使用 UniForm 來讀取差異資料表與 Iceberg 用戶端

發行項
10/02/2024

Delta Lake 通用格式 (UniForm) 可讓您使用 Iceberg 閱讀器用戶端讀取差異資料表。此功能需要 Databricks Runtime 14.3 LTS 或更新版本。

重要

如需舊版 UniForm IcebergCompatV1 資料表功能的文件，請參閱舊版 UniForm IcebergCompatV1。

您可以設定外部連線，讓 Unity Catalog 作為 Iceberg 目錄。請參閱使用 Unity Catalog Iceberg 目錄端點進行讀取。

UniForm Iceberg 使用 Zstandard 而非 Snappy 作為基礎 Parquet 資料檔案的壓縮編解碼器。

注意

UniForm 中繼資料產生會在用來將資料寫入差異資料表的計算上非同步執行，這可能會增加驅動程式資源使用量。

UniForm 如何運作？

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

需求

若要啟用 UniForm Iceberg，必須滿足下列需求：

Delta 資料表必須註冊至 Unity Catalog。同時支援受控資料表和外部資料表。
資料表必須啟用資料行對應。請參閱重新命名和卸除與 Delta Lake 資料行對應的資料行。
Delta 資料表必須擁有 minReaderVersion>= 2 和 minWriterVersion>= 7。請參閱 Azure Databricks 如何管理 Delta Lake 功能相容性？。
寫入到資料表必須使用 Databricks Runtime 14.3 LTS 或更新版本。

注意

您無法在已啟用 UniForm Iceberg 的資料表上啟用刪除向量。

在已啟用刪除向量的現有資料表上啟用 UniForm Iceberg 時，使用 REORG 來停用和清除刪除向量。請參閱使用 REORG 啟用或升級。

啟用 UniForm Iceberg

重要

啟用 Delta UniForm 會設定 Delta 資料表功能 IcebergCompatV2，這是一個寫入通訊協定功能。只有支援此資料表功能的用戶端可以寫入已啟用 UniForm 的資料表。您必須使用 Databricks Runtime 14.3 LTS 或更新版本，來寫入已啟用此功能的差異資料表。

您可以取消設定 delta.universalFormat.enabledFormats 資料表屬性來關閉 UniForm。無法復原對 Delta Lake 讀取器和寫入器通訊協定版本的升級。

您必須設定以下資料表的屬性，才能啟用 UniForm Iceberg：

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

當您第一次啟用 UniForm 時，非同步中繼資料產生就會開始。必須先完成此任務，外部用戶端才能使用 Iceberg 查詢資料表。請參閱檢查 Iceberg 中繼資料產生狀態。

如需限制的清單，請參閱限制。

在資料表建立期間啟用

您必須啟用資料行對應，才能使用 UniForm Iceberg。如果在資料表建立期間啟用 UniForm Iceberg，則會發生這種情況，如下列範例所示：

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

透過變更現有的資料表來啟用

在 Databricks Runtime 15.4 LTS 和更新版本中，您可以使用下列語法在現有資料表上啟用或升級 UniForm Iceberg：

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

使用 `REORG` 啟用或升級

您可以使用 REORG 來啟用 UniForm Iceberg 並重寫基礎資料檔案，如下列範例所示：

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

如果存在下列任何情況，請使用 REORG：

您的資料表已啟用刪除向量。
您先前已啟用 UniForm Iceberg 的 IcebergCompatV1 版本。
您需要從不支援 Hive 樣式的 Parquet 檔案的 Iceberg 引擎 (例如 Athena 或 Redshift) 中讀取。

UniForm 何時會產生 Iceberg 中繼資料？

在 Delta Lake 寫入交易完成之後，Azure Databricks 會非同步觸發中繼資料產生。此中繼資料產生程序使用完成 Delta 交易的相同計算。

注意

也可以手動觸發 Iceberg 中繼資料產生。請參閱手動觸發 Iceberg 中繼資料轉換。

為了避免與中繼資料產生關聯的寫入延遲，頻繁提交的差異資料表可能會將多個差異提交分組到單一 Iceberg 中繼資料提交中。Iceberg 中繼資料提交中。

Delta Lake 可確保在指定計算資源上任何時候都只有一個中繼資料產生程序正在進行中。會觸發第二個並行中繼資料產生程序的提交會成功提交至 Delta，但不會觸發非同步的 Iceberg 中繼資料產生。這可防止具有頻繁提交的工作負載的中繼資料產生的串聯延遲 (提交之間的間隔為數秒到數分鐘)。

請參閱 Delta 和 Iceberg 資料表版本。

Delta 和 Iceberg 資料表版本

Delta Lake 和 Iceberg 允許使用儲存在資料表中繼資料中的資料表版本或時間戳記進行時間旅行查詢。

一般而言，差異資料表版本不會依提交時間戳記或版本識別碼與 Iceberg 版本對齊。若要確認指定版本的 Iceberg 資料表對應到哪個差異資料表版本，您可以使用對應的資料表屬性。請參閱檢查 Iceberg 中繼資料產生狀態。

檢查 Iceberg 中繼資料產生狀態

UniForm 會將下列欄位新增至 Unity Catalog 和 Iceberg 資料表中繼資料，以追蹤中繼資料產生狀態：

中繼資料欄位	描述
`converted_delta_version`	已成功產生 Iceberg 中繼資料的 Delta 資料表最新版本。
`converted_delta_timestamp`	已成功產生 Iceberg 中繼資料的最新 Delta 提交的時間戳記。

在 Azure Databricks 上，您可以執行下列其中一項來檢閱這些中繼資料欄位：

檢閱 DESCRIBE EXTENDED table_name 傳回的 Delta Uniform Iceberg 部分。
使用目錄總管檢閱資料表中繼資料。
使用 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

在 Azure Databricks 上，您可以執行下列其中一項來檢閱此中繼資料位置：

檢閱 DESCRIBE EXTENDED table_name 傳回的 Delta Uniform 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。如需組態詳細資料，請參閱 Iceberg 讀取器用戶端文件。

驗證與授權

使用外部服務中的 api/2.1/unity-catalog/iceberg 端點存取 Unity Catalog 中註冊的資料有兩個需求：

使用 OAuth 或 Databricks 個人存取權杖進行驗證。請參閱驗證 Azure Databricks 資源的存取權限。
為中繼存放區啟用外部資料存取。這會將存取限制為對從中讀取 API 的結構描述具有 EXTERNAL USE SCHEMA 權限的使用者。請參閱控制 Unity 目錄中資料的外部存取。

Apache Spark 設定範例

以下是用於設定 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.type": "rest",
"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.warehouse": "<uc_catalog_name>"

將產生個人存取權杖之工作區的完整 URL 取代為 <api-root>。

當您使用 Spark 組態查詢 Unity 目錄中的資料表時，請記住下列事項：

物件識別碼會使用模式 unity.<schema-name>.<table-name>。

此模式使用 Unity 目錄中使用的相同三層命名空間，但目錄名稱會由 unity 取代。
只有當您在執行 Iceberg 特定的預存程序時，才需要 "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"。
如果您為儲存體使用雲端提供者，必須將雲端特定的 Iceberg 套件組合 jar 新增為 Spark 套件：
- AWS：org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
- Azure：org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
- GCP：org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>
如需詳細資訊，請參閱 Spark 的 Iceberg AWS 整合文件。

REST API curl 範例

您也可使用此 curl 範例中的 REST API 呼叫來載入資料表：

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

然後，您應會收到如下的回覆：

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

注意

回覆中的 expires-at-ms 欄位會指出認證的到期時間，且預設的到期時間為 1 小時。為了獲得更好的效能，請在要求新認證之前，讓用戶端快取認證，直到逾期為止。

限制

所有 UniForm 資料表都存在下列限制：

UniForm 不適用於已啟用刪除向量的資料表。請參閱什麼是刪除向量？。
已啟用 UniForm 的差異資料表不支援 VOID 類型。
Iceberg 用戶端只能從 UniForm 讀取。不支援寫入。
無論 UniForm 為何，Iceberg 讀取器用戶端可能都擁有單獨的限制。請參閱所選用戶端的文件。
即使啟用了 UniForm，Delta Sharing 的收件者也只能將資料表讀取為 Delta。
某些 Delta Sharing 讀取器用戶端不支援 UniForm Iceberg 使用的一些 Delta Lake 資料表功能。請參閱什麼是 Delta Sharing？。

啟用 UniForm 時，變更資料摘要適用於 Delta 用戶端，但在 Iceberg 中沒有支援。

共用方式為