Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

DataLakeCatalog

View as MarkdownEdit this pageReport an issueSet up docs MCP

DataLakeCatalog 데이터베이스 엔진을 사용하면 ClickHouse를 외부 데이터 카탈로그에 연결하고, 데이터 복제 없이 오픈 테이블 포맷 데이터를 쿼리할 수 있습니다. 이를 통해 ClickHouse는 기존 데이터 레이크 인프라와 원활하게 연동되는 강력한 쿼리 엔진이 됩니다.

지원되는 카탈로그

DataLakeCatalog 엔진은 다음 카탈로그를 지원합니다:

  • AWS Glue Catalog - AWS 환경의 Iceberg 테이블에 사용
  • Databricks Unity Catalog - Delta Lake 및 Iceberg 테이블에 사용
  • Hive Metastore - 전통적인 Hadoop 생태계 카탈로그
  • REST Catalogs - Iceberg REST 사양을 지원하는 모든 카탈로그

데이터베이스 생성

DataLakeCatalog 엔진을 사용하려면 아래 관련 설정을 활성화해야 합니다:

SET allow_experimental_database_iceberg = 1;
SET allow_experimental_database_unity_catalog = 1;
SET allow_experimental_database_glue_catalog = 1;
SET allow_experimental_database_hms_catalog = 1;
SET allow_experimental_database_paimon_rest_catalog = 1;

DataLakeCatalog 엔진을 사용하는 데이터베이스는 다음 구문으로 생성할 수 있습니다:

CREATE DATABASE database_name
ENGINE = DataLakeCatalog(catalog_endpoint[, user, password])
SETTINGS
catalog_type,
[...]

다음 설정이 지원됩니다:

설정 설명
catalog_type 카탈로그 유형: glue, unity (Delta), rest (Iceberg), hive, onelake (Iceberg), delta_sharing (Iceberg, 플랫 네임스페이스), horizon (Snowflake Horizon Iceberg REST)
warehouse 카탈로그에서 사용할 웨어하우스/데이터베이스 이름입니다.
catalog_credential 카탈로그 인증에 사용할 자격 증명입니다(예: API Key 또는 토큰).
auth_header 카탈로그 서비스 인증에 사용할 사용자 지정 HTTP 헤더
auth_scope 인증용 OAuth2 스코프입니다(OAuth를 사용하는 경우).
storage_endpoint 기본 스토리지의 엔드포인트 URL입니다.
oauth_server_uri 인증에 사용할 OAuth2 authorization server의 URI입니다.
vended_credentials 카탈로그에서 제공된 자격 증명을 사용할지 여부를 나타내는 불리언 값입니다(AWS S3 및 Azure ADLS Gen2 지원).
aws_access_key_id S3/Glue 액세스에 사용할 AWS access key ID입니다(제공된 자격 증명을 사용하지 않는 경우).
aws_secret_access_key S3/Glue 액세스에 사용할 AWS secret access key입니다(제공된 자격 증명을 사용하지 않는 경우).
aws_role_arn AWS/Glue 액세스를 위해 Assume할 IAM role의 ARN입니다. 설정하면 ClickHouse는 aws_access_key_id와 aws_secret_access_key가 모두 제공된 경우 이를 기본 자격 증명으로 사용해 AWS STS AssumeRole을 호출하고, 그렇지 않으면 기본 AWS credential chain을 사용합니다(이 role은 server가 실행되는 아이덴티티를 신뢰하도록 구성되어야 합니다).
aws_role_session_name AWS STS AssumeRole 호출에 사용할 세션 이름입니다. 선택 사항이며, 기본값은 ClickHouseSession입니다.
aws_external_id role의 trust policy에 있는 sts:ExternalId 조건과 일치하도록 AWS STS AssumeRole에 전달되는 external ID입니다. role이 ClickHouse Cloud와 같은 제3자 소유인 경우 이를 사용합니다.
region 서비스의 AWS 리전입니다(예: us-east-1).
dlf_access_key_id DLF 액세스에 사용할 access key ID입니다.
dlf_access_key_secret DLF 액세스에 사용할 access key secret입니다.
force_add_bucket 카탈로그에서 제공한 테이블 location과 storage_endpoint를 사용해 객체 스토리지 URL을 구성할 때, 엔드포인트에 이미 포함되어 있더라도 버킷/container 이름을 앞에 추가합니다. 기본값: false. 버킷 없이 경로를 반환하므로 URL 구성 단계에서 버킷을 추가해야 하는 카탈로그(Polaris 스타일 경로)의 경우 true로 설정합니다.

예시

아래 섹션에서 DataLakeCatalog 엔진 사용 예시를 확인할 수 있습니다:

  • Unity Catalog
  • Glue Catalog
  • OneLake Catalog allow_experimental_database_iceberg 또는 allow_database_iceberg를 활성화하여 사용할 수 있습니다.
CREATE DATABASE database_name
ENGINE = DataLakeCatalog(catalog_endpoint)
SETTINGS
    catalog_type = 'onelake',
    warehouse = warehouse,
    onelake_tenant_id = tenant_id,
    oauth_server_uri = server_uri,
    auth_scope = auth_scope,
    onelake_client_id = client_id,
    onelake_client_secret = client_secret;
SHOW TABLES IN database_name;
SELECT count() from database_name.table_name;

클라이언트 시크릿을 공유하지 않고 인증하려면 onelake_client_id/onelake_client_secret 대신 onelake_bearer_token을 미리 발급받은 bearer 토큰(https://storage.azure.com 범위로 제한됨)으로 설정하십시오. ClickHouse는 토큰을 갱신하지 않으므로, 만료되면 데이터베이스를 다시 생성해야 합니다.

Navigation