Iceberg V3 テーブルでバイナリ削除ベクトルを使用する

プレビュー

この機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

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 を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

   API の有効化

必要なロール

Iceberg V3 テーブルの作成と管理に必要な権限を取得するには、プロジェクトとストレージ バケットに対する次の IAM ロールを付与するよう管理者に依頼してください。

• すべて:
  • BigLake 管理者（roles/biglake.admin）- プロジェクト
  • ストレージ管理者（roles/storage.admin） - ターゲット Cloud Storage バケット

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Iceberg REST カタログを設定する

Iceberg V3 テーブルを作成する前に、名前空間とカタログの作成を含む Iceberg REST カタログを設定する必要があります。

Iceberg REST カタログの設定には時間がかかることがあります。続行する前に、名前空間とカタログの両方が正常に作成されていることを確認してください。

制限事項

Lakehouse ランタイム カタログの Iceberg V3 テーブルには次の制限があります。

• 新しい V3 データ型: 新しい Iceberg V3 データ型（Variant、Geography、ナノ秒タイムスタンプ、デフォルト値、不明なデータ型など）は対象外です。
• 行リネージのトラッキング: 行リネージのトラッキングは対象外です。
• BigQuery 書き込み: BigQuery 書き込みは V3 テーブルではサポートされていません。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 からクエリを実行する場合は、完全修飾されたテーブル識別子 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",
  ...
}

次のステップ

• BigQuery でテーブルをクエリし、カタログ連携を使用する方法を学習する。
• Apache Iceberg 用 Lakehouse for Apache Iceberg REST カタログ テーブルについて学習する。