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

Lakehouse 執行階段目錄支援 Apache Iceberg V3 資料表。Apache Iceberg V3 規格的核心功能是二進位刪除向量。這項最佳化功能會將資料列層級的刪除作業儲存在 .puffin 檔案中。BigQuery 和開放原始碼引擎 (例如 Apache Spark、Apache Flink 和 Trino) 會使用這些向量快速識別並略過已刪除的資料列，不必在查詢時執行耗費資源的聯結作業。

使用二進位刪除向量可透過下列方式提升效能：

  • 大量寫入：改善大量寫入資料表的寫入效能。
  • 提升讀取效率：讓 BigQuery 和開放原始碼引擎識別並略過已刪除的資料列，進而提升查詢速度。

這項功能特別適合在異動資料擷取 (CDC) 管道中處理大量更新和刪除作業，或為了符合 GDPR (被遺忘權) 等法規要求，刪除特定資料列，而不必重寫整個資料檔案，進而節省資源。

事前準備

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

  2. 啟用 BigLake API。

    啟用 API 時所需的角色

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

    啟用 API

必要的角色

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

  • 全部：
    • BigLake 管理員 (roles/biglake.admin) - 您的專案
    • Storage 管理員 (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 中執行下列陳述式：

Spark 

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 中執行下列陳述式：

Spark 

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

將資料插入資料表

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

Spark 

-- 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 會使用二進位刪除向量產生刪除檔案。

Spark 

DELETE FROM my_namespace.mytable_v3 WHERE id = 5000;

更新資料

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

Spark 

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

查詢資料表

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

Spark 

-- 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;

BigQuery

從 BigQuery 查詢時，請使用完整格式的資料表 ID PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3。

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",
  ...
}

後續步驟