Horizon 카탈로그

Horizon 카탈로그 (Horizon catalog)

ClickHouse를 Snowflake Horizon Catalog에 연결해 Snowflake 관리형 Iceberg 테이블을 읽고 쓸 수 있는 방법을 살펴봐요.

출처: 문서

본문

ClickHouse는 Horizon이 노출하는 Iceberg REST API(Apache Polaris 기반)를 통해 Snowflake Horizon Catalog에 연결할 수 있어요. 이렇게 하면 catalog_type = 'horizon'이 포함된 DataLakeCatalog 데이터베이스 엔진을 사용해 ClickHouse에서 Snowflake 관리형 Iceberg 테이블을 읽고 쓸 수 있어요. Horizon은 Snowflake Open Catalog / 자체 호스팅 Polaris와 관련이 있지만 같지는 않아요:

이 기능은 베타이므로 SET allow_experimental_database_iceberg = 1;(또는 ClickHouse 버전에 따라 SET allow_database_iceberg = 1;)로 활성화해요.

사전 조건

• Snowflake 관리형 Iceberg 테이블이 있는 Snowflake 계정
• Horizon Iceberg REST 엔드포인트: https://<organization>-<account>.snowflakecomputing.com/polaris/api/catalog
• Iceberg 테이블에 대한 권한이 있는 Snowflake 역할(INSERT할 거면 쓰기 권한도)
• 다음 중 하나로 인증:
  • Programmatic Access Token(PAT)
  • 액세스 토큰으로 교환된 키-페어 JWT
  • 외부 OAuth 액세스 토큰(bearer auth_header로)
• ClickHouse에서 접근 가능한 오브젝트 스토리지(vended credentials 권장)
• DataLakeCatalog Iceberg 지원이 있는 ClickHouse

연결 만들기

옵션 A: Programmatic Access Token(권장)

SET allow_experimental_database_iceberg = 1;

CREATE DATABASE horizon_catalog
ENGINE = DataLakeCatalog('https://<org>-<account>.snowflakecomputing.com/polaris/api/catalog')
SETTINGS
    catalog_type = 'horizon',
    warehouse = 'ICEBERG_TEST_DB',
    catalog_credential = '<PAT>',
    auth_scope = 'session:role:DATA_ENGINEER',
    oauth_server_uri = 'https://<org>-<account>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens',
    vended_credentials = 1;

warehouse는Snowflake 데이터베이스 이름이어야 해요(Snowflake 가상 웨어하우스가 아님). 인용되지 않은 Snowflake 식별자는 대문자예요.

옵션 B: 사전 교환된 bearer 액세스 토큰

CREATE DATABASE horizon_catalog
ENGINE = DataLakeCatalog('https://<org>-<account>.snowflakecomputing.com/polaris/api/catalog')
SETTINGS
    catalog_type = 'horizon',
    warehouse = 'ICEBERG_TEST_DB',
    auth_header = 'Authorization: Bearer ***',
    vended_credentials = 1;

Iceberg 테이블 조회하기

USE horizon_catalog;
SHOW TABLES;

SELECT count(*) FROM `PUBLIC.test_table`;
SHOW CREATE TABLE `PUBLIC.test_table`;

실험적 테이블 네임스페이스가 활성화되지 않는 한, 네임스페이스(스키마)와 테이블은 일반적으로 SCHEMA.table로 주소가 지정돼요.

쓰기 경로

INSERT/UPDATE/DELETE 권한(그리고 테이블을 만들 때는 CREATE ICEBERG TABLE)이 있는 역할을 사용하면 ClickHouse가 같은 카탈로그를 통해 쓸 수 있어요:

-- Insert into an existing Snowflake-managed Iceberg table
INSERT INTO horizon_catalog.`PUBLIC.test_table`
SELECT
    number AS id,
    concat('name_', toString(number)) AS name
FROM numbers(100);

-- Create a new Iceberg table in the Horizon catalog (requires CREATE ICEBERG TABLE)
CREATE TABLE horizon_catalog.`PUBLIC.clickhouse_written`
(
    id Int64,
    name String
)
ENGINE = Iceberg;

정확한 CREATE TABLE 구문은 여러분의 버전에서 REST 카탈로그에 대한 ClickHouse Iceberg / DataLakeCatalog 쓰기 지원을 따르며, Snowflake의 권한 오류는 카탈로그 HTTP 오류로 표시돼요.

MergeTree로 로드하기

CREATE TABLE my_clickhouse_table
(
    id Int64,
    name String
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO my_clickhouse_table
SELECT * FROM horizon_catalog.`PUBLIC.test_table`;

더 알아보기 (Learn more)

• REST 카탈로그 (REST catalog)
• DataLakeCatalog 엔진 문서
• Unity Catalog