数据湖入门 - ClickHouse Documentation

简而言之本指南通过实践演示如何查询数据湖表、使用 MergeTree 对其进行加速，以及将结果回写到 Iceberg。所有步骤均使用公开数据集，并同时适用于 Cloud 和 OSS。

本指南中的截图来自 ClickHouse Cloud 的 SQL 控制台。所有查询均适用于 Cloud 和自管理部署。

直接查询 Iceberg 数据

最快的开始方式是使用 icebergS3() table function——将其指向 S3 中的 Iceberg 表，即可立即发起查询，无需任何设置。查看 schema：

DESCRIBE icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

执行查询：

SELECT
    url,
    count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

ClickHouse 直接从 S3 读取 Iceberg 元数据，并自动推断 schema。同样的方法也适用于 deltaLake()、hudi() 和 paimon()。了解更多： 直接查询开放表格式涵盖这四种格式、用于分布式读取的集群变体，以及存储后端选项 (S3、Azure、HDFS、本地) 。

创建持久化表

如需重复访问，可使用 Iceberg 表引擎创建一个表，这样就无需每次都传递 path。数据仍保存在 S3 中，不会发生数据复制：

CREATE TABLE hits_iceberg
    ENGINE = IcebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')

现在可以像查询其他 ClickHouse 表一样查询它：

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

该表引擎支持数据缓存、元数据缓存、schema 演化和时间旅行。有关表引擎功能的详细信息，请参阅直接查询指南；如需查看完整的功能比较，请参阅支持矩阵。

连接到目录

大多数组织都会通过数据目录管理 Iceberg 表，以集中管理表元数据并进行数据发现。ClickHouse 支持使用 DataLakeCatalog 数据库引擎连接到你的目录，并将目录中的所有表公开为一个 ClickHouse 数据库。这种方式扩展性更好，因此随着新的 Iceberg 表不断创建，无需额外操作，即可始终在 ClickHouse 中访问它们。下面是一个连接到 AWS Glue 的示例：

CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = '<your-region>',
    aws_access_key_id = '<your-access-key>',
    aws_secret_access_key = '<your-secret-key>'

每种目录类型都需要单独的连接设置——有关受支持目录及其配置选项的完整列表，请参阅目录指南。浏览表并执行查询：

SHOW TABLES FROM my_lake;

SELECT count(*) FROM my_lake.`<database>.<table>`

由于 ClickHouse 原生不支持多个命名空间，因此 <database>.<table> 必须用反引号括起来。

了解更多： 连接到数据目录介绍了完整的 Unity Catalog 配置流程，并提供了 Delta 和 Iceberg 示例。

执行查询

无论你在上文使用的是哪种方式——表函数、表引擎还是 catalog——同一套 ClickHouse SQL 都适用于这三者：

-- 表函数
SELECT url, count() AS cnt
FROM icebergS3('https://datasets-documentation.s3.amazonaws.com/lake_formats/iceberg/')
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- 表引擎
SELECT url, count() AS cnt
FROM hits_iceberg
GROUP BY url ORDER BY cnt DESC LIMIT 5

-- 目录
SELECT url, count() AS cnt
FROM my_lake.`<database>.<table>`
GROUP BY url ORDER BY cnt DESC LIMIT 5

查询语法完全一致——只有 FROM 子句会发生变化。无论使用哪个数据源，所有 ClickHouse SQL 函数、JOIN 和聚合的用法都相同。

将部分数据加载到 ClickHouse

直接查询 Iceberg 很方便，但其性能受限于网络吞吐量和文件布局。对于分析型工作负载，建议将数据加载到原生 MergeTree 表中。首先，对 Iceberg 表运行带过滤条件的查询，建立一个基线：

SELECT
    url,
    count() AS cnt
FROM hits_iceberg
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

此查询会扫描 S3 中的整个数据集，因为 Iceberg 无法识别 counterid 过滤条件——预计需要几秒钟。现在创建一个 MergeTree 表并加载数据：

CREATE TABLE hits_clickhouse
(
    url String,
    eventtime DateTime,
    counterid UInt32
)
ENGINE = MergeTree()
ORDER BY (counterid, eventtime);

INSERT INTO hits_clickhouse
SELECT url, eventtime, counterid
FROM hits_iceberg

针对 MergeTree 表再次运行相同的查询：

SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
WHERE counterid = 38
GROUP BY url
ORDER BY cnt DESC
LIMIT 5

由于 counterid 是 ORDER BY 键中的第一列，ClickHouse 的稀疏主索引可以直接跳到相关粒度——只读取 counterid = 38 对应的行，而不必扫描全部 1 亿行。因此，查询速度会大幅提升。加速分析指南在此基础上进一步介绍了 LowCardinality 类型、全文索引和优化后的排序键，并展示了在一个 2.83 亿行数据集上实现 约 40 倍性能提升 的效果。了解更多：使用 MergeTree 加速分析涵盖了 schema 优化、全文索引，以及完整的性能优化前后对比。

回写到 Iceberg

ClickHouse 还可以将数据回写到 Iceberg 表，从而支持反向 ETL 工作流——发布聚合结果或数据子集，供其他工具 (Spark、Trino、DuckDB 等) 使用。创建一个用于输出的 Iceberg 表：

CREATE TABLE output_iceberg
(
    url String,
    cnt UInt64
)
ENGINE = IcebergS3('https://your-bucket.s3.amazonaws.com/output/', 'access_key', 'secret_key')

写入聚合后的结果：

SET allow_experimental_insert_into_iceberg = 1;

INSERT INTO output_iceberg
SELECT
    url,
    count() AS cnt
FROM hits_clickhouse
GROUP BY url
ORDER BY cnt DESC

生成的 Iceberg 表可由任何兼容 Iceberg 的 engine 读取。了解更多：将数据写入开放表格式介绍了如何使用 UK Price Paid dataset 写入原始数据和聚合结果，包括将 ClickHouse 类型映射到 Iceberg 时的 schema 注意事项。

后续步骤

现在你已经看完了完整的工作流程，可以进一步深入了解各个部分：

直接查询 — 四种格式、集群方案、表引擎、缓存
连接到目录 — 完整的 Unity Catalog 演练，涵盖 Delta 和 Iceberg
加速分析 — schema 优化、索引、约 40 倍提速演示
写入数据湖 — 原始写入、聚合写入、类型映射
支持矩阵 — 不同格式和存储后端的功能对比

​直接查询 Iceberg 数据

​创建持久化表

​连接到目录

​执行查询

​将部分数据加载到 ClickHouse

​回写到 Iceberg

​后续步骤

直接查询 Iceberg 数据

创建持久化表

连接到目录

执行查询

将部分数据加载到 ClickHouse

回写到 Iceberg

后续步骤