旧版 UniForm IcebergCompatV1

项目
10/21/2024

重要

本文档已过时，将来可能不会更新。本内容中提及的产品、服务或技术不再受支持。请参阅通过 Iceberg 客户端使用 UniForm 读取 Delta 表。

重要

此功能在 Databricks Runtime 13.2 及更高版本中作为公共预览版提供。

Delta 通用格式 (UniForm) 允许使用 Iceberg 阅读器客户端读取 Delta 表。

UniForm 利用了 Delta Lake 和 Iceberg 都由 Parquet 数据文件和元数据层组成的事实。 UniForm 自动异步生成 Iceberg 元数据，而无需重写数据，因此 Iceberg 客户端可以像读取 Iceberg 表一样读取 Delta 表。数据文件的单一副本可用于这两种格式。

可以配置外部连接，使 Unity Catalog 充当 Iceberg 目录。请参阅使用 Unity Catalog Iceberg 目录端点读取。

注意

UniForm 元数据生成在用于将数据写入 Delta 表的计算上异步运行，这可能会加剧驱动程序资源使用状况。

要求

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

Delta 表必须注册到 Unity Catalog。同时支持托管表和外部表。
表必须启用列映射。请参阅使用 Delta Lake 列映射重命名和删除列。
Delta 表必须具有 minReaderVersion>=2 和 minWriterVersion>=7。请参阅 Azure Databricks 如何管理 Delta Lake 功能兼容性？。
对表的写入必须使用 Databricks Runtime 13.2 或更高版本。

启用 Delta UniForm

重要

启用 Delta UniForm 将设置 Delta 表功能 IcebergCompatV1，它是写入协议功能。只有支持此表功能的客户端才能写入启用了 UniForm 的表。必须使用 Databricks Runtime 13.2 或更高版本才能在启用此功能的情况下写入 Delta 表。

可以通过取消设置 delta.universalFormat.enabledFormats 表属性来关闭 UniForm。启用列映射后将无法关闭它，并且无法撤消对 Delta Lake 读取器协议版本的升级。

下表属性启用了对 Iceberg 的 UniForm 支持。 iceberg 是唯一有效值。

'delta.universalFormat.enabledFormats' = 'iceberg'

还必须启用列映射和 IcebergCompatV1 才能使用 UniForm。如果在创建表期间启用 UniForm，则会自动设置这些属性，如以下示例所示：

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'iceberg');

如果使用 CTAS 语句创建新表，则必须手动指定列映射，如以下示例所示：

CREATE TABLE T
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.universalFormat.enabledFormats' = 'iceberg')
AS
  SELECT * FROM source_table;

如果要更改现有表，则必须指定所有这些属性，如以下示例所示：

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

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

注意

如果计划使用 BigQuery 作为 Iceberg 读取器客户端，则必须在 Azure Databricks 上将 spark.databricks.delta.write.dataFilesToSubdir 设置为 true，以满足 BigQuery 对数据布局的要求。

请参阅限制。

UniForm 何时生成 Iceberg 元数据？

在 Delta Lake 写入事务完成后（使用完成 Delta 事务的相同计算），Azure Databricks 异步触发 Iceberg 元数据生成。还可以手动触发 Iceberg 元数据生成。请参阅手动触发 Iceberg 元数据转换。

为了避免与 Iceberg 元数据生成相关的写入延迟，频繁提交的 Delta 表可能会将多个 Delta 提交捆绑到单一 Iceberg 提交中。

Delta Lake 确保在任何时候都只有一个 Iceberg 元数据生成进程在进行中。触发第二个并发 Iceberg 元数据生成进程的提交将成功提交到 Delta，但其不会触发异步 Iceberg 元数据生成。这可以防止频繁提交的工作负载的元数据生成的级联延迟（提交之间的秒到分钟）。

请参阅 Delta 和 Iceberg 表版本。

检查 Iceberg 元数据生成状态

UniForm 将以下字段添加到 Unity Catalog 和 Iceberg 表元数据中，以跟踪元数据生成状态：

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

在 Azure Databricks 上，可以使用目录资源管理器查看这些元数据字段。使用 REST API 获取表时，也会返回这些字段和值。

有关如何在 Azure Databricks 之外查看表属性，请参阅 Iceberg 读取器客户端文档。对于 OSS Apache Spark，可以使用以下语法查看这些属性：

SHOW TBLPROPERTIES <table-name>;

手动触发 Iceberg 元数据转换

可以手动触发最新版本 Delta 表的 Iceberg 元数据生成。此操作同步运行，表示当它完成时，Iceberg 中可用的表内容反映了转换过程开始时可用的最新版本 Delta 表。

在正常情况下不需要进行此操作，但如果遇到以下情况，则会有所帮助：

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

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

MSCK REPAIR TABLE <table-name> SYNC METADATA

请参阅 REPAIR TABLE。

使用元数据 JSON 路径读取

一些 Iceberg 客户端要求提供版本控制元数据文件的路径，以注册外部 Iceberg 表。每次 UniForm 将新版本 Delta 表转换为 Iceberg 时，它都会创建新的元数据 JSON 文件。

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

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

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

可以使用目录资源管理器找到此文件的路径。对于已启用 UniForm 的表，Delta 表的详细信息包括 Iceberg 元数据位置的字段。

还可以使用 REST API 获取表的所有详细信息，包括元数据位置。使用以下命令：

GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

响应包含以下信息：

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

重要

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

使用 Unity Catalog Iceberg 目录终结点读取

一些 Iceberg 客户端可以连接到 Iceberg REST 目录。 Unity Catalog 为 Delta 表（使用终结点 /api/2.1/unity-catalog/iceberg 启用了 UniForm）提供了 Iceberg REST 目录 API 的只读实现。有关使用此 REST API 的详细信息，请参阅 Iceberg REST API 规范。

已知支持 Iceberg 目录 API 的客户端包括 Apache Spark、Flink 和 Trino。必须配置对包含已启用 UniForm 的 Delta 表的基础云对象存储的访问权限。有关配置详细信息，请参阅 Iceberg 读取器客户端文档。

必须生成并配置 Azure Databricks 个人访问令牌，以允许其他服务连接到 Unity Catalog。请参阅对 Azure Databricks 资源的访问进行身份验证。

以下是配置 OSS Apache Spark 将 UniForm 读取为 Iceberg 的设置示例：

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity"="org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token":"<your_personal_access_token>",
"spark.sql.catalog.unity.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

将已生成个人访问令牌的工作区的完整 URL 替换为 <api-root>。

注意

使用此方法查询 Unity Catalog 中的表时，对象标识符使用以下模式：

unity.<catalog-name>.<schema-name>.<table-name>

此模式使用了 Unity Catalog 中相同的三层名称空间，但添加了额外的前缀 unity。

Delta 和 Iceberg 版本

Delta Lake 和 Iceberg 都允许使用存储在表元数据中的表版本或时间戳进行按时间顺序查看查询。

通常，Iceberg 和 Delta 表的版本不按照提交时间戳或版本 ID 对齐。如果希望验证指定版本的 Iceberg 表对应的 Delta 表版本，则可以使用在 Iceberg 表上设置的相应表格属性。请参阅检查 Iceberg 元数据生成状态。

限制

存在以下限制：

UniForm 不适用于已启用删除向量的表。请参阅什么是删除向量？。
已启用 UniForm 的 Dealta 表不支持 LIST、MAP 和 VOID 类型。
Iceberg 客户端只能从 UniForm 读取。不支持写入。
不管 UniForm 如何，Iceberg 读取器客户端可能都有各自局限性。请参阅所选客户端文档。
Iceberg 读取器客户端 1.2.0 及以下版本不支持 Apache Spark 编写的 INT96 时间戳类型。在写入 UniForm 表的笔记本中使用以下代码，以避免此限制：spark.conf.set("spark.sql.parquet.outputTimestampType", "TIMESTAMP_MICROS")
Unity Catalog Iceberg 终结点的公共预览版并不适用于大规模生产工作负载。如果超过每秒 5 个查询的阈值，则可能会遇到速率限制。

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

更改数据馈送
增量共享

通过