数据湖入门

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

本指南中的截图来自 ClickHouse Cloud 的 SQL 控制台。所有查询均适用于 Cloud 和自管理部署。 ClickHouse 提供三种读取开放表格式的方式：表函数、表引擎，以及 DataLakeCatalog 数据库引擎。如果你的表位于数据目录中 (如 Glue、Unity Catalog、REST 等) ，请通过 DataLakeCatalog 连接，这样便可通过一个函数访问所有 Iceberg/Delta 表。下方的表函数和表引擎部分更适合临时查询，或者在已知具体存储路径且不使用目录时使用。

直接查询 Iceberg 数据

最快的开始方式——尤其适用于临时查询，或不使用 catalog 时——是使用 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、本地) 。

创建持久化表引擎

如果不使用 catalog，但需要反复查询同一路径，可使用 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 演化和时间旅行。有关表引擎功能的详细信息，请参阅直接查询指南；如需查看完整的功能比较，请参阅支持矩阵。

连接到目录

如果你的组织使用数据目录，这是我们推荐的集成方式。目录可以集中管理表元数据并进行数据发现——无需为每个存储 path 分别管理表定义，只需通过 DataLakeCatalog 数据库引擎连接一次即可。目录中的每个表都会显示为一个 ClickHouse 表，包括在你创建连接后于 upstream 新增的表。

使用目录时推荐采用此方式对于使用 Glue、Unity Catalog、REST 和其他受支持目录的 production 工作负载，建议使用 DataLakeCatalog。当你已知特定 path 时，表函数和表引擎可以正常工作，但随着目录不断增长，它们不会保持同步，并且需要为每个表分别提供 credentials 或 path。

下面是一个连接到 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 示例。

执行查询

无论你在上文使用的是哪种方式——表函数、表引擎还是 DataLakeCatalog——同一套 ClickHouse SQL 都适用于这三者。在生产环境中，如果使用的是目录，应通过 DataLakeCatalog 数据库执行查询；其他示例仍适用于快速测试和基于 path 的访问：

-- Table function
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

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

-- Catalog
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 注意事项。

后续步骤

现在你已经了解了完整工作流程，接下来可以深入了解各个方面：

连接到目录 — 推荐用于以目录为支撑的工作负载；包含 Delta 和 Iceberg 的完整 Unity Catalog 操作指南
直接查询 — 四种格式、集群方案、表引擎、缓存机制
加速分析 — schema 优化、索引、约 40 倍提速演示
写入数据湖 — 原始写入、聚合写入、类型映射
支持矩阵 — 不同格式和存储后端之间的功能对比
最佳实践 — 访问方法选择、性能设置和工作负载模式

ClickHouse guides

Use case guides

后续步骤

​后续步骤

后续步骤