使用 Iceberg 客户端读取 Delta Lake 表

Iceberg 读取功能在 Databricks Runtime 14.3 LTS 及更高版本中可用，它会将 Delta Lake 表配置为自动生成 Iceberg 元数据，因此 Iceberg 客户端无需重写文件即可读取 Delta Lake 数据。

可以配置外部连接，使 Unity Catalog 充当 Iceberg 目录。请参阅 Apache Iceberg 客户端中的 Access Azure Databricks 表。

Iceberg 的阅读方式

Delta Lake 和 Apache Iceberg 都包含 Parquet 数据文件和元数据层。当你启用 Iceberg 读取时，Azure Databricks 会将你的表配置为元数据层使用通用格式（UniForm）。 UniForm 自动异步生成 Iceberg 元数据，同时与 Delta Lake 元数据并存，无需重写 Parquet 数据文件。一份数据文件即可同时供 Delta 和 Iceberg 客户端使用。

使用 Iceberg 进行读取时，请考虑以下事项：

启用了 Iceberg 读取的 Delta Lake 表使用 Zstandard 而不是 Snappy 作为底层 Parquet 数据文件的压缩编解码器。
Iceberg 元数据生成在用于将数据写入 Delta Lake 表的计算上异步运行，这可能会增加驱动程序资源使用率。

有关旧版 UniForm IcebergCompatV1 表功能的文档，请参阅旧版 UniForm IcebergCompatV1。

要求

要启用 Iceberg 读取操作，必须满足以下要求：

Delta Lake 表必须注册到 Unity 目录。同时支持托管表和外部表。
该表必须启用列映射。请参阅有关使用 Delta Lake 列映射重命名和删除列的说明。
- 为表启用 IcebergCompatV2 后，将无法删除 columnMapping 表功能。
Delta Lake 表必须满足 minReaderVersion>= 2 且 minWriterVersion>= 7。请参阅 Delta Lake 功能兼容性和协议。
对表的写入必须使用 Databricks Runtime 14.3 LTS 或更高版本。

注释

您无法在启用 Iceberg 读取功能的表上启用删除向量。

使用 REORG 可关闭并清除删除向量，同时在已启用删除向量的现有表上启用 Iceberg 读取。请参阅“启用或使用REORG升级 Iceberg 读取支持”。

启用 Iceberg 读取

注释

启用 Iceberg 读取会添加 IcebergCompatV2 写入协议功能并升级编写器协议。只有支持此表功能的客户端才能写入表。这可能会影响与外部 Delta Lake 客户端的兼容性。请参阅 Delta Lake 功能兼容性和协议。

首次启用 Iceberg 读取时，将开始异步元数据生成。在外部客户端可以使用 Iceberg 查询表之前，必须完成此任务。请参阅检查 Iceberg 元数据生成状态。

有关限制列表，请参阅限制。

在创建表时

在创建表期间启用 Iceberg 读取时，会自动启用列映射：

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.columnMapping.mode' = 'id',
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Databricks 建议出于兼容性目的而设置 delta.columnMapping.mode = id 。请参阅有关使用 Delta Lake 列映射重命名和删除列的说明。

在现有表上

若要在 Databricks Runtime 15.4 LTS 及更高版本上启用 Iceberg 读取现有表，请执行以下操作：

ALTER TABLE table_name SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

有关列映射模式的详细信息 name ，请参阅列映射模式。

使用 `REORG` 启用或升级 Iceberg 读取功能

如果以下任何一项为真，请使用 REORG 启用 Iceberg 读取：

您已在您的表上启用删除向量。
你之前已启用 UniForm Iceberg 的 IcebergCompatV1 版本。
需要从不支持 Hive 样式 Parquet 文件的 Iceberg 引擎（例如 Athena 或 Redshift）中读取数据。

若要启用 Iceberg 读取和重写基础数据文件，请使用 REORG 以下示例所示：

REORG TABLE table_name APPLY (UPGRADE UNIFORM(ICEBERG_COMPAT_VERSION=2));

验证 Iceberg 读取是否已启用

使用 DESCRIBE EXTENDED 验证是否已为您的表启用 Iceberg 读取：

DESCRIBE EXTENDED catalog_name.schema_name.table_name;

在输出中查找 Delta Uniform Iceberg 部分。如果存在此部分，则会在表中启用 Iceberg 读取。

也可使用 SHOW TBLPROPERTIES：

SHOW TBLPROPERTIES catalog_name.schema_name.table_name;

检查以下属性：

delta.enableIcebergCompatV2 = true
delta.universalFormat.enabledFormats = iceberg

如果这两个属性被设置为这些值，则 Iceberg 读取功能会被启用。

关闭 Iceberg 读取

您可以通过取消设置 delta.universalFormat.enabledFormats 表属性来禁用 Iceberg 读取：

ALTER TABLE table_name UNSET TBLPROPERTIES ('delta.universalFormat.enabledFormats');

对 Delta Lake 读取器和写入器协议版本的升级无法撤销。请参阅 Delta Lake 功能兼容性和协议。

Iceberg 元数据生成

在 Delta Lake 写入事务完成后，Azure Databricks 会异步触发元数据生成。此元数据生成过程使用完成 Delta Lake 事务的相同计算。

还可以手动触发 Iceberg 元数据生成。请参阅手动触发 Iceberg 元数据转换。

为了避免元数据生成带来的写入延迟，提交频繁的 Delta Lake 表可能会将多个 Delta Lake 提交合并为对 Iceberg 元数据的一次提交。

Delta Lake 确保给定计算资源上只有一个元数据生成过程正在进行。会触发第二个并发元数据生成过程的这些提交可以成功提交到 Delta Lake，但不会触发异步 Iceberg 元数据生成。这可以防止频繁提交的工作负载中的元数据生成出现连带延迟，提交时间间隔为几秒到几分钟。

请参阅 Delta 和 Iceberg 表版本。

Delta 和 Iceberg 表版本

Delta Lake 和 Iceberg 允许使用表元数据中存储的表版本或时间戳进行时间旅行查询。

无论按提交时间戳还是按版本 ID，都不能保证 Delta Lake 表版本与 Iceberg 版本对齐。若要验证 Iceberg 表的某个给定版本对应 Delta Lake 表的哪个版本，请使用相应的表属性。请参阅检查 Iceberg 元数据生成状态。

检查 Iceberg 元数据生成状态

在表上启用 Iceberg 读取会将以下字段添加到 Unity Catalog 和 Iceberg 表元数据中，以跟踪元数据生成状态：

元数据字段	Description
`converted_delta_version`	已成功生成 Iceberg 元数据的 Delta Lake 表的最新版本。
`converted_delta_timestamp`	已成功生成 Iceberg 元数据的最新 Delta Lake 提交时间戳。

在 Azure Databricks 上，可通过执行一种操作来查看这些元数据字段：

查看 Delta Uniform Iceberg 返回的 DESCRIBE EXTENDED table_name 段。
使用Catalog Explorer查看表元数据。

请参阅 Iceberg 读者客户端的文档，了解如何查看 Azure Databricks 外部的表属性。对于 OSS Apache Spark，可以使用以下语法查看这些属性：

SHOW TBLPROPERTIES <table-name>;

手动触发 Iceberg 元数据转换

可以为最新版本的 Delta Lake 表手动触发 Iceberg 元数据生成。此操作以同步方式运行。完成后，Iceberg 中提供的表内容反映了启动转换过程时可用的最新版本的 Delta Lake 表。

在正常情况下不需要此操作。使用它可从以下情况中恢复：

群集在自动生成元数据成功之前终止。
错误或作业失败中断了元数据生成。
不支持 UniForm Iceberg 元数据生成的客户端会向 Delta Lake 表写入数据。

使用以下语法手动触发 Iceberg 元数据生成：

MSCK REPAIR TABLE <table-name> SYNC METADATA

请参阅 REPAIR TABLE。

通过元数据 JSON 路径访问 Iceberg 数据集

某些 Iceberg 客户端（如 BigQuery）要求提供版本化元数据文件的路径来注册外部 Iceberg 表。每次Azure Databricks将新版本的 Delta Lake 表转换为 Iceberg 时，都会创建新的元数据 JSON 文件。

有关配置详细信息，请参阅特定 Iceberg 读取器客户端的文档。

Delta Lake 使用以下模式将 Iceberg 元数据存储在表目录下：

<table-path>/metadata/<version-number>-<uuid>.metadata.json

在 Azure Databricks 上，可通过执行一种操作来查看此元数据位置：

查看 Delta Uniform Iceberg 返回的 DESCRIBE EXTENDED table_name 段。
使用Catalog Explorer查看表元数据。

Important

基于路径的 Iceberg 读取器客户端可能需要手动更新和刷新元数据 JSON 路径来读取当前表版本。使用过时版本查询 Iceberg 表时，用户可能会遇到错误，因为 Parquet 数据文件已从 Delta Lake 表中删除。VACUUM

VACUUM 和 Iceberg 的元数据清理

从 Databricks Runtime 17.2 开始，该 VACUUM 命令删除 UniForm metadata/ 目录下的未跟踪文件，同时保留仍可访问的 Iceberg 元数据。

UniForm 转换会在内部进行 Iceberg 快照过期处理，但默认使用 cleanExpiredFiles(false)。因此，OPTIMIZE 和常规的 UniForm 转换只会使旧的 Iceberg 元数据无法访问，但不会将其从物理上删除。

若要物理删除不可访问的 Iceberg 元数据，请在 FULL VACUUM 保留期结束后运行 delta.deletedFileRetentionDuration。请参阅为“按时间顺序查看”查询配置数据保留。

局限性

启用 Iceberg 读取功能的所有表格都存在以下限制：

Iceberg 客户端仅支持读取功能。不支持写入。
- 不管 Azure Databricks 对 Iceberg 读取的支持如何，Iceberg 读取器客户端可能都有各自局限性。请参阅所选客户端的文档。
读取 Iceberg v2 时不支持删除向量。但是，Apache Iceberg v3 支持删除向量。请参阅使用 Apache Iceberg v3 功能和Databricks 中的删除向量。
使用 IcebergCompatV2 时，无法在物化视图或流式表上启用 Iceberg 读取。对于由管道管理的物化视图和流式表，可以改为使用 IcebergCompatV3 启用外部 Iceberg 访问。此功能目前以公共预览版提供。请参阅为流式表和物化视图启用外部数据访问。
必须按名称（非路径）访问 Delta Lake 表才能自动触发 Iceberg 元数据生成。
启用 Iceberg 读取的 Delta Lake 表不支持 VOID 类型。
Iceberg 读取使用的某些 Delta Lake 表功能不被某些 OpenSharing 读取器客户端支持。请参阅什么是 OpenSharing？。
OpenSharing 的接收方可以使用 Iceberg REST Catalog API，将已启用 Iceberg 读取的 Delta Lake 表作为 Iceberg 表进行读取。此功能目前以公共预览版提供。请参阅 “启用与外部 Iceberg 客户端共享”。
当启用 Iceberg 读取时，旧版更改数据馈送对 Delta 客户端有效，但在 Iceberg 中不受支持。请参阅 Delta Lake 的旧更改数据馈送。

Last updated on 2026-08-26