設定表格選項

預覽

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

設定資料表選項後，您就能為 Lakehouse 執行階段目錄中的 Apache Iceberg 資料表，啟用 BigQuery 寫入互通性或資料表管理功能 (自動最佳化儲存空間)。這些選項是基礎設定，可擴充表格作業的功能。

設定特定資料表屬性後，您就能啟用與 BigQuery DML 的寫入互通性，或啟用自動資料表管理功能 (儲存空間最佳化)。

在 Lakehouse 執行階段目錄中使用表格時，建議瞭解不同表格類型及其選擇加入功能。如要進一步瞭解如何使用 Apache Iceberg 資料表，請參閱 Apache Iceberg 資料表總覽。

事前準備

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

2. 啟用 BigLake API。

   啟用 API 時所需的角色

   如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

   啟用 API

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

必要的角色

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

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

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

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

設定注意事項

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

支援的 Iceberg 資料表

系統僅支援 Apache Iceberg V2 (正式發布版) 和 V3 (預先發布版) 資料表。不支援 Iceberg V1 資料表。如要升級現有的 V1 資料表，請參閱「將 Iceberg V1 資料表升級至 V2」。

憑證臨時配發規定

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

啟用 BigQuery DML

啟用 BigQuery 資料操縱語言 (DML) 陳述式後，即可在透過開放原始碼引擎建立的 Apache Iceberg 資料表上，使用 BigQuery 進行寫入作業。

支援的陳述式包括 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，為資料表中的快照設定到期時間。系統會從 metadata.json 檔案中移除過期的快照項目，然後實際刪除只屬於過期快照且不再由任何現有快照參照的資料和中繼資料檔案。

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

  • 限制：自動表格管理功能不會處理孤立檔案的移除作業。詳情請參閱「限制」一節。

• 合併 (壓縮)：合併作業負責維護資料形狀，方法是將小型檔案合併為大型檔案。在任何資料突變後，合併作業會在背景自動執行。如果檔案的平均未壓縮大小小於目標檔案大小 (256 MB) 的 50%，就會選取該檔案進行壓縮。每次合併作業都會產生新的表格快照。合併工作通常會讓步，並在任何正在執行的 DML 作業完成後重試。不過，為避免儲存空間最佳化作業無限期處於資源不足狀態，如果資料符合合併條件，系統會每 24 小時強制觸發一次合併工作。

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

  資料表管理作業的頻率與資料突變活動直接相關。頻繁的小型插入或更新作業會觸發更頻繁的背景工作。如果沒有寫入資料表，您可能會發現一段時間內沒有背景工作。反之，如果寫入量很高，INFORMATION_SCHEMA中可能會顯示更多工作活動。

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

從 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 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 寫入互通性和自動資料表管理) 的限制包括：

一般限制

• 只有使用 Apache Iceberg REST 目錄端點，在 Lakehouse 執行階段目錄中建立的 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)，則表格不支援受管理功能。
• 如果資料表含有自訂資料或中繼資料位置 (write.data.path 和 write.metadata.path)，則不支援代管功能。您必須使用預設的 Cloud Storage 值區位置，才能存放資料和中繼資料檔案。
• Lakehouse 執行階段目錄管理的 Apache Iceberg 資料表不支援 BigQuery 叢集。
• 如果在 BigQuery 中使用 NUMERIC 資料類型建立資料表，則來自 Spark 的任何結構定義更新都會失敗，因為 Spark 會將 NUMERIC 讀取為 NUMERIC(38,9)。如要解決這個問題，請在 BigQuery 中建立 NUMERIC 類型的資料表時，明確將精確度設為 NUMERIC(38,9)。
• 已知問題：BigQuery 不支援使用 DDL (ALTER TABLE ... DROP COLUMN) 刪除資料欄，然後立即重新新增同名資料欄。

時間旅行的限制

• 啟用表格管理功能後，history.expire.max-snapshot-age-ms 屬性的建議最大值為 7 天。
• BigQuery 專案層級或資料集層級的時空旅行設定不適用。只有 Iceberg 資料表屬性和預設值會生效。

資料表管理限制

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

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

  警告： 如果查詢執行時間超過 older_than 門檻 (預設為 3 天)，執行孤立檔案清理作業可能會從執行中的長期查詢中刪除檔案。請謹慎設定 older_than 參數。

• Coalesce 不支援 Z 排序和線性排序。如果資料表包含這些屬性，系統不保證在合併執行後會保留版面配置。如果資料表包含這些屬性，建議不要啟用資料表管理功能。

分區的限制

• 從開放原始碼引擎建立或註冊資料表時，受管理功能僅支援 DATE、TIMESTAMP 和 TIMESTAMPTZ 欄位類型的分割，並使用 hour、day、month 和 year 轉換 (DATE 欄位上的 hour 轉換除外)。
• 如果資料表含有 IDENTITY 轉換，就不支援受管理的功能。使用者必須明確指定轉換。
• 如果資料表使用相同的分區規格，系統就只支援對具備管理功能的資料表執行 CREATE OR REPLACE 指令。系統不支援下列取代作業：
  • 以分區資料表取代非分區資料表。
  • 以非分區資料表取代分區資料表。
  • 使用不同分區規格的資料表取代分區資料表。
• 系統不支援自訂分區欄位名稱。從開放原始碼引擎建立或註冊的資料表，必須遵循引擎的預設分區欄位命名慣例 (附加 _ 和轉換名稱，例如 _hour、_day、_month 或 _year)。舉例來說，如果使用 DAY 轉換的欄位名稱為 time_date，預期的分區欄位值為：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	系統會使用為 Lakehouse REST 目錄設定的預設 Cloud Storage bucket 路徑，寫入資料檔案。
write.metadata.path	table location + /metadata	系統會使用為 Lakehouse 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 天)	可設定為任何正整數，但啟用表格管理功能時，建議最多設定 7 天 (604800000 毫秒)。資料表管理工作會刪除存在時間超過指定時間長度的快照。
history.expire.min-snapshots-to-keep	1	可設為任何正整數。資料表管理工作至少會保留這個數量的快照。

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

後續步驟

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