컨트롤러 관리 API

컨트롤러 관리 API (Controller Admin API)

Pinot 컨트롤러 관리 UI 레퍼런스를 다루는 문서예요. http://<controller-host>:<port>/help의 컨트롤러 관리 UI는 Pinot의 관리 엔드포인트를 검사하고 실행하는 가장 빠른 방법이에요. 원시 curl 예시 대신 인터랙티브한 Swagger 화면을 원할 때 스키마, 테이블, 세그먼트 작업에 사용해요.

출처: 문서

본문

컨트롤러 관리 UI http://<controller-host>:<port>/help는 Pinot의 관리 엔드포인트를 검사하고 실행하는 가장 빠른 방법이에요. 원시 curl 예시 대신 인터랙티브한 Swagger 화면을 원할 때 스키마, 테이블, 세그먼트 작업에 사용해요.

컨트롤러 인증이 활성화되어 있다면, 각 요청을 수동으로 편집하는 대신 Swagger UI의 Authorize 컨트롤을 사용해 세션 한 번에 Authorization 헤더를 설정해요. Basic 인증에는 Basic <token>을, 배포가 같은 헤더에 bearer 토큰을 사용한다면 Bearer <token>을 입력해요.

다루는 내용 (What It Covers)

영역	일반적인 작업
테이블 (Tables)	테이블 구성 나열, 검사, 삭제, 업데이트
스키마 (Schemas)	스키마 나열, 검사, 생성, 삭제
세그먼트 (Segments)	세그먼트 나열, 검사, 업로드, 리로드

운영 알림 (Operational Reminder)

컨트롤러 API는 관리 작업용이에요. 컨트롤러 UI가 쿼리 콘솔도 노출하더라도, Pinot 쿼리에는 브로커 쿼리 API를 사용해요.

Pinot 관리 UI에는 클러스터를 운영·관리하는 데 필요한 모든 API가 포함돼 있어요. 헬스 체크, 인스턴스 관리, 스키마·테이블 관리, 데이터 세그먼트 관리 등 Pinot 클러스터 관리를 위한 API 모음을 제공해요.

참고: 컨트롤러 API는 주로 관리 작업용이에요. UI 콘솔이 쿼리 콘솔에서 쿼리를 실행할 때 Pinot를 쿼리하긴 하지만, Pinot 쿼리에는 Broker 쿼리 API를 사용해요.

클러스터의 테이블을 살펴보려면 Table -> List all tables in cluster로 가서 Try it out!을 클릭해요. 여기에 baseballStats 테이블이 나열된 걸 볼 수 있어요. 또한 컨트롤러 API로 만든 정확한 curl 호출도 볼 수 있어요.

테이블 구성을 보려면 Tables -> Get/Enable/Disable/Drop a table로 가서 테이블 이름에 baseballStats를 입력하고 Try it out!을 클릭해요.

클러스터의 스키마를 살펴보려면 Schema -> List all schemas in the cluster로 가서 Try it out!을 클릭해요. 이 목록에서 baseballStats라는 스키마를 볼 수 있어요.

스키마를 보려면 Schema -> Get a schema로 가서 스키마 이름에 baseballStats를 입력하고 Try it out!을 클릭해요.

{
  "schemaName": "baseballStats",
  "dimensionFieldSpecs": [
    { "name": "playerID", "dataType": "STRING" },
    { "name": "yearID", "dataType": "INT" },
    { "name": "teamID", "dataType": "STRING" },
    { "name": "league", "dataType": "STRING" },
    { "name": "playerName", "dataType": "STRING" }
  ],
  "metricFieldSpecs": [
    { "name": "playerStint", "dataType": "INT" },
    { "name": "numberOfGames", "dataType": "INT" },
    { "name": "numberOfGamesAsBatter", "dataType": "INT" },
    { "name": "AtBatting", "dataType": "INT" },
    { "name": "runs", "dataType": "INT" },
    { "name": "hits", "dataType": "INT" },
    { "name": "doules", "dataType": "INT" },
    { "name": "tripples", "dataType": "INT" },
    { "name": "homeRuns", "dataType": "INT" },
    { "name": "runsBattedIn", "dataType": "INT" },
    { "name": "stolenBases", "dataType": "INT" },
    { "name": "caughtStealing", "dataType": "INT" },
    { "name": "baseOnBalls", "dataType": "INT" },
    { "name": "strikeouts", "dataType": "INT" },
    { "name": "intentionalWalks", "dataType": "INT" },
    { "name": "hitsByPitch", "dataType": "INT" },
    { "name": "sacrificeHits", "dataType": "INT" },
    { "name": "sacrificeFlies", "dataType": "INT" },
    { "name": "groundedIntoDoublePlays", "dataType": "INT" },
    { "name": "G_old", "dataType": "INT" }
  ]
}

마지막으로 클러스터의 데이터 세그먼트를 보려면 List all segments로 가서 테이블 이름에 baseballStats를 입력하고 Try it out!을 클릭해요. 이 테이블에는 baseballStats_OFFLINE_0이라는 세그먼트가 1개 있어요.

테이블·스키마 삭제 (Deleting tables and schemas)

REST API 또는 Pinot 데이터 탐색기 UI를 사용해 테이블과 스키마를 삭제할 수 있어요.

API 사용 (Using the API)

테이블을 삭제하려면 /tables/{tableName}에 DELETE 요청을 보내요. 기본적으로 세그먼트는 삭제된 세그먼트 영역으로 이동하며 영구 삭제 전에 일정 기간(기본 7일) 보존돼요. 보존 없이 즉시 삭제하려면 retention=0d를 전달해요:

curl -X DELETE "http://localhost:9000/tables/baseballStats?retention=0d" -H "accept: application/json"

테이블 삭제 후 스키마도 삭제하려면 별도의 DELETE 요청을 보내요:

curl -X DELETE "http://localhost:9000/schemas/baseballStats" -H "accept: application/json"

retention=0d를 사용하면 복구 가능성 없이 모든 데이터가 즉시 영구 삭제돼요. 데이터가 더 이상 필요 없는 개발·테스트·정리 시나리오에서만 사용하세요.

테이블 삭제 API와 파라미터에 대한 자세한 내용은 컨트롤러 API 예시를 보세요.

데이터 탐색기 UI 사용 (Using the Data Explorer UI)

Pinot 데이터 탐색기에서 테이블로 이동해 Delete Table을 클릭해요. 삭제 대화상자는 두 가지 옵션을 제공해요:

Delete Immediately -- 기본 세그먼트 보존 기간을 건너뛰고 모든 세그먼트를 즉시 삭제해요. API에서 retention=0d를 전달하는 것과 동일해요. 기본 삭제 작업이 타임아웃될 수 있는 대형 테이블에 유용해요.
Delete Schema -- 테이블 삭제 성공 후 연결된 스키마도 삭제해요. 같은 스키마를 사용하는 다른 테이블이 없을 때만 동작해요.

Pinot 클러스터에 데이터를 넣으려면 테이블, 스키마, 세그먼트가 필요하다는 걸 이제 눈치챘을 거예요. 자신의 데이터를 위해 첫 테이블·스키마, 이어서 첫 배치 수집으로 계속 진행하세요.

이 페이지에서 다룬 내용 (What this page covered)

컨트롤러 Swagger UI 진입점
컨트롤러 UI에 속하는 관리 작업
브로커 쿼리 API가 여전히 SQL 실행을 담당하는 이유

다음 단계 (Next step)

Swagger UI로 엔드포인트 형태를 확인한 뒤, 정확한 curl 페이로드가 필요하면 컨트롤러 API 예시 페이지로 이동하세요.

컨트롤러 관리 API