支持矩阵 - ClickHouse Documentation

本页提供 ClickHouse 数据湖集成的完整支持矩阵，涵盖各类开放表格式支持的功能、ClickHouse 可连接的目录，以及各类目录所支持的能力。

开放表格式支持

ClickHouse 可与四种开放表格式集成：Apache Iceberg、Delta Lake、Apache Hudi 和 Apache Paimon。请选择下方的一种格式以查看其支持矩阵。 图例： ✅ 支持 | ⚠️ 部分支持 / Experimental | ❌ 不支持

Apache Iceberg
Delta Lake
Apache Hudi
Apache Paimon

特性	状态	备注
存储后端
AWS S3	✅	通过 `icebergS3()` 或 `iceberg()` 别名
GCS	✅	通过 `icebergS3()` 或 `iceberg()` 别名
Azure Blob 存储	✅	通过 `icebergAzure()`
HDFS	⚠️	通过 `icebergHDFS()`。已弃用。
本地文件系统	✅	通过 `icebergLocal()`
访问方式
表函数	✅	`icebergS3()`，针对不同后端提供相应变体
表引擎	✅	`IcebergS3`，针对不同后端提供相应变体
集群分布式读取	✅	`icebergS3Cluster`, `icebergAzureCluster`, `icebergHDFSCluster`
命名集合	✅	定义命名集合

读取特性
读取支持	✅	完整支持 SELECT 以及所有 ClickHouse SQL 函数
分区裁剪	✅	参见分区裁剪。
隐式分区	✅	支持基于 Iceberg transform 的分区
分区演进	✅	支持读取分区规范随时间变化的表
schema 演进	✅	支持列的添加、删除和重排序。参见 Schema evolution。
类型提升 / 扩展	✅	`int` → `long`, `float` → `double`, `decimal(P,S)` → `decimal(P',S)`，其中 P’ > P。参见 Schema evolution。
时间旅行 / 快照	✅	通过 `iceberg_timestamp_ms` 或 `iceberg_snapshot_id` 设置。参见 Time travel。
位置删除	✅	参见处理已删除行。
相等删除	✅	仅表引擎支持，自 v25.8+ 起。参见处理已删除行。
Merge-on-read	⚠️	实验性。支持删除操作。
格式版本	⚠️	支持 v1 和 v2。不支持 v3。
列统计信息	✅
布隆过滤器 / puffin 文件	❌	不支持 puffin 文件中的布隆过滤器索引
虚拟列	✅	`_path`, `_file`, `_size`, `_time`, `_etag`。参见虚拟列。

写入特性
创建表	✅	实验性。需要 `allow_insert_into_iceberg = 1`。自 v25.7+ 起支持。参见创建表。
INSERT	✅	自 26.2 起为 Beta。需要 `allow_insert_into_iceberg = 1`。参见插入数据。
DELETE	✅	Experimental。需要 `allow_insert_into_iceberg = 1`。通过 `ALTER TABLE ... DELETE WHERE` 实现。参见删除数据。
ALTER TABLE (schema 变更)	✅	Experimental。需要 `allow_insert_into_iceberg = 1`。支持添加、删除、修改和重命名列。参见Schema 演进。
Compaction	⚠️	Experimental。需要 `allow_experimental_iceberg_compaction = 1`。将位置删除文件合并整理到数据文件中。参见Compaction。不支持其他 Iceberg 合并整理操作。
UPDATE / MERGE	❌	不支持。参见 Compaction。
Copy-on-write	❌	不支持
Expire snapshots	❌	不支持
Remove orphan files	❌	不支持
写入分区	✅	支持。
修改分区	❌	不支持从 ClickHouse 更改分区方案。ClickHouse 可以向分区方案已演进的 Iceberg 表写入。

元数据
分支与标签	❌	不支持 Iceberg 分支/标签引用
元数据文件解析	✅	支持通过目录、简单目录列表、`version-hint` 和特定路径来解析元数据。可通过 `iceberg_metadata_file_path` 和 `iceberg_metadata_table_uuid` 配置。参见元数据文件解析。
数据缓存	✅	与 S3/Azure/HDFS 存储引擎采用相同机制。参见数据缓存。
元数据缓存	✅	manifest 和元数据文件会缓存在内存中。默认通过 `use_iceberg_metadata_files_cache` 启用。参见元数据缓存。

从 25.6 版本起，ClickHouse 使用 Delta Lake Rust kernel 读取 Delta Lake 表，从而支持更广泛的功能；不过，在访问 Azure Blob 存储中的数据时存在已知问题。因此，在 Azure Blob 存储上读取数据时，该 Kernel 会被禁用。下面会说明哪些功能需要此 kernel。

Feature	Status	Notes
Storage backends
AWS S3	✅	通过 `deltaLake()` 或 `deltaLakeS3()`
GCS	✅	通过 `deltaLake()` 或 `deltaLakeS3()`
Azure Blob Storage	✅	通过 `deltaLakeAzure()`
HDFS	❌	不支持
Local filesystem	✅	通过 `deltaLakeLocal()`
Access methods
Table function	✅	`deltaLake()` 及其针对各后端的变体
Table engine	✅	`DeltaLake`
Cluster-distributed reads	✅	`deltaLakeCluster`, `deltaLakeAzureCluster`
Named collections	✅	Named collection
Read features
Read support	✅	完整支持 SELECT 以及所有 ClickHouse SQL 函数
Partition pruning	✅	需要 Delta Kernel。
Schema evolution	✅	需要 Delta Kernel。
Time travel	✅	需要 Delta Kernel。
Deletion vectors	✅
Column mapping	✅
Change data feed	✅	需要 Delta Kernel。
Virtual columns	✅	`_path`, `_file`, `_size`, `_time`, `_etag`。参见 Virtual columns。
Write features
INSERT	✅	Experimental。需要 `allow_experimental_delta_lake_writes = 1`。参见 DeltaLake engine。需要 Delta Kernel。
DELETE / UPDATE / MERGE	❌	不支持
CREATE empty table	❌	不支持创建新的空 Delta Lake 表。`CREATE TABLE` 操作假定对象存储上已存在 Delta Lake 表。
Caching
Data caching	✅	机制与 S3/Azure/HDFS 存储引擎相同。参见 Data cache。

功能	状态	说明
存储后端
AWS S3	✅	通过 `hudi()`
GCS	✅	通过 `hudi()`
Azure Blob 存储	❌	不支持
HDFS	❌	不支持
本地文件系统	❌	不支持
访问方式
表函数	✅	`hudi()`
表引擎	✅	`Hudi`
集群分布式读取	✅	`hudiCluster` (仅支持 S3)
命名集合	✅	Hudi 参数
读取功能
读取支持	✅	全面支持 SELECT 以及所有 ClickHouse SQL 函数
schema 演化	❌	不支持
时间旅行	❌	不支持
虚拟列	✅	`_path`, `_file`, `_size`, `_time`, `_etag`。参见虚拟列。
写入功能
INSERT / DELETE / UPDATE	❌	仅支持只读
缓存
数据缓存	❌	不支持

Feature	Status	Notes
存储后端
S3	✅	实验性。通过 `paimon()` 或 `paimonS3()`
GCS	✅	实验性。通过 `paimon()` 或 `paimonS3()`
Azure Blob 存储	✅	实验性。通过 `paimonAzure()`
HDFS	⚠️	实验性。通过 `paimonHDFS()`。已弃用。
本地文件系统	✅	实验性。通过 `paimonLocal()`
访问方式
表函数	✅	实验性。`paimon()` 及各后端对应的变体
表引擎	❌	没有专用表引擎
集群分布式读取	✅	实验性。`paimonS3Cluster`、`paimonAzureCluster`、`paimonHDFSCluster`
命名集合	✅	实验性。定义命名集合
读取功能
读取支持	✅	实验性。完整支持 SELECT 以及所有 ClickHouse SQL 函数
schema 演进	❌	不支持
时间旅行	❌	不支持
虚拟列	✅	实验性。`_path`, `_file`, `_size`, `_time`, `_etag`。参见虚拟列。
写入功能
INSERT / DELETE / UPDATE	❌	只读集成
缓存
数据缓存	❌	不支持

目录支持

ClickHouse 可以使用 DataLakeCatalog 数据库引擎连接外部数据目录，并将该目录映射为一个 ClickHouse 数据库。注册在目录中的表会自动显示出来，并可使用标准 SQL 查询。当前支持以下目录。有关完整的设置说明，请参阅各目录的参考指南。

目录	格式	读取	创建表	INSERT	参考指南
AWS Glue Catalog	Iceberg	✅ Beta	❌	❌	Glue 目录指南
BigLake Metastore	Iceberg	✅ Beta	❌	❌	BigLake Metastore 指南
Databricks Unity Catalog	Delta, Iceberg	✅ Beta	✅ Beta	✅ Beta	Unity Catalog 指南
Iceberg REST	Iceberg	✅ Beta	❌	❌	REST 目录指南
Lakekeeper	Iceberg	✅ Beta	❌	❌	Lakekeeper 目录指南
Project Nessie	Iceberg	✅ Experimental	❌	❌	Nessie 目录指南
Microsoft OneLake	Iceberg	✅ Beta	✅ Beta	✅ Beta	OneLake 目录指南

目前所有目录集成都需要启用 Experimental 或 Beta 设置。除 Microsoft OneLake 和 Databricks Unity Catalog 外，所有目录都仅提供 read-only 访问——可以查询表，但不能通过目录连接创建表或写入数据。若要将目录中的数据加载到 ClickHouse 以加快分析速度，请使用加速分析指南中所述的 INSERT INTO SELECT。若要将数据写回开放表格式，请按写入数据指南中的说明创建独立的 Iceberg 表。

​开放表格式支持

​目录支持

开放表格式支持

目录支持