Catalog

Catalog

Druid의 카탈로그에 저장된 메타데이터를 구성, 갱신, 조회, 관리할 수 있게 해주는 실험적(EXPERIMENTAL) 확장 기능이에요. 현재는 테이블에 대한 메타데이터만 카탈로그에 저장돼요.

출처: 문서

본문

이 기능은 오랜 기간 실행되는 다양한 Druid 클러스터에서 아직 광범위하게 테스트되지 않았기 때문에 대체로 실험적(EXPERIMENTAL) 기능으로 간주하세요.

이 확장 기능은 Druid 카탈로그에 저장된 메타데이터를 구성, 갱신, 조회, 관리할 수 있게 해줘요. 현재는 테이블에 대한 메타데이터만 카탈로그에 저장돼요. 이 확장 기능은 MSQ 기반 인제이션만 지원해요.

구성 (Configuration)

이 확장 기능을 사용하려면 extensions load list에 druid-catalog을 포함하세요.

카탈로그 메타데이터 (Catalog Metadata)

테이블 (Tables)

사용자는 컬럼 이름 집합과 각 데이터 타입, 그리고 다른 속성들과 함께 테이블을 정의할 수 있어요. 카탈로그에 정의된 테이블로 데이터를 인제스트할 때, DML 쿼리는 카탈로그에 정의된 테이블의 정의에 대해 검증돼요. 이를 통해 사용자는 정의에서 찾은 테이블의 속성을 생략할 수 있어 쿼리를 더 간결하고 작성하기 쉽게 만들어요. 또한 사용자는 테이블의 정의된 컬럼에 쓰이는 데이터 타입이 해당 컬럼의 정의와 일치하는지 확인할 수 있어, 테이블의 특정 컬럼에 예기치 않은 데이터가 쓰이는 오류를 최소화해요.

API 객체 (API Objects)

TableSpec

tableSpec은 테이블을 정의해요.

| Property | Type | Description | Required | Default | | type | String | the type of table. The only value supported at this time is datasource | yes | null | | properties | Map<String, Object> | the table's defined properties. see table properties | no | null | | columns | List< ColumnSpec > | the table's defined columns | no | null |

테이블 속성 (Table Properties)

| PropertyKeyName | PropertyValueType | Description | Required | Default | | segmentGranularity | String | determines how time-based partitioning is done. See Partitioning by time . Can specify any of the values as permitted for PARTITIONED BY . This property value may be overridden at query time, by specifying the PARTITIONED BY clause. | no | null | | sealed | boolean | require all columns in the table schema to be fully declared before data is ingested. Setting this to true will cause failure when DML queries attempt to add undefined columns to the table. | no | false |

ColumnSpec

| Property | Type | Description | Required | Default | | name | String | The name of the column | yes | null | | dataType | String | The type of the column. Can be any column data type that is available to Druid. Depends on what extensions are loaded. | no | null | | properties | Map<String, Object> | the column's defined properties. Non properties defined at this time. | no | null |

API (APIs)

테이블 생성 또는 갱신 (Create or update a table)

주어진 테이블 스펙을 포함하는 테이블을 갱신하거나 새로 생성해요.

URL
POST /druid/coordinator/v1/catalog/schemas/{schema}/tables/{name}
Request body

이 요청의 요청 객체는 TableSpec이에요.

Query parameters

이 엔드포인트는 낙관적 잠금(optimistic locking)을 적용하고 요청이 새 테이블을 생성하는 것이 아니라 갱신하기 위한 것임을 지정하는 일련의 선택적 query parameter를 지원해요. 기본적으로 query parameter를 설정하지 않으면, 지정된 스키마에 동일한 이름의 테이블이 이미 존재할 경우 이 요청은 오류를 반환해요.

| Parameter | Type | Description | | version | Long | the expected version of an existing table. The version must match. If not (or if the table does not exist), returns an error. | | overwrite | boolean | if true, then overwrites any existing table. Otherwise, the operation fails if the table already exists. |

Responses
  • 200 SUCCESS
  • 400 BAD REQUEST
  • 500 INTERNAL SERVER ERROR

성공적으로 제출된 테이블 스펙. 생성되거나 갱신된 테이블의 버전을 포함하는 객체를 반환해요:

{
    "version": 12345687
}

잘못된 요청으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}

예상치 못한 조건으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}
Sample request

다음 예제는 몇 가지 정의된 컬럼과 "P1D"의 정의된 세그먼트 granularity를 가진 sealed 테이블을 만드는 방법을 보여줘요.

curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/catalog/schemas/druid/tables/test_table" \
-X 'POST' \
--header 'Content-Type: application/json' \
--data '{
  "type": "datasource",
  "columns": [
    {
      "name": "__time",
      "dataType": "long"
    },
    {
      "name": "double_col",
      "dataType": "double"
    },
    {
      "name": "float_col",
      "dataType": "float"
    },
    {
      "name": "long_col",
      "dataType": "long"
    },
    {
      "name": "string_col",
      "dataType": "string"
    }
  ],
  "properties": {
    "segmentGranularity": "P1D",
    "sealed": true
  }
}'
Sample response
{
  "version": 1730965026295
}

테이블 조회 (Retrieve a table)

테이블을 조회해요.

URL
GET /druid/coordinator/v1/catalog/schemas/{schema}/tables/{name}
Responses
  • 200 SUCCESS
  • 400 BAD REQUEST
  • 500 INTERNAL SERVER ERROR

해당 테이블의 TableSpec을 성공적으로 조회했어요.

잘못된 요청으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}

예상치 못한 조건으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}
Sample request

다음 예제는 druid 스키마에서 test_table이라는 테이블을 조회하는 방법을 보여줘요:

curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/catalog/schemas/druid/tables/test_table"
Sample response

응답을 확인하세요.

{
  "id": {
    "schema": "druid",
    "name": "test_table"
  },
  "creationTime": 1730965026295,
  "updateTime": 1730965026295,
  "state": "ACTIVE",
  "spec": {
    "type": "datasource",
    "properties": {
      "segmentGranularity": "P1D",
      "sealed": true
    },
    "columns": [
      {
        "name": "__time",
        "dataType": "long"
      },
      {
        "name": "double_col",
        "dataType": "double"
      },
      {
        "name": "float_col",
        "dataType": "float"
      },
      {
        "name": "long_col",
        "dataType": "long"
      },
      {
        "name": "string_col",
        "dataType": "string"
      }
    ]
  }
}

테이블 삭제 (Delete a table)

테이블을 삭제해요.

URL
DELETE /druid/coordinator/v1/catalog/schemas/{schema}/tables/{name}
Responses
  • 200 SUCCESS
  • 400 BAD REQUEST
  • 500 INTERNAL SERVER ERROR

응답 본문 없음.

잘못된 요청으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}

예상치 못한 조건으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}
Sample request

다음 예제는 druid 스키마에서 test_table이라는 테이블을 삭제하는 방법을 보여줘요.

curl -X 'DELETE' "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/catalog/schemas/druid/tables/test_table"
Sample response

응답 본문 없음.

스키마 이름 목록 조회 (Retrieve list of schema names)

스키마 이름 목록을 조회해요.

URL
GET /druid/coordinator/v1/catalog/schemas
Responses
  • 200 SUCCESS
  • 400 BAD REQUEST
  • 500 INTERNAL SERVER ERROR

스키마 이름 목록을 성공적으로 조회했어요.

잘못된 요청으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}

예상치 못한 조건으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}
Sample request

다음 예제는 스키마 이름 목록을 조회하는 방법을 보여줘요.

curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/catalog/schemas"
Sample response
[
  "INFORMATION_SCHEMA",
  "druid",
  "ext",
  "lookups",
  "sys",
  "view"
]

스키마의 테이블 이름 목록 조회 (Retrieve list of table names in schema)

스키마의 테이블 이름 목록을 조회해요.

URL
GET /druid/coordinator/v1/catalog/schemas/{schema}/tables
Responses
  • 200 SUCCESS
  • 400 BAD REQUEST
  • 500 INTERNAL SERVER ERROR

스키마에 속한 테이블 이름 목록을 성공적으로 조회했어요.

잘못된 요청으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}

예상치 못한 조건으로 인한 오류. 다음 형식으로 오류를 상세히 설명하는 JSON 객체를 반환해요:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error."
}
Sample request

다음 예제는 druid 스키마에 속한 테이블들의 모든 테이블 이름을 조회하는 방법을 보여줘요.

curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/catalog/schemas/druid/tables"
Sample response
[
  "test_table"
]

더 알아보기 (Learn more)