DataLakeCatalog

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_database_iceberg = 1;
SET allow_database_unity_catalog = 1;
SET allow_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；启用 `use_unity_catalog_v2` 时为 Delta 和 Iceberg) 、`rest` (Iceberg) 、`hive`、`onelake` (Iceberg)、`delta_sharing` (Iceberg，扁平命名空间)、`horizon` (Snowflake Horizon Iceberg REST)
`warehouse`	在目录中使用的仓库/数据库名称。
`catalog_credential`	目录的身份验证凭据 (例如 API key 或令牌)
`use_unity_catalog_v2`	适用于 `catalog_type = 'unity'`：使用新的实现，可同时支持 Delta Lake 表和 Iceberg 表。默认值：`false`。可在 `CREATE` 时设置，也可通过 `ALTER DATABASE ... MODIFY SETTING` 为已有数据库修改此设置。
`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
使用 Delta Lake 和 Iceberg 表的 Unity Catalog 设置 use_unity_catalog_v2 = 1 后，unity 目录可同时提供 Delta Lake 和 Iceberg 表，并自动识别每个表的格式。

CREATE DATABASE database_name
ENGINE = DataLakeCatalog('https://<workspace>.cloud.databricks.com/api/2.1/unity-catalog')
SETTINGS
    catalog_type = 'unity',
    use_unity_catalog_v2 = 1,
    warehouse = 'my_catalog',
    catalog_credential = '<client_id>:<client_secret>';
SHOW TABLES FROM database_name;
SELECT count() FROM database_name.`schema_name.table_name`;

catalog_credential 接受格式为 <client_id>:<client_secret> 的 OAuth 服务主体凭据、个人访问令牌 (dapi...) 或预先获取的 OAuth 令牌。

Glue Catalog
OneLake Catalog 可通过启用 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 不会刷新该令牌，因此其过期后必须重新创建数据库。

SQL 参考文档

数据类型

引擎

函数

格式

设置

系统表

数据湖

支持的目录

创建数据库

示例

​支持的目录

​创建数据库

​示例

支持的目录

创建数据库

示例