统一格式（UniForm）

Delta 统一格式 (UniForm) 允许您使用 Iceberg 和 Hudi 客户端读取 Delta 表。

UniForm 利用了 Delta Lake、Iceberg 和 Hudi 都由 Parquet 数据文件和元数据层组成的事实。UniForm 异步自动生成 Iceberg 元数据，允许 Iceberg 客户端像读取 Iceberg 或 Hudi 表一样读取 Delta 表。启用 UniForm 后，Delta 写入开销可以忽略不计，因为元数据转换和事务在 Delta 提交后异步发生。

一份数据文件副本即可供所有格式的客户端访问。

要求

要启用 UniForm，您必须满足以下要求

统一 Iceberg

• 表必须启用列映射。请参阅 Delta 列映射。
• Delta 表的 minReaderVersion 必须 >= 2 且 minWriterVersion 必须 >= 7。
• 对表的写入必须使用 Delta Lake 3.1 或更高版本。
• 必须将 Hive Metastore (HMS) 配置为目录。有关如何配置 Apache Spark 以使用 Hive Metastore，请参阅 HMS 文档。

统一 Hudi（预览版）

• 对表的写入必须使用 Delta Lake 3.2 或更高版本。

启用 Delta Lake UniForm

重要

启用 Delta UniForm Iceberg 需要 Delta 表功能 IcebergCompatV2，这是一个写入协议功能。只有支持此表功能的客户端才能写入启用了此功能的表。您必须使用 Delta Lake 3.1 或更高版本才能写入启用了此功能的 Delta 表。

启用 Delta UniForm Iceberg 需要将“delta-iceberg”提供给 Spark shell

--packages io.delta:io.delta:delta-iceberg_2.12:<version>

启用 Delta UniForm Hudi 需要将“delta-hudi”提供给 Spark shell

--packages io.delta:io.delta:delta-hudi_2.12:<version>

以下表属性启用 Iceberg 的 UniForm 支持。

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

以下表属性启用 Hudi 的 UniForm 支持。

'delta.universalFormat.enabledFormats' = 'hudi'

以下表属性同时启用两者的 UniForm 支持。

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg,hudi'

您还必须启用列映射才能使用 UniForm。它在表创建期间自动设置，如以下示例所示

SQL

CREATE TABLE T(c1 INT) USING DELTA TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

在 Delta 3.3 及更高版本中，您可以使用以下语法在现有表上启用或升级 UniForm Iceberg

SQL

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

您还可以使用 REORG 启用 UniForm Iceberg 并重写底层数据文件，如以下示例所示

SQL

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

如果以下任何一项为真，请使用 REORG

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

您可以使用以下语法在现有表上启用 UniForm Hudi

SQL

ALTER TABLE table_name SET TBLPROPERTIES ('delta.universalFormat.enabledFormats' = 'hudi');

注意

此语法要求在 Delta 3.1 上运行之前在表上启用 Delta 列映射。此语法也适用于从 IcbergCompatV1 升级。它可能会重写现有文件以使其与 Iceberg 兼容，并且会自动禁用并清除表中的删除向量。

重要

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

注意

您可以取消设置 delta.universalFormat.enabledFormats 表属性来关闭 UniForm。一旦启用，列映射就无法关闭，并且 Delta Lake 读取器和写入器协议版本的升级无法撤消。

请参阅 限制。

UniForm 何时生成元数据？

Delta Lake 在 Delta Lake 写入事务完成后，使用完成 Delta 事务的相同计算资源异步触发 Iceberg/Hudi 元数据生成。

Iceberg/Hudi 的写入延迟可能比 Delta Lake 高得多。频繁提交的 Delta 表可能会将多个 Delta 提交捆绑到一个 Iceberg/Hudi 提交中。

Delta Lake 确保在单个集群中，每个格式只有一个元数据生成过程正在进行中。将触发第二个并发元数据生成过程的提交将成功提交到 Delta，但不会触发异步元数据生成。这可以防止对于频繁提交（提交之间几秒到几分钟）的工作负载，元数据生成出现级联延迟。

检查 Iceberg/Hudi 元数据生成状态

UniForm 将以下属性添加到 Iceberg/Hudi 表元数据以跟踪元数据生成状态

表属性	描述
converted_delta_version	成功生成元数据的 Delta 表的最新版本。
converted_delta_timestamp	成功生成元数据的最新 Delta 提交的时间戳。

有关如何在 Delta Lake 之外查看表属性，请参阅您的 Iceberg/Hudi 读取器客户端文档。对于 Apache Spark，您可以使用以下语法查看这些属性

SQL

SHOW TBLPROPERTIES <table-name>;

在 Apache Spark 中将 UniForm 表作为 Iceberg 表读取

您可以通过以下步骤在 Apache Spark 中将 UniForm 表作为 Iceberg 表读取

• 启动 Apache Spark（带 Iceberg），并连接到 UniForm 使用的 Hive Metastore。有关如何在 Apache Spark 中运行 Iceberg 并连接到 Hive Metastore，请参阅 Iceberg 文档。
• 使用 SHOW TABLES 命令查看目录中可用的 Iceberg 表列表。
• 使用标准 SQL（例如 SELECT）读取 Iceberg 表。

使用元数据 JSON 路径将 UniForm 表作为 Iceberg 表读取

一些 Iceberg 客户端允许您通过提供版本化元数据文件的路径来注册外部 Iceberg 表。每次 UniForm 将新版本的 Delta 表转换为 Iceberg 时，都会创建一个新的元数据 JSON 文件。

使用元数据 JSON 路径配置 Iceberg 的客户端包括 BigQuery。有关配置详细信息，请参阅 Iceberg 读取器客户端的文档。

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

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

在 Apache Spark 中将 UniForm 表作为 Hudi 表读取

您可以通过以下步骤在 Apache Spark 中将 UniForm 表作为 Hudi 表读取

• 有关如何在 Apache Spark 上运行 Hudi，请参阅 Hudi 文档

Scala

spark.read.format("hudi")
  .option("hoodie.metadata.enable", "true")
  .load("PATH_TO_UNIFORM_TABLE_DIRECTORY")

Delta 和 Iceberg/Hudi 表版本

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

Delta 和 Iceberg 表版本既不与提交时间戳对齐，也不与版本 ID 对齐。但是，Delta 和 Hudi 提交时间戳对齐，但版本 ID 不对齐。如果您希望验证给定 Iceberg/Hudi 表版本对应于哪个 Delta 表版本，您可以使用 Iceberg/Hudi 表上设置的相应表属性。请参阅 检查 Iceberg/Hudi 元数据生成状态。

限制

注意

从 Iceberg 和 Hudi 的角度来看，UniForm 是只读的。但是，这无法强制执行，因为对于 Iceberg，UniForm 使用 HMS 作为 Iceberg 目录，对于 Hudi，元数据存储在文件系统上。如果任何外部写入器（非 Delta Lake）写入此 Iceberg/Hudi 表，这可能会破坏您的 Delta 表并导致数据丢失，因为 Iceberg/Hudi 写入器可能会执行 Delta 不知道的数据清理或垃圾回收。

存在以下限制

• UniForm 不适用于启用了删除向量的表。请参阅 什么是删除向量？。
• 启用了 UniForm 的 Delta 表不支持 VOID 类型。
• Iceberg/Hudi 客户端只能从 UniForm 读取。不支持写入。
• Iceberg/Hudi 读取器客户端可能有单独的限制，无论 UniForm 如何。请参阅目标客户端的文档。

启用 UniForm 时，以下 Delta Lake 功能适用于 Delta 客户端，但在 Iceberg 中不受支持

• 更改数据馈送
• Delta Sharing