Menggunakan vektor penghapusan biner dalam tabel Iceberg V3

Vektor penghapusan biner dalam tabel Apache Iceberg V3 memungkinkan Anda mencatat penghapusan tingkat baris dalam file .puffin tanpa menulis ulang seluruh file data. Alih-alih melakukan penggabungan waktu kueri yang mahal, mesin seperti BigQuery, Managed Service untuk Apache Spark, Apache Flink, dan Trino menggunakan vektor ini untuk mengidentifikasi dan melewati baris yang dihapus selama pembacaan.

Didukung dalam katalog runtime Lakehouse, pengoptimalan ini dapat meningkatkan performa tulis dan baca untuk pipeline Change Data Capture (CDC) bervolume tinggi. Hal ini juga membantu Anda memenuhi persyaratan peraturan seperti GDPR (Hak untuk Dilupakan) dengan menghapus data individual tanpa overhead penulisan ulang file data.

Sebelum memulai

  1. Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

  2. Aktifkan BigLake API, jika belum diaktifkan.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Mengaktifkan API

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk membuat dan mengelola tabel Iceberg V3, minta administrator untuk memberi Anda peran IAM berikut pada project dan bucket penyimpanan Anda:

  • Membuat dan mengelola tabel Iceberg V3:
    • BigLake Admin (roles/biglake.admin) - project Anda
    • Storage Admin (roles/storage.admin) - bucket Cloud Storage target

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Menyiapkan katalog REST Iceberg

Sebelum membuat tabel Iceberg V3, Anda harus menyiapkan katalog REST Iceberg, yang mencakup pembuatan namespace dan katalog.

Penyiapan katalog REST Iceberg mungkin memerlukan waktu beberapa saat untuk diselesaikan. Pastikan Anda berhasil membuat namespace dan katalog sebelum melanjutkan.

Batasan

Tabel Iceberg V3 di katalog runtime Lakehouse memiliki batasan berikut:

  • Jenis data V3 baru: Jenis data Iceberg V3 baru (seperti Variant, Geography, stempel waktu Nanodetik, nilai default, dan jenis data yang tidak diketahui) tidak didukung.
  • Pelacakan silsilah baris: Pelacakan silsilah baris tidak didukung.
  • Penulisan BigQuery: Penulisan BigQuery tidak didukung dengan tabel V3. Anda hanya dapat membaca tabel V3 dari BigQuery. Untuk membuat dan menulis ke tabel V3, Anda harus menggunakan mesin open source (seperti Apache Spark, Apache Flink, atau Trino).

Persyaratan mesin

Pastikan Anda menggunakan versi mesin yang mendukung Iceberg V3 dan vektor penghapusan biner. Sebaiknya gunakan Apache Spark 3.5 atau yang lebih tinggi. Contoh dalam panduan ini menggunakan iceberg-spark-runtime-3.5_2.12:1.10.1.

Saat mengonfigurasi sesi tabel dan mesin, pastikan hal berikut:

  • Versi format tabel: Harus ditetapkan ke format-version='3'.
  • Delete mode: Harus ditetapkan ke merge-on-read. Mode ini memastikan bahwa penghapusan ditulis ke file terpisah (vektor penghapusan), bukan menulis ulang file data asli (copy-on-write).

Contoh konfigurasi sesi Spark

Konfigurasi berikut mengaktifkan ekstensi Iceberg yang diperlukan dan menyiapkan koneksi katalog 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

Ganti kode berikut:

  • CATALOG_NAME: nama endpoint katalog REST Apache Iceberg Anda.
  • WAREHOUSE_PATH: URI folder Cloud Storage tempat data warehouse Anda disimpan, dimulai dengan gs://.
  • PROJECT_ID: Project ID Google Cloud Anda.

Menggunakan vektor penghapusan biner

Untuk menggunakan vektor penghapusan biner di tabel Apache Iceberg V3, Anda harus membuat tabel dengan versi pemformatan 3, mengisi tabel dengan data, melakukan modifikasi database standar, dan membuat kueri tabel. Anda dapat menjalankan semua pernyataan create, insert, delete, dan update menggunakan Spark SQL.

Membuat tabel Iceberg dengan vektor penghapusan biner

Buat tabel yang menentukan format-version='3' dan mode penghapusan, pembaruan, dan penggabungan merge-on-read di properti tabel. Jalankan pernyataan berikut di 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'
);

Mengupgrade tabel Iceberg V2 ke V3

Anda dapat mengupgrade tabel Iceberg V2 yang ada ke V3 menggunakan pernyataan ALTER TABLE. Menurunkan versi tabel dari V3 ke V2 tidak didukung. Jalankan pernyataan berikut di Spark SQL:

Spark 

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

Menyisipkan data ke dalam tabel

Untuk memastikan file vektor penghapusan biner dibuat untuk penghapusan, mesin tidak boleh kembali ke copy-on-write. Hal ini biasanya memerlukan sejumlah besar data yang ada dalam tabel sebelum operasi penghapusan. Misalnya, Apache Spark mungkin mengoptimalkan penghapusan kecil dengan beralih ke copy-on-write. Isi tabel dengan menjalankan pernyataan berikut di 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;

Menghapus data

Menjalankan pernyataan DELETE di Spark SQL. Karena tabel dikonfigurasi untuk merge-on-read dan memiliki data yang memadai, Spark akan membuat file penghapusan menggunakan vektor penghapusan biner.

Spark 

DELETE FROM my_namespace.mytable_v3 WHERE id = 5000;

Memperbarui data

Menjalankan pernyataan UPDATE di Spark SQL. Karena tabel dikonfigurasi untuk merge-on-read dan memiliki data yang memadai, Spark menghasilkan file penghapusan menggunakan vektor penghapusan biner.

Spark 

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

Membuat kueri tabel

Kueri pada tabel secara otomatis menggunakan file vektor penghapusan biner untuk mengecualikan baris yang dihapus. Anda dapat membuat kueri tabel menggunakan Apache Spark atau 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

Saat membuat kueri dari BigQuery, gunakan ID tabel yang sepenuhnya memenuhi syarat, 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'

Memverifikasi pembuatan vektor penghapusan biner

Anda dapat memverifikasi bahwa vektor penghapusan biner berhasil dibuat dengan memeriksa direktori penyimpanan dan metadata snapshot.

Memeriksa file .puffin

Buka direktori data tabel di warehouse Cloud Storage Anda (misalnya, gs://WAREHOUSE_BUCKET/my_namespace/mytable_v3/data). Anda akan menemukan file .puffin, yang menyimpan vektor penghapusan biner.

Memeriksa metadata snapshot

Metadata snapshot dalam file JSON tabel Iceberg berisi informasi tentang operasi penghapusan. Cari properti seperti added-delete-files, added-dvs, dan operation dalam ringkasan snapshot. Hal ini mengonfirmasi bahwa file penghapusan telah ditambahkan.

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

Langkah berikutnya