Set up docs MCP本指南中的截图来自 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 新增的表。
下面是一个连接到 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>`了解更多： 连接到数据目录 介绍了完整的 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 注意事项。
后续步骤
现在你已经了解了完整工作流程，接下来可以深入了解各个方面：