在 Iceberg V3 資料表中使用二進位刪除向量

Apache Iceberg V3 資料表中的二進位刪除向量，可讓您在 .puffin 檔案中記錄資料列層級的刪除作業，而不必重寫整個資料檔案。BigQuery、Managed Service for Apache Spark、Apache Flink 和 Trino 等引擎會使用這些向量，在讀取期間識別並略過已刪除的資料列，而非執行昂貴的查詢時間 join。

這項最佳化功能支援 Lakehouse 執行階段目錄，可提升大量變更資料擷取 (CDC) 管道的寫入和讀取效能。此外，這項功能還能清除個別記錄，不必重新編寫資料檔案，有助於滿足 GDPR (被遺忘權) 等法規要求。

事前準備

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

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

   啟用 API 所需的角色

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

   啟用 API

必要的角色

如要取得建立及管理 Iceberg V3 資料表所需的權限，請要求管理員授予您專案和 Storage bucket 的下列 IAM 角色：

• 建立及管理 Iceberg V3 資料表：
  • BigLake 管理員 (roles/biglake.admin) - 您的專案
  • 儲存空間管理員 (roles/storage.admin) - 目標 Cloud Storage bucket

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

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

設定 Iceberg REST 目錄

建立 Iceberg V3 資料表前，您必須先設定 Iceberg REST 目錄，包括建立命名空間和目錄。

設定 Iceberg REST 目錄可能需要一些時間才能完成。請務必先成功建立命名空間和目錄，再繼續操作。

限制

Lakehouse 執行階段目錄中的 Iceberg V3 資料表有下列限制：

• 新的 V3 資料類型：不支援新的 Iceberg V3 資料類型 (例如 Variant、Geography、奈秒時間戳記、預設值和不明資料類型)。
• 資料列歷程追蹤：不支援資料列歷程追蹤。
• BigQuery 寫入：V3 資料表不支援 BigQuery 寫入。您只能從 BigQuery 讀取 V3 資料表。如要建立 V3 資料表並寫入資料，必須使用開放原始碼引擎 (例如 Apache Spark、Apache Flink 或 Trino)。

引擎需求

請務必使用支援 Iceberg V3 和二進位刪除向量的引擎版本。建議使用 Apache Spark 3.5 以上版本。本指南中的範例使用 iceberg-spark-runtime-3.5_2.12:1.10.1。

設定資料表和引擎工作階段時，請注意下列事項：

• 資料表格式版本：必須設為 format-version='3'。
• 刪除模式：必須設為 merge-on-read。這個模式可確保刪除作業會寫入個別檔案 (刪除向量)，而不是重寫原始資料檔案 (寫入時複製)。

Spark 工作階段設定範例

下列設定會啟用必要的 Iceberg 擴充功能，並設定 REST 目錄連線：

spark-sql \
    --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.10.1,org.apache.iceberg:iceberg-gcp:1.10.1 \
    --jars https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-gcp-bundle/1.10.1/iceberg-gcp-bundle-1.10.1.jar \
    --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
    --conf spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog \
    --conf spark.sql.catalog.CATALOG_NAME.type=rest \
    --conf spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog \
    --conf spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH \
    --conf spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID \
    --conf spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager \
    --conf spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO \
    --conf spark.sql.defaultCatalog=CATALOG_NAME

更改下列內容：

• CATALOG_NAME：Apache Iceberg REST 目錄端點的名稱。
• WAREHOUSE_PATH：儲存資料倉儲的 Cloud Storage 資料夾 URI，開頭為 gs://。
• PROJECT_ID：您的 Google Cloud 專案 ID。

使用二進位刪除向量

如要在 Apache Iceberg V3 資料表中使用二進位刪除向量，您必須建立格式版本為 3 的資料表、在資料表中填入資料、執行標準資料庫修改作業，以及查詢資料表。您可以使用 Spark SQL 執行所有建立、插入、刪除和更新陳述式。

建立含有二進位刪除向量的 Iceberg 資料表

建立資料表，並在資料表屬性中指定 format-version='3' 和 merge-on-read 刪除、更新和合併模式。在 Spark SQL 中執行下列陳述式：

CREATE NAMESPACE IF NOT EXISTS my_namespace;
USE my_namespace;

CREATE TABLE my_namespace.mytable_v3 (
   id BIGINT,
   city STRING,
   state STRING
) TBLPROPERTIES (
   'format-version'='3',
   'write.delete.mode'='merge-on-read',
   'write.update.mode'='merge-on-read',
   'write.merge.mode'='merge-on-read'
);

將 Iceberg V2 資料表升級至 V3

您可以使用 ALTER TABLE 陳述式，將現有的 Iceberg V2 資料表升級至 V3。不支援將資料表從 V3 降級至 V2。在 Spark SQL 中執行下列陳述式：

ALTER TABLE my_namespace.mytable_v2 SET TBLPROPERTIES ('format-version' = '3');

將資料插入資料表

為確保系統會為刪除作業產生二進位刪除向量檔案，引擎不得改用寫入時複製。這通常需要資料表在刪除作業前，含有大量資料。舉例來說，Apache Spark 可能會改用寫入時複製，最佳化小型刪除作業。在 Spark SQL 中執行下列陳述式，填入資料表：

-- Create a temporary view with a large number of rows (100,000 rows)
CREATE OR REPLACE TEMPORARY VIEW large_source AS
SELECT
  id,
  CAST(id AS STRING) as city,
  'WA' as state
FROM (
  SELECT row_number() OVER (ORDER BY (SELECT NULL)) as id
  FROM (SELECT 0 FROM range(1000)) a
  CROSS JOIN (SELECT 0 FROM range(100)) b
);

-- Overwrite the existing table with the generated data
INSERT OVERWRITE my_namespace.mytable_v3 SELECT * FROM large_source;

刪除資料

在 Spark SQL 中執行 DELETE 陳述式。由於資料表已設定為 merge-on-read，且有足夠的資料，Spark 會使用二進位刪除向量產生刪除檔案。

DELETE FROM my_namespace.mytable_v3 WHERE id = 5000;

更新資料

在 Spark SQL 中執行 UPDATE 陳述式。由於資料表已設定為 merge-on-read，且有足夠的資料，Spark 會使用二進位刪除向量產生刪除檔案。

UPDATE my_namespace.mytable_v3 SET state = 'NY' WHERE id = 1;

查詢資料表

資料表查詢會自動使用二進位刪除向量檔案，排除已刪除的資料列。您可以使用 Apache Spark 或 BigQuery 查詢資料表。

-- Should be less than the initial 100,000 rows
SELECT count(*) FROM my_namespace.mytable_v3;

-- Should return no results
SELECT * FROM my_namespace.mytable_v3 WHERE id = 5000;

-- Should return 'NY'
SELECT * FROM my_namespace.mytable_v3 WHERE id = 1;

bq query --nouse_legacy_sql \
    'SELECT * FROM `PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3` LIMIT 10'

確認二進位刪除向量建立作業

您可以檢查儲存空間目錄和快照中繼資料，確認二進位刪除向量是否已成功建立。

檢查 .puffin 檔案

在 Cloud Storage 倉儲中，前往資料表的資料目錄 (例如 gs://WAREHOUSE_BUCKET/my_namespace/mytable_v3/data)。您應該會看到 .puffin 檔案，其中儲存了二進位刪除向量。

檢查快照中繼資料

Iceberg 資料表 JSON 檔案中的快照中繼資料，包含刪除作業的相關資訊。在快照摘要中尋找 added-delete-files、added-dvs 和 operation 等屬性。這表示刪除檔案已新增。

"summary": {
  "operation": "delete",
  "added-delete-files": "1",
  "added-dvs": "1",
  "added-files-size": "42",
  "added-position-deletes": "1",
  ...
}

後續步驟

• 瞭解如何在 Lakehouse 執行階段目錄中管理 Apache Iceberg 資料表。