选择访问方法
表函数
icebergAzure、icebergLocal,以及其他格式中的对应变体) 。完整列表请参见直接查询。
Paimon仅提供表函数。
表引擎
DataLakeCatalog 数据库引擎
多部分表名中的反引号目录通常采用
database.table 这种命名方式。请像上面的示例一样,用反引号将包含数据库限定符的名称括起来。必需设置
CREATE DATABASE 因权限错误而失败,请检查你的服务版本。
对于目录连接,不同目录类型都有各自的标志。概览请参阅Connecting to catalogs,设置详情请参阅 DataLakeCatalog Reference。各目录的具体设置请见目录指南。
对于写入操作,Iceberg 需要 allow_insert_into_iceberg (25.7+,自 26.2 起为 Beta) 。请参阅写入数据湖。Delta Lake 需要 allow_delta_lake_writes (25.9+) 。支持矩阵列出了每种格式和操作适用的标志。
提升查询性能
查询习惯
WHERE 中按分区列进行过滤。Iceberg 和 Delta Lake 会存储分区元数据,使 ClickHouse 能在查询计划阶段跳过无关文件。如果过滤条件针对的是分区规范之外的列,ClickHouse 就会扫描所有匹配的文件。
对于启用了隐藏分区的 Iceberg 表,应针对表 schema 中的源列进行过滤,而不是单独的分区列或转换后的字段名。如果该表按 day(event_time) 分区,请对 event_time 添加谓词。ClickHouse 会根据该过滤条件和 Iceberg 分区规范进行分区裁剪。参见分区裁剪和 Iceberg 规范。
SELECT *。ClickHouse 会从对象存储中按列读取 Parquet,因此查询的列越少,传输和解压的字节数就越少。
将选择性高的过滤条件放在 WHERE 中。从 ClickHouse 26.2+ 开始,PREWHERE 也支持 Iceberg 和其他数据湖表的读取,会在读取其余列之前先在 Parquet 层进行过滤。分区裁剪仍然依赖于对分区源列的过滤,不能仅靠 PREWHERE。
对于包含大量 position 或 equality deletes 的 Iceberg 表,扫描期间会应用 merge-on-read 过滤。因此,单个文件的处理开销通常会高于仅看清单裁剪所显示的程度。
在多节点部署中,使用 cluster 表函数 将文件读取分发到各个副本上。
多节点集群上的并行读取
'default') 。所有受支持的格式都提供了对应的集群变体:
你还可以将集群读取与其他性能设置配合使用。
将批次读取限定在快照范围内
- 对于 Iceberg,可使用 iceberg_snapshot_id 或 iceberg_timestamp_ms (25.4+) 读取某个时间点的视图。对于仅追加表,可将快照设置与
WHERE中的分区过滤条件结合使用。可使用 system.iceberg_history (25.6+) 查找两次运行之间的快照 ID。 - 对于 Delta Lake,可使用 delta_lake_snapshot_start_version 和 delta_lake_snapshot_end_version (25.12+) 读取两个版本之间的变更。可使用 delta_lake_snapshot_version (25.8+) 读取单个快照。有关 CDF 示例,请参见 Delta change data feed。
在本地缓存 Parquet 文件
enable_filesystem_cache = 0,以免缓存命中掩盖不同运行之间的变化。
Apache Iceberg
读取设置
降低 目录 延迟
- 在创建表时设置 iceberg_metadata_async_prefetch_period_ms,以便在后台预拉取元数据。
- 在查询中设置 iceberg_metadata_staleness_ms (26.3+) ,允许使用略有过期的元数据,从而跳过与 目录 的往返访问。
0 时,始终会拉取最新元数据。对于读操作密集且表很少发生变化的工作负载,请增大该窗口。
当 ClickHouse 选错元数据文件时 (表 path 中存在多个 .metadata.json 文件) ,请在创建表时使用 iceberg_metadata_file_path (25.4+) 或 iceberg_metadata_table_uuid 固定分辨率。请参阅元数据文件分辨率。
时间旅行
Iceberg 写入
请参阅写入数据湖和 Iceberg 引擎参考。
Delta Lake
Delta Kernel
读取设置
带有删除向量 (26.2+) 的表会在读取时应用行级过滤。ClickHouse 会自动处理这一点,但对 DV 较多的表进行 scan 时,每个文件都需要执行更多操作。
Delta change data feed
delta.enableChangeDataFeed) 。请在查询设置中同时设置起始版本和结束版本。仅设置结束版本会报错。
_change_type、_commit_version、_commit_timestamp) 。将数据加载到目标表之前,请先处理这些列。有关通用快照模式,请参阅 将批次读取限定到快照。
Delta Lake 写入
调试数据湖查询
验证 目录 连接性
DataLakeCatalog 的 CREATE DATABASE 不会校验凭据。即使 目录 连接已断开,数据库也可能仍然存在。从 ClickHouse 26.4 开始,可运行轻量级健康检查:
SHOW TABLES FROM my_lake 确认连接是否正常,并查看错误信息。使用 SHOW CREATE TABLE,并将表名用反引号括起来,以验证解析后的存储路径和引擎类型:
system.tables 中看不到目录表,请启用 show_remote_databases_in_system_tables (25.8+) 。默认情况下,目录表不会显示在系统内部信息中。在 26.6 之前的版本中,请使用其原名称 show_data_lake_catalogs_in_system_tables。
查看读取了哪些文件
_path、_file、_size、_time、_etag) 。按 _path 分组,可查看分区裁剪是否生效,或查询扫描的文件是否超出预期。对于使用隐藏分区的 Iceberg 表,应基于源列 (例如 event_time) 进行过滤,而不是单独的分区列:
检查扫描量
read_rows 和 read_bytes。ReadBufferFromS3Bytes 和 CachedReadBufferReadFromCacheBytes 等 ProfileEvents 可显示有多少数据来自对象存储,以及有多少来自本地缓存。有关 query_log 和 EXPLAIN 的完整说明,请参阅 查询优化。
进行基准测试时,请禁用 enable_filesystem_cache,以免缓存命中掩盖不同运行之间的变化。
元数据日志
启用日志后运行查询,刷新日志,然后检查该
query_id 对应的条目:
clusterAllReplicas 可查看跨所有副本的完整情况。
较高的 Iceberg 日志级别会禁用 manifest 列表和文件的 元数据缓存,从而减慢对同一表的后续查询。只有在主动排查问题时才应使用高详细程度。对于 Delta Lake predicate 问题,可启用 delta_lake_throw_on_engine_predicate_error (25.8+) ,以便在内核无法下推过滤器时快速报错。
有关列详情和详细程度选项,请参阅 iceberg_metadata_log 和 delta_lake_metadata_log 参考页面。