設定表格選項

您可以使用 Lakehouse 執行階段目錄中的資料表選項，為 Apache Iceberg 資料表選擇加入 BigQuery DML 寫入互通性和資料表管理 (自動儲存空間最佳化) 功能。

如要進一步瞭解 Lakehouse 執行階段目錄支援的資料表格式和選用功能，請參閱「比較資料表類型」和「Apache Iceberg 資料表總覽」。

事前準備

  1. 確認 Google Cloud 專案已啟用計費功能。

  2. 啟用 BigLake API (如果尚未啟用)。

    啟用 API 所需的角色

    您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

  3. 使用 Apache Iceberg REST 目錄端點設定 Lakehouse 執行階段目錄。

必要的角色

如要取得設定資料表選項所需的權限，請要求管理員授予您專案和 Storage bucket 的下列 IAM 角色：

  • 在憑證販售模式中設定資料表屬性：BigLake 編輯者 (roles/biglake.editor) - 專案
  • 在非憑證臨時配發模式中設定資料表屬性：
    • BigLake 編輯者 (roles/biglake.editor) - 專案
    • Storage 物件使用者 (roles/storage.objectUser) - Cloud Storage bucket

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

設定考量

設定資料表選項時，請考量下列需求和預設行為：

支援的 Iceberg 資料表

雖然 Lakehouse 執行階段目錄支援 Apache Iceberg V2 (正式發布版) 和 V3 (預先發布版) 資料表，但代管功能 (BigQuery DML 和資料表管理) 僅支援 Iceberg V2 資料表。不支援 Iceberg V1 資料表。如要升級現有的 V1 資料表，請參閱「將 Iceberg V1 資料表升級至 V2」。

憑證臨時配發需求

如要選擇加入資料表管理功能，Lakehouse 執行階段目錄必須在目錄層級啟用憑證販售。資料表管理背景工作會使用憑證販售服務帳戶，驗證及更新基礎儲存空間資料檔案。

啟用 BigQuery DML

啟用 BigQuery data manipulation language (DML) 陳述式，即可從 BigQuery 對使用開放原始碼引擎建立的 Apache Iceberg 資料表執行寫入互通性。

支援的陳述式包括 INSERT、UPDATE、DELETE 和 MERGE，以及標準 DDL 陳述式，例如 CREATE TABLE、ALTER TABLE 和 DROP TABLE，但不包括 BigQuery 中 Apache Iceberg 資料表不支援的陳述式。

為新資料表啟用 BigQuery DML

從 BigQuery 建立資料表時，系統會預設啟用 BigQuery DML 和資料表管理功能。從開放原始碼引擎建立資料表時，請使用引擎的 DDL 語法設定 gcp.biglake.bigquery-dml.enabled = true 資料表屬性。

例如，在 Spark SQL 中：

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

為現有資料表啟用 BigQuery DML

如要在現有資料表上啟用 BigQuery DML，請更新資料表屬性。

例如，在 Spark SQL 中：

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

停用 BigQuery DML

停用 BigQuery DML 後，BigQuery 資料表會變成唯讀，且資料表管理作業會停止。

例如，在 Spark SQL 中：

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

啟用表格管理功能

資料表管理功能會自動執行背景程序，最佳化儲存空間並管理資料和中繼資料生命週期，例如壓縮和垃圾收集。

資料表管理功能可讓您執行下列作業：

  • 快照到期和垃圾收集：快照到期功能可管理資料表快照中資料和中繼資料檔案的保留和刪除作業。只要資料有任何異動，這項作業就會在背景自動執行。快照會根據使用者設定的 Iceberg 資料表屬性 history.expire.max-snapshot-age-ms 和 history.expire.min-snapshots-to-keep 到期。方法是在新的中繼資料檔案中建立額外的快照定義，並省略對已移除快照的參照，藉此移除過期的快照項目。

    • 限制：如果資料表使用標記或分支版本，系統會略過快照到期和相關聯的垃圾收集作業。詳情請參閱「限制」一節。

    • 限制：資料表管理功能不會移除孤立檔案。詳情請參閱「限制」一節。

  • Coalesce (壓縮)：Coalesce 會將零碎的小檔案合併成較大的檔案，藉此維持資料形狀和查詢效能。資料變動後，系統會在背景評估合併作業。如果檔案的平均未壓縮大小小於目標檔案大小 (256 MB) 的 50%，則符合壓縮條件。每項聯合運算都會產生新的資料表快照。合併工作通常會讓位給任何執行中的 DML 作業，並在作業完成後重試。不過，為避免儲存空間最佳化作業無限期停滯，如果資料符合壓縮條件，系統會每 24 小時強制觸發一次聯合工作。

    並非所有資料異動、插入或 DML 陳述式都會觸發儲存空間最佳化工作。儲存空間最佳化工作會在專案中執行，並耗用運算資源。為避免產生不必要的運算費用，BigQuery 會評估資料表形狀，判斷是否需要最佳化，並在下列情況下略過最佳化：

    • 資料檔案已處於最佳狀態：如果檔案大小適中 (平均未壓縮大小至少為 256 MB 目標檔案大小的 50%)，則不需要壓縮。
    • 未達門檻：如果資料表累積的小檔案不夠多，或未超過資料表大小下限門檻 (例如小於 1 GB 的資料表)，系統就會略過最佳化作業。

    如果資料已處於最佳狀態，系統會略過儲存空間最佳化作業，不會執行任何背景工作。

  • 監控資料表管理工作：所有背景資料表管理工作都會記錄在 BigQuery 的 INFORMATION_SCHEMA.JOBS 檢視表中。您可以查詢這個檢視表來追蹤這些作業，方法與監控其他 BigQuery 工作類似。如要進一步瞭解如何查詢工作資訊，請參閱「取得 Iceberg 儲存空間最佳化工作」。

    資料表管理工作的頻率與資料異動活動和檔案分散程度有關。頻繁的小型插入或更新作業會觸發更頻繁的背景工作。如果沒有寫入資料表的作業，您可能會發現某些時段沒有背景工作。如果略過儲存空間最佳化 (例如，因為資料是以大型批次載入，且檔案已最佳化)，則該作業的 INFORMATION_SCHEMA.JOBS 中不會顯示任何工作，這是預期行為。

    如要在測試或開發環境中觀察資料表管理工作，請在一段時間內將多個小批次資料插入總大小超過 1 GB 的資料表。這會產生小型、分散的檔案，這些檔案的大小低於 50% 的目標大小門檻，並觸發壓縮。

選擇是否啟用桌位管理功能

如果 Apache Iceberg 資料表是由 Lakehouse 執行階段目錄管理，並透過 Apache Iceberg REST 目錄端點提供，您可以啟用資料表管理功能，也可以使用開放原始碼或第三方引擎自行管理資料表維護作業 (例如壓縮和快照到期)。

如果符合下列所有條件，請啟用表格管理功能 (gcp.biglake.table-management.enabled = true)：

  • 您希望在 DML 或開放原始碼串流寫入後，自動在背景壓縮檔案 (合併)，並自動清除過期快照和垃圾。

  • 目錄採用憑證臨時配發模式。

  • 快照保留和時間旅行時間範圍最多 7 天 (預設為 5 天)，符合您的需求。

  • 資料表符合代管功能的需求條件 (請參閱「限制」)。

如果符合下列任一條件，請停用資料表管理功能 (從開放原始碼引擎建立的資料表預設為停用，或設定 gcp.biglake.table-management.enabled = false)，並自行管理資料表維護作業：

  • 您在 Apache Spark、Apache Flink 或 Trino 等開放原始碼引擎中，執行自訂壓縮或維護程序，尤其是資料表依賴 z 排序或線性排序版面配置，而 coalesce 不會保留這些配置。

  • 資料表使用 Apache Iceberg 快照標記或分支版本 (導致資料表管理作業略過快照到期)，或需要保留快照和時間旅行超過 7 天。

  • 目錄使用使用者憑證 (直接 Cloud Storage Identity and Access Management (IAM) 權限)，而非憑證販售模式。

  • 資料表使用的功能不受代管功能支援 (在這種情況下，資料表管理和 BigQuery DML 都必須保持停用狀態)，例如 Apache Iceberg 格式版本 3、讀取時合併模式、多欄或 IDENTITY 分區，或自訂客戶資料和中繼資料儲存路徑。如需不支援功能的完整清單，請參閱「限制」。

為新資料表啟用資料表管理功能

從 BigQuery 建立資料表時，系統會預設啟用 DML 和資料表管理功能。從開放原始碼引擎建立資料表時，請設定 gcp.biglake.table-management.enabled 屬性。啟用資料表管理功能時，系統會自動啟用 BigQuery DML (如果尚未啟用)。

例如，在 Spark SQL 中：

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

為現有資料表啟用資料表管理功能

如要為現有資料表啟用資料表管理功能，請更新資料表屬性。

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

BigQuery

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "enabled");

停用資料表管理功能

停用資料表管理功能後，系統就不會將日後的背景最佳化工作排入佇列，但會完成進行中的工作。停用資料表管理功能不會停用 BigQuery DML。

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);

BigQuery

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");

限制

代管功能 (例如 BigQuery 寫入互通性和資料表管理) 的限制包括：

一般限制

  • 只有在 Lakehouse 執行階段目錄中，使用 Apache Iceberg REST 目錄端點建立的 Apache Iceberg 資料表，才支援代管功能。
  • BigQuery 管理的 Apache Iceberg 資料表現有所有限制，均適用於啟用管理功能的作業。
  • 採用 Apache Iceberg 格式版本 3 的資料表不支援代管功能。只有格式版本 2 (Iceberg v2 規格) 的資料表，才能選擇加入代管功能。
  • 如果資料表採用進階分區功能，例如依 STRING 分區、多欄分區或分區演進，則不支援代管功能。
  • 如果資料表已設定排列順序 (例如使用 WRITE ORDER BY 程序或設定 write.distribution.mode = range)，則不支援代管功能。
  • 使用讀取時合併模式的 Iceberg v2 資料表不支援代管功能。只有使用寫入時複製更新、刪除和合併模式的資料表，才能選擇加入代管功能。
  • 代管功能不支援使用 gzip、lz4 或 brotli 轉碼器 (write.parquet.compression-codec) 壓縮的資料檔案。資料檔案僅支援 zstd 和 snappy 壓縮類型。
  • 如果資料表的結構定義包含巢狀主鍵 ID (identifier-field-ids)，且該 ID 參照結構中的巢狀路徑或欄位，則不支援代管功能。
  • 如果資料表含有自訂資料或中繼資料位置 (write.data.path 和 write.metadata.path)，則不支援代管功能。您必須使用預設的 Cloud Storage bucket 位置，才能保存資料和中繼資料檔案。
  • BigQuery 分群不支援由 Lakehouse 執行階段目錄管理的 Apache Iceberg 資料表。
  • 如果資料表是在 BigQuery 中以 NUMERIC 資料類型建立，則 Spark 的任何結構定義更新都會失敗，因為 Spark 會將 NUMERIC 讀取為 NUMERIC(38,9)。如要解決這個問題，請在 BigQuery 中建立 NUMERIC 類型的資料表時，明確將精確度設為 NUMERIC(38,9)。
  • 已知問題：不支援使用 DDL (ALTER TABLE ... DROP COLUMN) 在 BigQuery 中捨棄資料欄，然後立即重新加入同名資料欄。

時間旅行的限制

  • 啟用資料表管理功能後，history.expire.max-snapshot-age-ms 屬性的最大允許值為 30 天 (2592000000 毫秒)，建議最大值為 7 天 (604800000 毫秒)。history.expire.min-snapshots-to-keep 屬性的最大允許值為 100。
  • BigQuery 專案層級或資料集層級的時間旅行設定不適用。只有 Iceberg 資料表屬性和預設值會生效。

資料表管理限制

  • 如果資料表包含具有標記或分支版本的快照，系統會略過整個資料表的快照到期時間。系統會忽略使用 ALTER... RETAIN x DAYS 設定的自訂保留期限，以及為 history.expire.max-ref-age-ms 屬性設定的任何值。開放原始碼引擎仍可執行快照到期作業。
  • 資料表管理功能不會讓結構定義或分區規格過期。metadata.json 檔案會保留結構定義和分區規格的完整記錄，即使沒有任何快照參照這些結構定義 ID 也是如此。

  • 資料表管理功能不會清除 BigQuery 或開放原始碼引擎建立的孤立檔案。開放原始碼引擎可以執行孤立檔案清理作業 (例如使用 Spark remove_orphan_files 程序，並將 prefix_listing 選項設為 true)。

  • Coalesce 不支援 Z 軸排序和線性排序。如果資料表包含這些屬性，則無法保證在合併執行後仍能維持版面配置。如果資料表包含這些屬性，請勿啟用資料表管理功能。

分區限制

  • 從開放原始碼引擎建立或註冊資料表時，代管功能僅支援對 DATE、DATETIME 和 TIMESTAMP 欄位類型進行分區，並使用 hour、day、month 和 year 轉換 (DATE 欄位上的 hour 轉換除外)，以及 INTEGER 欄位類型。
  • 含有 IDENTITY 轉換作業的資料表不支援代管功能。您必須明確指定轉換。
  • 只有在使用相同分區規格時，才支援對具有代管功能的資料表執行 CREATE OR REPLACE 指令。不支援下列替換作業：
    • 將非分區資料表替換為分區資料表。
    • 將分區資料表替換為非分區資料表。
    • 將分區資料表替換為使用不同分區規格的資料表。
  • 不支援自訂分區欄位命名。從開放原始碼引擎建立或註冊的資料表，必須遵循引擎的預設分區欄位命名慣例 (附加 _ 和轉換名稱，例如 _hour、_day、_month 或 _year)。舉例來說，如果欄位名稱為 time_date，且使用 DAY 轉換，則預期的分區欄位值為：json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

自訂 Iceberg 資料表屬性的限制

啟用代管功能時，下列資料表行為屬性無法設為非預設值。啟用任何受管理功能時，系統會硬式編碼預設值：

屬性 預設值 詳細資料
format-version 2 代管功能僅支援 Iceberg v2 資料表。
write.format.default parquet 資料表僅支援 Parquet 格式的資料檔案。
write.data.path table location + /data 系統會使用為 Apache Iceberg REST 目錄端點設定的預設 Cloud Storage bucket 路徑，寫入資料檔案。
write.metadata.path table location + /metadata 系統會使用為 Apache Iceberg REST 目錄端點設定的預設 Cloud Storage bucket 路徑，寫入中繼資料檔案。
write.delete.mode copy-on-write BigQuery 寫入和資料表管理工作僅支援寫入時複製。
write.update.mode copy-on-write BigQuery 寫入和資料表管理工作僅支援寫入時複製。
write.merge.mode copy-on-write BigQuery 寫入和資料表管理工作僅支援寫入時複製。
write.delete.isolation-level 嚴格衝突偵測 如果變更會修改 metadata.json 檔案 (包括資料衝突、中繼資料衝突、幻讀或非衝突並行寫入)，並行交易就會失敗並重試。
write.update.isolation-level 嚴格衝突偵測 行為與 write.delete.isolation-level 相同。
write.merge.isolation-level 嚴格衝突偵測 行為與 write.delete.isolation-level 相同。

從開放原始碼引擎建立或修改資料表時，可以設定下列屬性：

屬性 預設值 詳細資料
write.parquet.compression-codec zstd BigQuery 寫入和儲存空間最佳化功能僅支援 zstd 和 snappy 壓縮格式。不支援其他壓縮格式 (例如 gzip、brotli 和 lz4)。
write.metadata.compression-codec null 可設為 null 或 gzip。
history.expire.max-snapshot-age-ms 432000000 (5 天) 啟用資料表管理功能後，可設為任何非負整數，最大值為 2592000000 (30 天)，建議最多 7 天 (604800000 毫秒)。資料表管理工作會刪除超過指定時間長度的快照。
history.expire.min-snapshots-to-keep 1 啟用表格管理功能後，可設為任何正整數，最大值為 100。資料表管理工作至少會保留這個數量的快照。

其他 Apache Iceberg 寫入屬性 (例如 write.target-file-size-bytes 和 write.parquet.page-size-bytes) 可透過開放原始碼引擎設定，但 BigQuery 寫入和資料表管理工作可能不符合這些屬性。

後續步驟