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，扁平命名空间)
warehouse 在目录中使用的仓库/数据库名称。
catalog_credential 目录的身份验证凭据 (例如 API key 或令牌)
auth_header 用于与目录服务进行身份验证的自定义 HTTP 请求头
auth_scope 用于身份验证的 OAuth2 作用域 (如果使用 OAuth)
storage_endpoint 底层存储的端点 URL
oauth_server_uri 用于身份验证的 OAuth2 授权服务器 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。设置后，如果同时提供了 aws_access_key_id 和 aws_secret_access_key，ClickHouse 会使用其中的基础凭据调用 AWS STS AssumeRole；否则会使用默认的 AWS credential chain (该角色必须信任服务器运行所使用的身份)。
aws_role_session_name 用于 AWS STS AssumeRole 调用的会话名称。可选；默认为 ClickHouseSession。
aws_external_id 传递给 AWS STS AssumeRole 的外部 ID，需要与该角色 trust policy 上的 sts:ExternalId 条件匹配。当该角色归第三方所有时 (例如 ClickHouse Cloud) ，请使用此项。
region 服务所在的 AWS 区域 (例如 us-east-1)
dlf_access_key_id 用于访问 DLF 的 access key ID
dlf_access_key_secret 用于访问 DLF 的 access key Secret
force_add_bucket 根据目录提供的表位置和 storage_endpoint 构造对象存储 URL 时，即使端点中已包含 bucket/container 名称，也会在前面再加上该名称。默认值：false。对于返回不带 bucket 且需要在 URL 构造阶段补上的目录，请将其设为 true (Polaris 风格路径) 。

示例

有关使用 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_bearer_token 设置为预先获取的 Bearer 令牌 (作用域为 https://storage.azure.com) ，而不要使用 onelake_client_id/onelake_client_secret。ClickHouse 不会刷新该令牌，因此其过期后必须重新创建数据库。

Navigation