搭配 OneLake 使用 Iceberg 數據表
在 Microsoft OneLake 中,您可以建立 Apache Iceberg 數據表的快捷方式,使其可在各種不同的網狀架構工作負載中使用。 這項功能可透過稱為 元數據虛擬化的功能來達成,其可讓 Iceberg 數據表從快捷方式的觀點解譯為 Delta Lake 數據表。 當您建立 Iceberg 資料表資料夾的快捷方式時,OneLake 會自動產生該數據表的對應 Delta Lake 元數據(Delta 記錄),讓 Delta Lake 元數據可透過快捷方式存取。
重要
此功能處於預覽。
雖然本文包含將 Iceberg 數據表從 Snowflake 撰寫至 OneLake 的指導方針,但這項功能旨在與任何 Iceberg 數據表搭配 Parquet 數據檔使用。
建立 Iceberg 資料表的數據表快捷方式
如果您已經在 OneLake 快捷方式支援的儲存位置中有 Iceberg 數據表,請遵循下列步驟來建立快捷方式,並讓 Iceberg 數據表以 Delta Lake 格式出現。
找出您的 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
檔案。在您的 Fabric Lakehouse 中,在未啟用架構的 Lakehouse 的 [數據表] 區域中建立新的快捷方式。
注意
如果您在 Lakehouse 的 [資料表] 資料夾下看到架構
dbo
,則 lakehouse 會啟用架構,且尚未與這項功能相容。針對快捷方式的目標路徑,選取 Iceberg 資料表資料夾。 Iceberg 資料表資料夾包含
metadata
和data
資料夾。建立快捷方式之後,您應該會自動看到此數據表反映為 Lakehouse 中的 Delta Lake 數據表,準備好在整個 Fabric 中使用。
如果您的新 Iceberg 數據表快捷方式未顯示為可使用的數據表,請檢查 [疑難解答] 區段。
使用 Snowflake 將 Iceberg 數據表寫入 OneLake
如果您在 Azure 上使用 Snowflake,您可以遵循下列步驟,將 Iceberg 數據表寫入 OneLake:
請確定您的 Fabric 容量位於與 Snowflake 實例相同的 Azure 位置。
識別與您的 Fabric Lakehouse 相關聯的 Fabric 容量位置。 開啟包含 Lakehouse 的 Fabric 工作區設定。
在 Azure 帳戶介面上 Snowflake 的左下角,檢查 Snowflake 帳戶的 Azure 區域。
如果這些區域不同,您必須在與 Snowflake 帳戶相同的區域中使用不同的 Fabric 容量。
開啟 Lakehouse [檔案] 區域的功能表,選取 [屬性],然後複製該資料夾的 URL (HTTPS 路徑)。
識別您的網狀架構租用戶標識碼。 選取網狀架構 UI 右上角的使用者配置檔,並將滑鼠停留在租使用者名稱旁邊的資訊泡泡上。 複製 [租用戶識別碼]。
在 Snowflake 中,使用 Lakehouse 中 [檔案] 資料夾的路徑來設定
EXTERNAL VOLUME
。 如需設定 Snowflake 外部磁碟區的詳細資訊,請參閱這裡。注意
Snowflake 要求 URL 配置為
azure://
,因此請務必變更https://
為azure://
。CREATE OR REPLACE EXTERNAL VOLUME onelake_exvol STORAGE_LOCATIONS = ( ( NAME = 'onelake_exvol' STORAGE_PROVIDER = 'AZURE' STORAGE_BASE_URL = 'azure://<path_to_Files>/icebergtables' AZURE_TENANT_ID = '<Tenant_ID>' ) );
在此範例中,使用此外部磁碟區建立的任何數據表會儲存在資料夾內的
Files/icebergtables
Fabric Lakehouse 中。現在已建立外部磁碟區,請執行下列命令來擷取 Snowflake 用來寫入 OneLake 之應用程式的同意 URL 和名稱。 此應用程式會由 Snowflake 帳戶中的任何其他外部磁碟區使用。
DESC EXTERNAL VOLUME onelake_exvol;
此命令的輸出會
AZURE_CONSENT_URL
傳回 和AZURE_MULTI_TENANT_APP_NAME
屬性。 記下這兩個值。 Azure 多租使用者應用程式名稱看起來像<name>_<number>
,但您只需要擷取部分<name>
。在新瀏覽器索引標籤中開啟上一個步驟的同意 URL。如果您想要繼續,請視提示同意必要的應用程式許可權。
回到 [網狀架構],開啟您的工作區,然後選取 [ 管理存取權],然後 [新增人員或群組]。 授與 Snowflake 外部磁碟區所使用的應用程式,授與將數據寫入工作區中 lakehouses 所需的許可權。 建議授與 參與者 角色。
回到 Snowflake,使用新的外部磁碟區來建立 Iceberg 數據表。
CREATE OR REPLACE ICEBERG TABLE MYDATABASE.PUBLIC.Inventory ( InventoryId int, ItemName STRING ) EXTERNAL_VOLUME = 'onelake_exvol' CATALOG = 'SNOWFLAKE' BASE_LOCATION = 'Inventory/';
使用此語句時,會在外部磁碟區中定義的資料夾路徑內建立名為 Inventory 的新 Iceberg 資料表資料夾。
將一些數據新增至 Iceberg 數據表。
INSERT INTO MYDATABASE.PUBLIC.Inventory VALUES (123456,'Amatriciana');
最後,在相同湖屋的 [數據表] 區域中, 您可以建立 Iceberg 數據表的 OneLake 快捷方式。 透過該快捷方式,您的 Iceberg 數據表會顯示為 Delta Lake 數據表,以供跨網狀架構工作負載取用。
疑難排解
下列秘訣可協助確定您的 Iceberg 數據表與這項功能相容:
檢查 Iceberg 資料表的資料夾結構
在慣用的記憶體總管工具中開啟 Iceberg 資料夾,並在原始位置檢查 Iceberg 資料夾的目錄清單。 您應該會看到資料夾結構,例如下列範例。
../
|-- MyIcebergTable123/
|-- data/
|-- snow_A5WYPKGO_2o_APgwTeNOAxg_0_1_002.parquet
|-- snow_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
資料夾。
限制與考量
當您使用這項功能時,請記住下列暫時性限制:
支援的資料類型
下列 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
類型寬度問題
如果您使用 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.enableVectorizedReader
false
來解決此錯誤。 以下是在 Spark 筆記本中執行的範例 PySpark 命令:spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")
Iceberg 數據表元數據記憶體無法移植
Iceberg 數據表的元數據檔案會使用絕對路徑參考彼此參考。 如果您複製或移動 Iceberg 資料表的資料夾內容至另一個位置,而不需要重寫 Iceberg 元數據檔案,則 Iceberg 讀者無法讀取該數據表,包括此 OneLake 功能。
因應措施:
如果您需要將 Iceberg 數據表移至另一個位置以使用這項功能,請使用原本撰寫 Iceberg 數據表的工具,在所需的位置中撰寫新的 Iceberg 數據表。
冰山錶必須比根層級更深
記憶體中的 Iceberg 資料表資料夾必須位於比貯體或容器層級更深的目錄中。 儲存在貯體或容器根目錄中的 Iceberg 資料表可能無法虛擬化為 Delta Lake 格式。
我們正努力改善以移除此需求。
因應措施:
請確定任何 Iceberg 資料表都儲存在比貯體或容器根目錄更深的目錄中。
Iceberg 資料表資料夾必須只包含一組元數據檔案
如果您在 Snowflake 中卸除並重新建立 Iceberg 數據表,則不會清除元數據檔案。 此行為支援
UNDROP
Snowflake 中的功能。 不過,由於您的快捷方式直接指向資料夾,而且該資料夾內現在有多個元數據檔案集,因此除非您移除舊數據表的元數據檔案,否則無法轉換數據表。目前,在此案例中嘗試轉換,這可能會導致虛擬化 Delta Lake 數據表中顯示的舊數據表內容和架構資訊。
我們正在處理修正,如果在 Iceberg 數據表的元數據資料資料夾中找到一組以上的元數據檔案,轉換就會失敗。
因應措施:
若要確保已轉換的數據表反映資料表的正確版本:
- 請確定您未將多個 Iceberg 資料表儲存在相同的資料夾中。
- 在卸除 Iceberg 資料表資料夾之後清除任何內容,再重新建立數據表。
元數據變更未立即反映
如果您對 Iceberg 資料表進行元數據變更,例如新增數據行、刪除數據行、重新命名數據行或變更數據行類型,則在進行數據變更之前,可能不會重新轉換數據表,例如新增數據列。
我們正在進行修正,以挑選包含最新元數據變更的正確最新元數據檔案。
因應措施:
對 Iceberg 數據表進行架構變更之後,請新增一列數據,或對數據進行任何其他變更。 在該變更之後,您應該能夠在 Fabric 中重新整理並查看數據表的最新檢視。
尚未支援已啟用架構的工作區
如果您在已啟用架構的 Lakehouse 中建立 Iceberg 快捷方式,則不會針對該快捷方式進行轉換。
我們正努力改善以移除這項限制。
因應措施:
使用已啟用非架構的 Lakehouse 搭配這項功能。 您可以在 Lakehouse 建立期間設定此設定。
區域可用性限制
此功能尚無法在下列區域中使用:
- 卡達中部
- 挪威西部
因應措施:
附加至其他區域中 Fabric 容量的工作區可以使用此功能。 請參閱可用Microsoft網狀架構之區域的完整清單。
不支援私人連結
已啟用私人連結的租使用者或工作區目前不支援此功能。
我們正努力改善以移除這項限制。
表格大小限制
此功能所支援的 Iceberg 資料表大小有暫時限制。 Parquet 數據檔的最大支援數目約為 5,000 個數據檔,或大約 10 億個數據列,無論第一次遇到限制。
我們正努力改善以移除這項限制。
OneLake 快捷方式必須是相同區域
我們暫時限制使用此功能與指向 OneLake 位置的快捷方式:快捷方式的目標位置必須與快捷方式本身位於相同的區域中。
我們正努力改善以移除此需求。
因應措施:
如果您在另一個湖屋有 Iceberg 數據表的 OneLake 快捷方式,請確定另一個湖屋與相同區域中的容量相關聯。
相關內容
- 深入瞭解 Fabric 和 OneLake 安全性。
- 深入瞭解 OneLake 快捷方式。