카탈로그 연결하기

ClickHouse를 데이터 카탈로그에 연결해서 전체 카탈로그를 하나의 데이터베이스로 노출하고, 개별 테이블 경로를 몰라도 전체 SQL로 조회하는 방법을 살펴봐요.

출처: 문서

본문

이전 섹션에서 스토리지 경로를 직접 전달해 오픈 테이블 포맷을 조회했어요. 실제로는 대부분의 조직이 데이터 카탈로그를 통해 테이블 메타데이터를 관리해요. 데이터 카탈로그는 테이블 위치, 스키마, 파티션을 추적하는 중앙 레지스트리예요. DataLakeCatalog 데이터베이스 엔진을 사용해 ClickHouse를 카탈로그에 연결하면, 전체 카탈로그가 ClickHouse 데이터베이스로 노출돼요. 카탈로그의 모든 테이블이 자동으로 나타나고 완전한 ClickHouse SQL로 조회할 수 있어요. 개별 테이블 경로를 알거나 테이블별로 자격 증명을 관리할 필요가 없어요. 이 가이드에서는 Databricks Unity Catalog에 연결하는 과정을 안내할게요. ClickHouse는 다음 카탈로그들도 지원하니, 전체 설정 방법은 각 참조 가이드를 확인해 주세요:

카탈로그	참조 가이드
AWS Glue	AWS Glue catalog
Iceberg REST Catalog	REST catalog
Lakekeeper	Lakekeeper catalog
Project Nessie	Nessie catalog
Microsoft OneLake	Fabric OneLake
SeaweedFS	SeaweedFS catalog

Unity Catalog에 연결하기

예시를 위해 Unity Catalog를 사용할게요. Databricks Unity Catalog는 Databricks lakehouse 데이터에 대한 중앙 집중식 거버넌스를 제공해요. Databricks는 lakehouse에 여러 데이터 포맷을 지원해요. ClickHouse를 사용하면 외부 스토리지 위치를 사용하는 Unity Catalog의 Delta 및 Iceberg 테이블을 조회할 수 있어요.

이 통합은 현재 AWS에서만 지원돼요. Unity Catalog가 해당 위치에 대한 자격 증명 판매(credential vending)를 제공하지 않기 때문에, Databricks 관리형 스토리지의 테이블은 지원되지 않아요. 자세한 내용은 Unity Catalog 참조를 확인해 주세요.

Databricks에서 Unity 구성하기

ClickHouse가 Unity Catalog와 상호작용하게 하려면, Unity Catalog가 외부 리더와의 상호작용을 허용하도록 구성되어 있어야 해요. 이는 “Enable external data access to Unity Catalog” 가이드를 따라 달성할 수 있어요. 외부 접근을 활성화하는 것 외에도, 통합을 구성하는 주체(principal)가 테이블이 있는 스키마에 대해 EXTERNAL USE SCHEMA 권한을 가지고 있어야 해요. 카탈로그가 구성되면 ClickHouse용 자격 증명을 생성해야 해요. Unity와의 상호작용 방식에 따라 두 가지 방법을 사용할 수 있어요:

Iceberg 클라이언트의 경우 서비스 주체(service principal)로 인증해요.
Delta 클라이언트의 경우 개인 액세스 토큰(PAT)을 사용해요.

카탈로그에 연결하기

자격 증명이 있으면 관련 엔드포인트에 연결해서 Iceberg 또는 Delta 테이블을 조회할 수 있어요.

Delta
Iceberg

Delta 포맷의 데이터에 접근하려면 Unity catalog를 사용해야 해요.

SET allow_experimental_database_unity_catalog = 1;

CREATE DATABASE unity
ENGINE = DataLakeCatalog('https://<workspace-id>.cloud.databricks.com/api/2.1/unity-catalog')
SETTINGS warehouse = 'CATALOG_NAME', catalog_credential = '<PAT>', catalog_type = 'unity';

SET allow_database_iceberg = 1;

CREATE DATABASE unity
ENGINE = DataLakeCatalog('https://<workspace-id>.cloud.databricks.com/api/2.1/unity-catalog/iceberg-rest')
SETTINGS catalog_type = 'rest', catalog_credential = '<client-id>:<client-secret>', warehouse = 'workspace',
oauth_server_uri = 'https://<workspace-id>.cloud.databricks.com/oidc/v1/token', auth_scope = 'all-apis,sql';

테이블 나열하기

카탈로그에 연결이 확립되면 테이블을 나열할 수 있어요.

SHOW TABLES FROM unity

┌─name───────────────────────────────────────────────┐
│ unity.logs                                         │
│ unity.single_day_log                               │
└────────────────────────────────────────────────────┘

31 rows in set.

테이블 스키마 살펴보기

표준 SHOW CREATE TABLE 명령을 사용해 테이블이 어떻게 생성되었는지 볼 수 있어요.

백틱 필요 - 네임스페이스와 테이블 이름을 백틱으로 감싸서 지정해야 한다는 점에 유의하세요. ClickHouse는 네임스페이스를 하나 이상 지원하지 않아요.

다음은 REST Iceberg 카탈로그를 조회한다고 가정할게요:

SHOW CREATE TABLE unity.`icebench.single_day_log`

CREATE TABLE unity.`icebench.single_day_log`
(
    `pull_request_number` Nullable(Int64),
    `commit_sha` Nullable(String),
    `check_start_time` Nullable(DateTime64(6, 'UTC')),
    `check_name` Nullable(String),
    `instance_type` Nullable(String),
    `instance_id` Nullable(String),
    `event_date` Nullable(Date32),
    `event_time` Nullable(DateTime64(6, 'UTC')),
    `event_time_microseconds` Nullable(DateTime64(6, 'UTC')),
    `thread_name` Nullable(String),
    `thread_id` Nullable(Decimal(20, 0)),
    `level` Nullable(String),
    `query_id` Nullable(String),
    `logger_name` Nullable(String),
    `message` Nullable(String),
    `revision` Nullable(Int64),
    `source_file` Nullable(String),
    `source_line` Nullable(Decimal(20, 0)),
    `message_format_string` Nullable(String)
)
ENGINE = Iceberg('s3://...')

테이블 조회하기

모든 ClickHouse 함수가 지원돼요. 다시 말하지만, 네임스페이스와 테이블 이름은 백틱으로 구분해야 해요.

SELECT count()
FROM unity.`icebench.single_day_log`

┌───count()─┐
│ 282634391 │ -- 282.63 million
└───────────┘

1 row in set. Elapsed: 1.265 sec.

전체 설정 방법은 Unity catalog 참조 가이드를 확인해 주세요.

카탈로그 연결하기