搭配 OneLake 使用 Iceberg 數據表

在 Microsoft OneLake 中，您可以順暢地使用 Delta Lake 和 Apache Iceberg 格式的數據表。

這項彈性是透過 元數據虛擬化來啟用，此功能可讓 Iceberg 資料表解譯為 Delta Lake 數據表，反之亦然。 您可以直接撰寫 Iceberg 數據表或建立其快捷方式，讓這些數據表可在各種網狀架構工作負載之間存取。 同樣地，使用 Iceberg 讀取器也可以讀取以 Delta Lake 格式撰寫的網狀架構數據表。

當您撰寫或建立 Iceberg 資料表資料夾的快捷方式時，OneLake 會自動為資料表產生虛擬 Delta Lake 元數據 （Delta log），使其與 Fabric 工作負載搭配使用。 相反地，Delta Lake 數據表現在包含虛擬 Iceberg 元數據，允許與 Iceberg 讀取器相容。

雖然本文包含搭配 Snowflake 使用 Iceberg 數據表的指引，但這項功能旨在與儲存中具有 Parquet 格式數據檔的任何 Iceberg 數據表搭配使用。

將 Delta Lake 數據表虛擬化為 Iceberg

若要設定從 Delta Lake 格式到 Iceberg 格式的數據表自動轉換和虛擬化，請遵循下列步驟。

1. 在您的工作區設定中，開啟名為 Enable Delta Lake to Apache Iceberg 數據表格式虛擬化 的委派 OneLake 設定，以啟用 Delta Lake 表格的自動虛擬化至 Iceberg 格式。

   注意

   此設定可控制目前處於預覽狀態的功能。 當所有使用者啟用此功能且不再處於預覽狀態時，將會在未來的更新中移除此設定。

2. 請確定您的 Delta Lake 數據表或它的快捷方式位於 Tables 數據項的 區段中。 數據項可能是 Lakehouse 或其他 Fabric 數據項。

   小提示

   如果您的 Lakehouse 已開啟架構，則您的資料表目錄會直接位於 架構中，例如 dbo。 如果您的 Lakehouse 未啟用架構，那麼您的資料表目錄將直接位於 Tables 目錄內。

3. 確認您的 Delta Lake 數據表已成功轉換為虛擬 Iceberg 格式。 您可以藉由檢查資料表背後的目錄來執行此動作。

   若要在 Lakehouse 中檢視目錄，您可以在 Fabric UI 中的數據表上按兩下滑鼠右鍵，然後選取 [ 檢視檔案]。

   如果您的數據表位於另一個數據項類型，例如倉儲、資料庫或鏡像資料庫，您必須使用 Azure 記憶體總管或 OneLake 檔案總管之類的用戶端，而不是 Fabric UI 來檢視數據表後面的檔案。

4. 您應該會在資料表資料夾內看到名為 metadata 的目錄，而且應該包含多個檔案，包括轉換記錄檔。 開啟轉換記錄檔，以查看 Delta Lake 到 Iceberg 轉換的詳細資訊，包括最近轉換的時間戳和任何錯誤詳細數據。

5. 如果轉換記錄檔顯示數據表已成功轉換，請使用您選擇的服務、應用程式或連結庫來讀取 Iceberg 資料表。

   取決於您所使用的 Iceberg 讀取器，您必須知道資料表目錄的路徑或目錄中顯示的最新.metadata.json檔案。

   您可以開啟具有最高版本號碼之檔案的 [ 屬性 ] 檢視 *.metadata.json ，以查看數據表最新元數據檔案的 HTTP 路徑。 記下此路徑。

   資料項目 Tables 資料夾的路徑可能如下所示：

   https://onelake.dfs.fabric.microsoft.com/83896315-c5ba-4777-8d1c-e4ab3a7016bc/a95f62fa-2826-49f8-b561-a163ba537828/Tables/
   

   在該資料夾中，最新元資料檔案的相對路徑可能看起來像 dbo/MyTable/metadata/321.metadata.json。

   若要使用 Snowflake 讀取虛擬 Iceberg 數據表， 請遵循本指南中的步驟。

建立 Iceberg 資料表的數據表快捷方式

如果您已經在 OneLake 快捷方式支援的儲存位置中有 Iceberg 數據表，請遵循下列步驟來建立快捷方式，並讓 Iceberg 數據表以 Delta Lake 格式出現。

1. 找出您的 Iceberg 數據表。 尋找您的 Iceberg 數據表儲存位置，其可能位於 Azure Data Lake Storage、OneLake、Amazon S3、Google Cloud Storage 或 S3 相容的記憶體服務中。

   注意

   如果您使用 Snowflake，且不確定 Iceberg 數據表的儲存位置，您可以執行下列語句來查看 Iceberg 數據表的儲存位置。

   SELECT SYSTEM$GET_ICEBERG_TABLE_INFORMATION('<table_name>');

   執行此語句會傳回 Iceberg 數據表元數據檔案的路徑。 此路徑會告訴您哪個記憶體帳戶包含 Iceberg 數據表。 例如，以下是尋找儲存在 Azure Data Lake Storage 中的 Iceberg 數據表路徑的相關信息：

   {"metadataLocation":"azure://<storage_account_path>/<path_within_storage>/<table_name>/metadata/00001-389700a2-977f-47a2-9f5f-7fd80a0d41b2.metadata.json","status":"success"}

   您的 Iceberg 資料表資料夾必須包含資料夾，其本身至少包含一個 metadata 結尾為的 .metadata.json檔案。

2. 在您的 Fabric Lakehouse 中，在 Lakehouse 的 [數據表] 區域中建立新的數據表快捷方式。

   小提示

   如果您在 Lakehouse 的 Tables 資料夾下看到 dbo 之類的架構，則 lakehouse 會啟用架構。 在此情況下，以滑鼠右鍵單擊架構，然後在架構下建立資料表捷徑。

   

3. 針對快捷方式的目標路徑，選取 Iceberg 資料表資料夾。 Iceberg 資料表資料夾包含 metadata 和 data 資料夾。

4. 建立快捷方式之後，您應該會自動看到此數據表反映為 Lakehouse 中的 Delta Lake 數據表，準備好在整個 Fabric 中使用。

   

   如果您的新 Iceberg 數據表快捷方式未顯示為可使用的數據表，請檢查 [疑難解答] 區段。

疑難排解

下列秘訣可協助確定您的 Iceberg 數據表與這項功能相容：

檢查 Iceberg 資料表的資料夾結構

在慣用的記憶體總管工具中開啟 Iceberg 資料夾，並在原始位置檢查 Iceberg 資料夾的目錄清單。 您應該會看到資料夾結構，例如下列範例。

../
|-- MyIcebergTable123/
    |-- data/
        |-- A5WYPKGO_2o_APgwTeNOAxg_0_1_002.parquet
        |-- A5WYPKGO_2o_AAIBON_h9Rc_0_1_003.parquet
    |-- metadata/
        |-- 00000-1bdf7d4c-dc90-488e-9dd9-2e44de30a465.metadata.json
        |-- 00001-08bf3227-b5d2-40e2-a8c7-2934ea97e6da.metadata.json
        |-- 00002-0f6303de-382e-4ebc-b9ed-6195bd0fb0e7.metadata.json
        |-- 1730313479898000000-Kws8nlgCX2QxoDHYHm4uMQ.avro
        |-- 1730313479898000000-OdsKRrRogW_PVK9njHIqAA.avro
        |-- snap-1730313479898000000-9029d7a2-b3cc-46af-96c1-ac92356e93e9.avro
        |-- snap-1730313479898000000-913546ba-bb04-4c8e-81be-342b0cbc5b50.avro

如果您沒有看到元數據資料夾，或如果您沒有看到此範例中所顯示擴展名的檔案，則您可能沒有正確產生的 Iceberg 資料表。

檢查轉換記錄檔

當 Iceberg 資料表虛擬化為 Delta Lake 數據表時，可以在快捷方式資料夾內找到名為 _delta_log/ 的資料夾。 此資料夾包含成功轉換後 Delta Lake 格式的元資料 （差異記錄檔）。

此資料夾也包含 latest_conversion_log.txt 檔案，其中包含最近嘗試的轉換成功或失敗詳細數據。

若要在建立快捷方式之後查看此檔案的內容，請在 Lakehouse 的 [數據表] 區域下開啟 Iceberg 數據表快捷方式功能表，然後選取 [ 檢視檔案]。

您應該會看到類似下列範例的結構：

Tables/
|-- MyIcebergTable123/
    |-- data/
        |-- <data files>
    |-- metadata/
        |-- <metadata files>
    |-- _delta_log/   <-- Virtual folder. This folder doesn't exist in the original location.
        |-- 00000000000000000000.json
        |-- latest_conversion_log.txt   <-- Conversion log with latest success/failure details.

開啟轉換記錄檔，以查看最新的轉換時間或失敗詳細數據。 如果您沒有看到轉換記錄檔， 則未嘗試轉換。

如果未嘗試轉換

如果您沒有看到轉換記錄檔，則未嘗試轉換。 以下是嘗試轉換的兩個常見原因：

• 快捷方式未在正確的位置建立。

  為了讓 Iceberg 數據表的快捷方式轉換成 Delta Lake 格式，快捷方式必須直接放在未啟用架構之 Lakehouse 的 Tables 資料夾之下。 如果您想要將數據表自動虛擬化為 Delta Lake 數據表，就不應該將快捷方式放在 [檔案] 區段或另一個資料夾底下。

  

• 快捷方式的目標路徑不是 Iceberg 資料夾路徑。

  當您建立快捷方式時，您在目標儲存位置中選取的資料夾路徑只能是 Iceberg 資料表資料夾。 此資料夾 包含metadata 和 data 資料夾。

  

Snowflake 中的「網狀架構容量區域無法驗證」錯誤訊息

如果您使用 Snowflake 將新的 Iceberg 數據表寫入 OneLake，您可能會看到下列錯誤訊息：

無法驗證網狀架構容量區域。 原因：『無效的存取令牌。 這可能是因為身份驗證和界定範圍的問題。 請確認委派的範圍。

如果您看到此錯誤，請讓 Fabric 租借者管理員再次確認您是否已啟用 使用 Snowflake 將 Iceberg 表格寫入 OneLake 一節中提到的兩個租戶設定：

1. 在網狀架構 UI 的右上角，開啟 [ 設定]，然後選取 [管理入口網站]。
2. 在租用戶設定下的開發人員設定區段中，啟用名為服務主體可以使用 Fabric API的設定。
3. 在相同的區域中，於 [OneLake 設定 ] 區段中，啟用標示為 [使用者可以存取儲存在 OneLake 中的數據與 Fabric 外部應用程式] 的設定。

限制與考量

當您使用這項功能時，請記住下列暫時性限制：

• 支援的資料類型

  下列 Iceberg 數據行數據類型會使用這項功能對應到其對應的 Delta Lake 類型。

  Iceberg 資料行類型	Delta Lake 資料行類型	註解
  int	integer
  long	long	請參閱 類型寬度問題。
  float	float
  double	double	請參閱 類型寬度問題。
  decimal(P, S)	decimal(P, S)	請參閱 類型寬度問題。
  boolean	boolean
  date	date
  timestamp	timestamp_ntz	timestamp Iceberg 數據類型不包含時區資訊。 timestamp_ntz跨網狀架構工作負載不支援 Delta Lake 類型。 建議您搭配包含時區使用時間戳。
  timestamptz	timestamp	在 Snowflake 中，若要使用此類型，請在 Iceberg 數據表建立期間指定 timestamp_ltz 為數據行類型。 如需 Snowflake 中支援的 Iceberg 數據類型詳細資訊，請參閱這裡。
  string	string
  binary	binary
  time	N/A	不支援

• 類型寬度問題

  如果您使用 Snowflake 來撰寫 Iceberg 數據表，且數據表包含數據行類型 INT64、 double或 Decimal 有效位數 >= 10，則產生的虛擬 Delta Lake 數據表可能無法由所有網狀架構引擎取用。 您可能會看到下列錯誤：

  Parquet column cannot be converted in file ... Column: [ColumnA], Expected: decimal(18,4), Found: INT32.
  

  我們正在針對此問題進行修正。

  因應措施： 如果您使用 Lakehouse 數據表預覽 UI 並看到此問題，您可以切換至 SQL 端點檢視（右上角，選取 Lakehouse 檢視，切換至 SQL 端點），並從該處預覽數據表來解決此錯誤。 如果您接著切換回 Lakehouse 檢視，數據表預覽應該會正確顯示。

  如果您執行 Spark 筆記本或作業並遇到此問題，您可以將 Spark 組態設定設定為 spark.sql.parquet.enableVectorizedReaderfalse來解決此錯誤。 以下是在 Spark 筆記本中執行的範例 PySpark 命令：

  spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")
  

• Iceberg 數據表元數據記憶體無法移植

  Iceberg 數據表的元數據檔案會使用絕對路徑參考彼此參考。 如果您複製或移動 Iceberg 資料表的資料夾內容至另一個位置，而不需要重寫 Iceberg 元數據檔案，則 Iceberg 讀者無法讀取該數據表，包括此 OneLake 功能。

  因應措施：

  如果您需要將 Iceberg 數據表移至另一個位置以使用這項功能，請使用原本撰寫 Iceberg 數據表的工具，在所需的位置中撰寫新的 Iceberg 數據表。

• Iceberg 資料表資料夾必須只包含一組元數據檔案

  如果您在 Snowflake 中卸除並重新建立 Iceberg 數據表，則不會清除元數據檔案。 此行為是刻意設計，以支援 Snowflake 中的 UNDROP 功能。 不過，由於您的快捷方式直接指向資料夾，而且該資料夾內現在有多個元數據檔案集，因此除非您移除舊數據表的元數據檔案，否則無法轉換數據表。

  如果在 Iceberg 資料表的元資料資料資料夾中找到一組以上的元資料檔案，轉換將會失敗。

  因應措施：

  若要確保已轉換的數據表反映資料表的正確版本：

  • 請確定您未將多個 Iceberg 資料表儲存在相同的資料夾中。
  • 在卸除 Iceberg 資料表資料夾之後清除任何內容，再重新建立數據表。

• 元數據變更未立即反映

  如果您對 Iceberg 資料表進行元數據變更，例如新增數據行、刪除數據行、重新命名數據行或變更數據行類型，則在進行數據變更之前，可能不會重新轉換數據表，例如新增數據列。

  我們正在進行修正，以挑選包含最新元數據變更的正確最新元數據檔案。

  因應措施：

  對 Iceberg 數據表進行架構變更之後，請新增一列數據，或對數據進行任何其他變更。 在該變更之後，您應該能夠在 Fabric 中重新整理並查看數據表的最新檢視。

• 區域可用性限制

  此功能尚無法在下列區域中使用：

  • 卡達中部
  • 挪威西部

  因應措施：

  附加至其他區域中 Fabric 容量的工作區可以使用此功能。 請參閱可用Microsoft網狀架構之區域的完整清單。

• 不支援私人連結

  已啟用私人連結的租使用者或工作區目前不支援此功能。

  我們正努力改善以移除這項限制。

• OneLake 快捷方式必須是相同區域

  我們暫時限制使用此功能與指向 OneLake 位置的快捷方式：快捷方式的目標位置必須與快捷方式本身位於相同的區域中。

  我們正努力改善以移除此需求。

  因應措施：

  如果您在另一個湖屋有 Iceberg 數據表的 OneLake 快捷方式，請確定另一個湖屋與相同區域中的容量相關聯。

• 某些 Iceberg 分割轉換類型不受支援

  目前不支援 Iceberg 資料分割類型bucket[N]truncate[W]、 和 void 。

  如果要轉換的 Iceberg 數據表包含這些分割區轉換類型，則對 Delta Lake 格式的虛擬化將不會成功。

  我們正努力改善以移除這項限制。

相關內容

• 使用 Snowflake 在 OneLake 中寫入或讀取 Iceberg 數據表。
• 深入瞭解 Fabric 和 OneLake 安全性。
• 深入瞭解 OneLake 快捷方式。