舊版 UniForm IcebergCompatV1

發行項
10/01/2024

重要

此文件已淘汰，且可能未更新。不再支援此內容中提及的產品、服務或技術。請參閱<使用 UniForm 來讀取 Delta 資料表與 Iceberg 使用者端>。

重要

在 Databricks Runtime 13.2 和更新版本中，這項功能處於公開預覽狀態。

Delta Universal Format (UniForm) 可讓您使用 Iceberg 讀取器用戶端讀取 Delta 資料表。

UniForm 利用了 Delta Lake 和 Iceberg 都包含 Parquet 資料檔案和中繼資料層這一事實。 UniForm 會自動以非同步方式產生 Iceberg 中繼資料，而不需要重寫資料，以便 Iceberg 用戶端可以讀取 Delta 資料表，就像是 Iceberg 資料表一樣。資料檔案的單一拷貝提供這兩種格式。

您可以設定外部連線，讓 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 寫入交易完成後，Azure Databricks 會使用與完成 Delta 交易的相同計算非同步觸發 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 資料表時，使用者可能會遇到錯誤，因為使用 VACUUM 從 Delta 資料表中移除了 Parquet 資料檔案。

使用 Unity Catalog Iceberg 目錄端點進行讀取

有些 Iceberg 用戶端可以連線到 Iceberg REST 目錄。 Unity Catalog 為使用端點 /api/2.1/unity-catalog/iceberg 啟用了 UniForm 的 Delta 資料表提供 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 的 Delta 資料表不支援 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 中不受支援：

變更資料摘要
Delta Sharing

共用方式為