Unity Catalog

本指南将逐步介绍如何使用 ClickHouse 和 Unity Catalog 查询存储在 S3 存储桶中的数据。

ClickHouse 支持与多个目录 (如 Unity、Glue、Polaris 等) 集成。本指南将逐步说明如何使用 ClickHouse 和 Unity Catalog 查询由 Databricks 管理的数据。

Databricks 的湖仓支持多种数据格式。借助 ClickHouse，您可以以 Delta 和 Iceberg 两种方式查询 Unity Catalog 表。

由于此功能仍处于 Experimental 阶段，您需要使用以下命令启用它： SET allow_experimental_database_unity_catalog = 1;

​

在 Databricks 中配置 Unity

要让 ClickHouse 与 Unity Catalog 交互，您需要确保 Unity Catalog 已配置为允许外部读取方访问。为此，可按照“启用对 Unity Catalog 的外部数据访问”指南进行配置。

完成目录 配置后，您必须为 ClickHouse 生成凭据。根据您与 Unity 的交互方式不同，可以使用以下两种方法：

• 对于 Iceberg 客户端，使用 service principal 进行身份验证。

• 对于 Delta 客户端，使用个人访问令牌 (PAT) 。

​

所需的 PAT 令牌权限

使用 PAT 进行读访问时，该令牌必须具备允许 ClickHouse 列出并读取 Unity Catalog 元数据的权限。请确保该 PAT 至少具有 EXTERNAL USE SCHEMA 权限，以及该表上的 SELECT 权限、其父 目录 上的 USE CATALOG 权限和其父 schema 上的 USE SCHEMA 权限。

​

创建 Unity Catalog 与 ClickHouse 之间的连接

在完成 Unity Catalog 配置并启用身份验证后，建立 ClickHouse 与 Unity Catalog 之间的连接。

​

读取 Delta

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'

​

读取 Iceberg 表

要访问托管的 Iceberg 表：

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'

​

使用 ClickHouse 查询 Unity Catalog 中的表

完成连接配置后，你就可以开始通过 Unity Catalog 进行查询了。例如：

USE unity;

SHOW TABLES;

┌─name───────────────────────────────────────────────┐
│ clickbench.delta_hits                              │
│ demo.fake_user                                     │
│ information_schema.catalog_privileges              │
│ information_schema.catalog_tags                    │
│ information_schema.catalogs                        │
│ information_schema.check_constraints               │
│ information_schema.column_masks                    │
│ information_schema.column_tags                     │
│ information_schema.columns                         │
│ information_schema.constraint_column_usage         │
│ information_schema.constraint_table_usage          │
│ information_schema.information_schema_catalog_name │
│ information_schema.key_column_usage                │
│ information_schema.parameters                      │
│ information_schema.referential_constraints         │
│ information_schema.routine_columns                 │
│ information_schema.routine_privileges              │
│ information_schema.routines                        │
│ information_schema.row_filters                     │
│ information_schema.schema_privileges               │
│ information_schema.schema_tags                     │
│ information_schema.schemata                        │
│ information_schema.table_constraints               │
│ information_schema.table_privileges                │
│ information_schema.table_tags                      │
│ information_schema.tables                          │
│ information_schema.views                           │
│ information_schema.volume_privileges               │
│ information_schema.volume_tags                     │
│ information_schema.volumes                         │
│ uniform.delta_hits                                 │
└────────────────────────────────────────────────────┘

SHOW TABLES

┌─name───────────────┐
│ uniform.delta_hits │
└────────────────────┘

要查询某个表：

SELECT count(*) FROM `uniform.delta_hits`

必须使用反引号

必须使用反引号，因为 ClickHouse 仅支持一个命名空间。

要查看该表的 DDL：

SHOW CREATE TABLE `uniform.delta_hits`

CREATE TABLE unity_uniform.`uniform.delta_hits`
(
    `WatchID` Int64,
    `JavaEnable` Int32,
    `Title` String,
    `GoodEvent` Int32,
    `EventTime` DateTime64(6, 'UTC'),
    `EventDate` Date,
    `CounterID` Int32,
    `ClientIP` Int32,
    ...
    `FromTag` String,
    `HasGCLID` Int32,
    `RefererHash` Int64,
    `URLHash` Int64,
    `CLID` Int32
)
ENGINE = Iceberg('s3://<path>);

​

将数据从数据湖导入 ClickHouse

如果需要将 Databricks 中的数据导入 ClickHouse，请先创建一个本地 ClickHouse 表：

CREATE TABLE hits
(
    `WatchID` Int64,
    `JavaEnable` Int32,
    `Title` String,
    `GoodEvent` Int32,
    `EventTime` DateTime64(6, 'UTC'),
    `EventDate` Date,
    `CounterID` Int32,
    `ClientIP` Int32,
    ...
    `FromTag` String,
    `HasGCLID` Int32,
    `RefererHash` Int64,
    `URLHash` Int64,
    `CLID` Int32
)
PRIMARY KEY (CounterID, EventDate, UserID, EventTime, WatchID);

然后通过 INSERT INTO SELECT 从您的 Unity Catalog 表中加载数据：

INSERT INTO hits SELECT * FROM unity_uniform.`uniform.delta_hits`;