Menggunakan vektor penghapusan biner dalam tabel Iceberg V3

Katalog runtime Lakehouse mendukung tabel Apache Iceberg V3. Fitur inti dari spesifikasi Apache Iceberg V3 adalah vektor penghapusan biner. Pengoptimalan ini menyimpan penghapusan tingkat baris dalam file .puffin. Daripada melakukan gabungan yang mahal pada waktu kueri, BigQuery dan mesin open source (seperti Apache Spark, Apache Flink, dan Trino) menggunakan vektor ini untuk mengidentifikasi dan melewati baris yang dihapus dengan cepat.

Penggunaan vektor penghapusan biner dapat meningkatkan performa dengan cara berikut:

  • Penulisan volume tinggi: Meningkatkan performa penulisan untuk tabel dengan penulisan volume tinggi.
  • Pembacaan yang efisien: Meningkatkan kecepatan kueri dengan memungkinkan BigQuery dan mesin open source mengidentifikasi dan melewati baris yang dihapus.

Hal ini sangat berguna untuk menangani update dan penghapusan volume tinggi dalam pipeline Change Data Capture (CDC), atau untuk memenuhi persyaratan peraturan seperti GDPR (hak untuk dilupakan) dengan menghapus baris tertentu tanpa overhead penulisan ulang seluruh file data.

Sebelum memulai

  1. Pastikan penagihan diaktifkan untuk Google Cloud project Anda.

  2. Aktifkan BigLake API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. 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 di project dan bucket penyimpanan:

  • Semua:
    • Admin BigLake (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 dalam katalog runtime Lakehouse memiliki batasan berikut:

  • Jenis data V3 baru: Jenis data Iceberg V3 baru (seperti Variant, Geography, stempel waktu Nanosecond, nilai default, dan jenis data tidak dikenal) tidak didukung.
  • Pelacakan asal-usul baris: Pelacakan asal-usul 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. Apache Spark 3.5 atau yang lebih tinggi direkomendasikan. 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'.
  • Mode penghapusan: 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 Anda Google Cloud .

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 pembuatan, penyisipan, penghapusan, dan pembaruan menggunakan Spark SQL.

Membuat tabel Iceberg dengan vektor penghapusan biner

Buat tabel yang menentukan format-version='3' dan mode penghapusan merge-on-read, pembaruan, dan penggabungan 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. Tabel yang di-downgrade 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. Biasanya, hal ini memerlukan sejumlah besar data yang ada dalam tabel sebelum operasi penghapusan. Misalnya, Apache Spark dapat mengoptimalkan penghapusan kecil dengan kembali 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

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

Spark 

DELETE FROM my_namespace.mytable_v3 WHERE id = 5000;

Memperbarui data

Jalankan pernyataan UPDATE di Spark SQL. Karena tabel dikonfigurasi untuk merge-on-read dan memiliki data yang cukup, Spark akan membuat 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 data 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 di 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