跳转到主内容
跳转到主内容

连接到数据目录

在上一节中，你通过直接传递存储路径来查询开放表格式的表。在实际场景中，大多数组织会通过**数据目录（data catalog）**来管理表的元数据——这是一个集中式注册系统，用于跟踪表的位置、模式（schema）和分区。 当你使用 DataLakeCatalog 数据库引擎将 ClickHouse 连接到目录时，整个目录会呈现为一个 ClickHouse 数据库。目录中的每一张表都会自动呈现出来，并且可以使用完整的 ClickHouse SQL 进行查询——无需了解各个表的具体路径，也不必为每张表单独管理凭证。

本指南将演示如何连接到 Databricks Unity Catalog。ClickHouse 还支持以下目录——完整的配置步骤请参考各自的参考指南：

CatalogReference guide
AWS GlueAWS Glue catalog
Iceberg REST CatalogREST catalog
LakekeeperLakekeeper catalog
Project NessieNessie catalog
Microsoft OneLakeFabric OneLake

连接到 Unity Catalog​

Beta feature. Learn more.

作为示例，我们将使用 Unity Catalog。

Databricks Unity Catalog 为 Databricks Lakehouse 数据提供集中式治理。

Databricks 为其 Lakehouse 支持多种数据格式。借助 ClickHouse，你可以将 Unity Catalog 中的表作为 Delta 和 Iceberg 表进行查询。

注意

与 Unity Catalog 的集成适用于托管表和外部表。 此集成目前仅支持在 AWS 上使用。

在 Databricks 中配置 Unity​

要允许 ClickHouse 与 Unity Catalog 交互，需要确保 Unity Catalog 已配置为允许与外部读取方（external reader）交互。可以按照“Enable external data access to Unity Catalog” 指南进行配置。

除了启用外部访问（external access）之外，还要确保用于配置该集成的主体（principal）在包含这些表的 schema 上拥有 EXTERNAL USE SCHEMA 权限。

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

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

  • 对于 Delta 客户端，使用个人访问令牌（Personal Access Token，PAT）。

连接到目录​

使用这些凭证，您可以连接到相应的端点，查询 Iceberg 或 Delta 表。

应使用 Unity Catalog 来访问 Delta 格式的数据。

SET allow_experimental_database_unity_catalog = 1;

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';

列出表​

完成与目录的连接后，您就可以列出其中的表。

SHOW TABLES FROM unity

┌─name───────────────────────────────────────────────┐
│ unity.logs                                         │
│ unity.single_day_log                               │
└────────────────────────────────────────────────────┘

31 rows in set.

浏览表结构​

我们可以使用标准的 SHOW CREATE TABLE 命令来查看这些表是如何创建的。

必须使用反引号

注意需要同时指定命名空间和表名，并用反引号包裹——ClickHouse 不支持多个命名空间。

下面的示例假定在对 REST Iceberg 目录进行查询：

SHOW CREATE TABLE unity.`icebench.single_day_log`

CREATE TABLE unity.`icebench.single_day_log`
(
    `pull_request_number` Nullable(Int64),
    `commit_sha` Nullable(String),
    `check_start_time` Nullable(DateTime64(6, 'UTC')),
    `check_name` Nullable(String),
    `instance_type` Nullable(String),
    `instance_id` Nullable(String),
    `event_date` Nullable(Date32),
    `event_time` Nullable(DateTime64(6, 'UTC')),
    `event_time_microseconds` Nullable(DateTime64(6, 'UTC')),
    `thread_name` Nullable(String),
    `thread_id` Nullable(Decimal(20, 0)),
    `level` Nullable(String),
    `query_id` Nullable(String),
    `logger_name` Nullable(String),
    `message` Nullable(String),
    `revision` Nullable(Int64),
    `source_file` Nullable(String),
    `source_line` Nullable(Decimal(20, 0)),
    `message_format_string` Nullable(String)
)
ENGINE = Iceberg('s3://...')

查询表​

支持所有 ClickHouse 函数。同样，命名空间和表名应使用反引号（`）括起来。


SELECT count()
FROM unity.`icebench.single_day_log`

┌───count()─┐
│ 282634391 │ -- 282.63 million
└───────────┘

1 row in set. Elapsed: 1.265 sec.

如需完整的设置步骤，请参阅 Unity Catalog 参考指南。