設定表格選項

您可以使用 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 負責維護資料形狀，將小型檔案合併為大型檔案。只要資料發生任何異動，Coalesce 就會在背景自動執行。如果檔案的平均未壓縮大小小於目標檔案大小 (256 MB) 的 50%，系統就會選取這些檔案進行壓縮。每項合併作業都會產生新的資料表快照。合併工作通常會讓路給任何執行中的 DML 作業，並在作業完成後重試。不過，為避免儲存空間最佳化作業無限期停滯，如果資料符合合併條件，系統每 24 小時會強制觸發合併工作。

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

  資料表管理工作的頻率與資料異動活動直接相關。頻繁插入或更新少量資料，會觸發更頻繁的背景工作。如果沒有寫入資料表的作業，您可能會發現一段時間內沒有背景工作。相反地，如果寫入量較高，INFORMATION_SCHEMA 中的工作活動可能會更明顯。

選擇是否啟用資料表管理功能

如果 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);

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

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

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

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

停用表格管理功能

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

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

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 會將 NUMERIC 讀取為 NUMERIC(38,9)，因此任何來自 Spark 的結構定義更新都會失敗。如要解決這個問題，請在 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 資料表屬性的限制

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

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

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

後續步驟

• 瞭解如何使用 BigQuery DML 修改資料。
• 瞭解如何查詢資料表。