Mengonfigurasi opsi tabel

Anda dapat menggunakan opsi tabel di katalog runtime Lakehouse untuk mengaktifkan interoperabilitas penulisan DML BigQuery dan pengelolaan tabel (pengoptimalan penyimpanan otomatis) untuk tabel Apache Iceberg Anda.

Untuk mempelajari lebih lanjut format tabel yang didukung dan kemampuan keikutsertaan dalam katalog runtime Lakehouse, lihat Membandingkan jenis tabel dan Ringkasan tabel Apache Iceberg.

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

  3. Siapkan katalog runtime Lakehouse dengan endpoint katalog REST Apache Iceberg.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mengonfigurasi opsi tabel, minta administrator untuk memberi Anda peran IAM berikut pada project dan bucket penyimpanan Anda:

  • Konfigurasikan properti tabel dalam mode penyediaan kredensial: BigLake Editor (roles/biglake.editor) - project
  • Konfigurasikan properti tabel dalam mode non-credential vending:
    • BigLake Editor (roles/biglake.editor) - project
    • Storage Object User (roles/storage.objectUser) - bucket Cloud Storage

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.

Pertimbangan konfigurasi

Pertimbangkan persyaratan dan perilaku default berikut saat mengonfigurasi opsi tabel:

Tabel Iceberg yang didukung

Meskipun katalog runtime Lakehouse mendukung tabel Apache Iceberg V2 (GA) dan V3 (Pratinjau), kemampuan terkelola (DML BigQuery dan pengelolaan tabel) hanya didukung untuk tabel Iceberg V2. Tabel Iceberg V1 tidak didukung. Untuk mengupgrade tabel V1 yang ada, lihat Mengupgrade tabel Iceberg V1 ke V2.

Persyaratan penyediaan kredensial

Untuk mengaktifkan pengelolaan tabel, katalog runtime Lakehouse Anda harus mengaktifkan penjualan kredensial di tingkat katalog. Tugas latar belakang pengelolaan tabel menggunakan akun layanan penyedia kredensial untuk mengautentikasi dan memperbarui file data penyimpanan yang mendasarinya.

Mengaktifkan DML BigQuery

Mengaktifkan pernyataan bahasa pengolahan data (DML) BigQuery akan membuka interoperabilitas tulis dari BigQuery pada tabel Apache Iceberg yang dibuat menggunakan mesin open source.

Pernyataan yang didukung mencakup INSERT, UPDATE, DELETE, dan MERGE, serta pernyataan DDL standar seperti CREATE TABLE, ALTER TABLE, dan DROP TABLE, kecuali yang tidak didukung dalam tabel Apache Iceberg di BigQuery.

Mengaktifkan DML BigQuery untuk tabel baru

Saat Anda membuat tabel dari BigQuery, DML BigQuery dan pengelolaan tabel diaktifkan secara default. Saat Anda membuat tabel dari mesin open source, konfigurasikan properti tabel gcp.biglake.bigquery-dml.enabled = true menggunakan sintaksis DDL mesin Anda.

Misalnya, di Spark SQL:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Mengaktifkan DML BigQuery untuk tabel yang ada

Untuk mengaktifkan DML BigQuery pada tabel yang ada, perbarui properti tabel.

Misalnya, di Spark SQL:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Menonaktifkan DML BigQuery

Menonaktifkan DML BigQuery akan membuat tabel menjadi hanya baca untuk BigQuery dan menghentikan pengelolaan tabel.

Misalnya, di Spark SQL:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

Mengaktifkan pengelolaan tabel

Pengelolaan tabel mengotomatiskan proses latar belakang untuk mengoptimalkan penyimpanan serta mengelola siklus proses data dan metadata, seperti pemadatan dan pembersihan sampah memori.

Pengelolaan tabel memungkinkan Anda melakukan operasi berikut:

  • Masa berlaku snapshot dan pembersihan sampah memori: Masa berlaku snapshot mengelola retensi dan penghapusan file data dan metadata dari snapshot tabel. Proses ini berjalan otomatis di latar belakang setelah mutasi data. Snapshot akan berakhir masa berlakunya berdasarkan properti tabel Iceberg yang dikonfigurasi pengguna, history.expire.max-snapshot-age-ms dan history.expire.min-snapshots-to-keep pada tabel. Tindakan ini akan menghapus entri snapshot yang sudah tidak berlaku dengan membuat definisi snapshot tambahan dalam file metadata baru yang menghilangkan referensi ke snapshot yang dihapus.

    • Batasan: Masa berlaku snapshot dan pembersihan sampah memori terkait akan dilewati jika tabel menggunakan tag atau cabang. Untuk mengetahui informasi selengkapnya, lihat Batasan.

    • Batasan: Penghapusan file tanpa induk tidak ditangani oleh pengelolaan tabel. Untuk mengetahui informasi selengkapnya, lihat Batasan.

  • Coalesce (pemadatan): Coalesce mempertahankan bentuk data dan performa kueri dengan menggabungkan file kecil yang terfragmentasi menjadi file yang lebih besar. Coalesce dievaluasi di latar belakang setelah mutasi data. File memenuhi syarat untuk pemadatan jika ukuran rata-rata yang tidak dikompresi kurang dari 50% dari ukuran file target sebesar 256 MB. Setiap operasi penggabungan menghasilkan snapshot tabel baru. Tugas penggabungan biasanya mengalah dan mencoba lagi setelah operasi DML yang sedang berjalan. Namun, untuk mencegah penghentian pengoptimalan penyimpanan tanpa batas, tugas penggabungan akan dipicu secara paksa setiap 24 jam jika data memenuhi syarat untuk pemadatan.

    Tidak setiap mutasi data, penyisipan, atau pernyataan DML memicu tugas pengoptimalan penyimpanan. Tugas pengoptimalan penyimpanan berjalan di project Anda dan menggunakan resource komputasi. Untuk mencegah biaya komputasi yang tidak perlu, BigQuery mengevaluasi bentuk tabel untuk menentukan apakah pengoptimalan diperlukan, dan melewati pengoptimalan dalam kondisi berikut:

    • File data sudah dalam bentuk yang optimal: Jika file sudah berukuran baik (ukuran rata-rata yang tidak dikompresi setidaknya 50% dari target ukuran file 256 MB), pemadatan tidak diperlukan.
    • Nilai minimum tidak terpenuhi: Pengoptimalan akan dilewati jika tabel belum mengumpulkan cukup file kecil atau tidak melebihi nilai minimum ukuran tabel minimum (misalnya, tabel di bawah 1 GB).

    Jika pengoptimalan penyimpanan dilewati karena data sudah dalam status optimal, tidak ada tugas latar belakang yang dijalankan.

  • Memantau tugas pengelolaan tabel: Semua tugas pengelolaan tabel latar belakang dicatat dalam tampilan INFORMATION_SCHEMA.JOBS di BigQuery. Anda dapat membuat kueri tabel virtual ini untuk melacak operasi ini, mirip dengan cara Anda memantau tugas BigQuery lainnya. Untuk mengetahui informasi selengkapnya tentang cara mengkueri informasi tugas, lihat Mendapatkan tugas pengoptimalan penyimpanan Iceberg.

    Frekuensi tugas pengelolaan tabel berkorelasi dengan aktivitas mutasi data dan fragmentasi file. Penyisipan atau pembaruan kecil yang sering memicu tugas latar belakang yang lebih sering. Anda mungkin mengamati periode tanpa tugas latar belakang jika tidak ada penulisan ke tabel. Jika pengoptimalan penyimpanan dilewati (misalnya, karena data dimuat dalam batch besar dan file sudah optimal), tidak ada tugas yang muncul di INFORMATION_SCHEMA.JOBS untuk operasi tersebut, yang merupakan perilaku yang diharapkan.

    Untuk mengamati tugas pengelolaan tabel di lingkungan pengujian atau pengembangan, masukkan beberapa batch kecil data dari waktu ke waktu ke dalam tabel dengan ukuran total lebih dari 1 GB. Hal ini akan membuat file kecil yang terfragmentasi yang berada di bawah nilai minimum ukuran target 50% dan memicu pemadatan.

Memilih apakah akan mengaktifkan pengelolaan tabel

Untuk tabel Apache Iceberg yang dikelola oleh katalog runtime Lakehouse dan disajikan melalui endpoint katalog REST Apache Iceberg, Anda dapat mengaktifkan pengelolaan tabel atau mengelola pemeliharaan tabel (seperti pemadatan dan masa berlaku snapshot) sendiri menggunakan mesin open source atau pihak ketiga.

Aktifkan pengelolaan tabel (gcp.biglake.table-management.enabled = true) jika semua kondisi berikut terpenuhi:

  • Anda menginginkan pemadatan file latar belakang otomatis (coalesce) serta masa berlaku snapshot dan pembersihan sampah memori otomatis setelah penulisan streaming open source atau DML.

  • Katalog Anda menggunakan mode penjualan kredensial.

  • Periode retensi snapshot dan perjalanan waktu hingga 7 hari (default 5 hari) memenuhi persyaratan Anda.

  • Tabel Anda memenuhi persyaratan untuk kemampuan terkelola (lihat Batasan).

Tetap nonaktifkan pengelolaan tabel (default untuk tabel yang dibuat dari mesin open source, atau tetapkan gcp.biglake.table-management.enabled = false) dan kelola pemeliharaan tabel sendiri jika salah satu kondisi berikut terpenuhi:

  • Anda menjalankan prosedur pemadatan atau pemeliharaan kustom di mesin open source seperti Apache Spark, Apache Flink, atau Trino, terutama jika tabel Anda mengandalkan tata letak pengurutan linear atau z-order yang tidak dipertahankan oleh penggabungan.

  • Tabel Anda menggunakan tag atau cabang snapshot Apache Iceberg (yang menyebabkan pengelolaan tabel melewati masa berlaku snapshot), atau memerlukan retensi snapshot dan perjalanan waktu lebih dari 7 hari.

  • Katalog Anda menggunakan kredensial pengguna akhir (izin Identity and Access Management (IAM) Cloud Storage langsung), bukan mode penjualan kredensial.

  • Tabel Anda menggunakan fitur yang tidak didukung oleh kemampuan terkelola (dalam hal ini, pengelolaan tabel dan DML BigQuery harus tetap dinonaktifkan), seperti Apache Iceberg format-version 3, mode merge-on-read, partisi multi-kolom atau IDENTITY, atau jalur penyimpanan data dan metadata kustom. Untuk mengetahui daftar lengkap fitur yang tidak didukung, lihat Batasan.

Mengaktifkan pengelolaan tabel untuk tabel baru

Saat Anda membuat tabel dari BigQuery, DML dan pengelolaan tabel diaktifkan secara default. Saat Anda membuat tabel dari mesin open source, konfigurasikan properti gcp.biglake.table-management.enabled. Mengaktifkan pengelolaan tabel akan otomatis mengaktifkan DML BigQuery jika belum diaktifkan.

Misalnya, di Spark SQL:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

Mengaktifkan pengelolaan tabel untuk tabel yang ada

Untuk mengaktifkan pengelolaan tabel pada tabel yang ada, perbarui properti tabel.

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

BigQuery 

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "enabled");

Menonaktifkan pengelolaan tabel

Menonaktifkan pengelolaan tabel akan mencegah tugas pengoptimalan latar belakang mendatang dimasukkan ke dalam antrean, meskipun tugas yang sedang berlangsung dan aktif akan diselesaikan. Menonaktifkan pengelolaan tabel tidak akan menonaktifkan DML BigQuery.

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);

BigQuery 

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");

Batasan

Batasan untuk kemampuan terkelola (seperti interoperabilitas penulisan BigQuery dan pengelolaan tabel) mencakup:

Batasan umum

  • Kemampuan terkelola hanya didukung dengan tabel Apache Iceberg yang dibuat di katalog runtime Lakehouse menggunakan endpoint katalog REST Apache Iceberg.
  • Semua batasan yang ada untuk tabel Apache Iceberg yang dikelola oleh BigQuery berlaku untuk operasi dengan kemampuan terkelola yang diaktifkan.
  • Kemampuan terkelola tidak didukung untuk tabel dengan Apache Iceberg format-version 3. Hanya tabel format-version 2 (Iceberg v2 spec) yang dapat diikutsertakan dalam kemampuan terkelola.
  • Kemampuan terkelola tidak didukung untuk tabel yang memiliki partisi lanjutan, seperti partisi berdasarkan STRING, partisi multi-kolom, atau evolusi partisi.
  • Kemampuan terkelola tidak didukung untuk tabel yang dikonfigurasi dengan tata urutan (misalnya, menggunakan prosedur WRITE ORDER BY atau menetapkan write.distribution.mode = range).
  • Kemampuan terkelola tidak didukung untuk tabel Iceberg v2 yang menggunakan mode merge-on-read. Hanya tabel yang menggunakan mode update, penghapusan, dan penggabungan copy-on-write yang dapat diikutsertakan untuk kemampuan terkelola.
  • Kemampuan terkelola tidak mendukung file data yang dikompresi menggunakan codec gzip, lz4, atau brotli (write.parquet.compression-codec). Hanya jenis kompresi zstd dan snappy yang didukung untuk file data.
  • Kemampuan terkelola tidak didukung untuk tabel jika skema berisi ID kunci utama bertingkat (identifier-field-ids) yang merujuk ke jalur atau kolom bertingkat dalam struktur.
  • Kemampuan terkelola tidak didukung untuk tabel dengan lokasi data atau metadata kustom (write.data.path dan write.metadata.path). Lokasi bucket Cloud Storage default diperlukan untuk menyimpan file data dan metadata.
  • Pengelompokan BigQuery tidak didukung untuk tabel Apache Iceberg yang dikelola oleh katalog runtime Lakehouse.
  • Jika tabel dibuat dengan jenis data NUMERIC di BigQuery, setiap update skema dari Spark akan gagal karena Spark membaca NUMERIC sebagai NUMERIC(38,9). Sebagai solusinya, saat membuat tabel dengan jenis NUMERIC di BigQuery, tetapkan presisi secara eksplisit ke NUMERIC(38,9).
  • Masalah umum: Menghapus kolom di BigQuery menggunakan DDL (ALTER TABLE ... DROP COLUMN) yang langsung diikuti dengan menambahkan kembali kolom dengan nama yang sama tidak didukung.

Batasan dengan perjalanan waktu

  • Jika pengelolaan tabel diaktifkan, nilai maksimum yang diizinkan untuk properti history.expire.max-snapshot-age-ms adalah 30 hari (2592000000 md), dan nilai maksimum yang direkomendasikan adalah 7 hari (604800000 md). Nilai maksimum yang diizinkan untuk properti history.expire.min-snapshots-to-keep adalah 100.
  • Konfigurasi level project atau level set data BigQuery untuk perjalanan waktu tidak berlaku. Hanya properti dan default tabel Iceberg yang aktif.

Batasan terkait pengelolaan tabel

  • Masa berlaku snapshot dilewati untuk seluruh tabel jika tabel berisi snapshot dengan tag atau cabang. Retensi kustom yang ditetapkan menggunakan ALTER... RETAIN x DAYS akan diabaikan, dan nilai apa pun yang ditetapkan untuk properti history.expire.max-ref-age-ms akan diabaikan. Mesin open source masih dapat melakukan masa berlaku snapshot.
  • Pengelolaan tabel tidak mengakhiri masa berlaku skema atau spesifikasi partisi. File metadata.json menyimpan histori lengkap skema dan spesifikasi partisi, meskipun tidak ada snapshot yang merujuk ke ID skema tersebut.

  • File tanpa induk yang dibuat oleh BigQuery atau mesin open source tidak akan dihapus oleh pengelolaan tabel. Mesin open source dapat melakukan pembersihan file tanpa induk (misalnya, menggunakan prosedur remove_orphan_files Spark dengan opsi prefix_listing ditetapkan ke true).

  • Coalesce tidak mendukung pengurutan z dan pengurutan linear. Jika tabel Anda berisi properti ini, tidak ada jaminan bahwa tata letak akan dipertahankan setelah coalesce dijalankan. Jika tabel Anda berisi properti ini, jangan aktifkan pengelolaan tabel.

Batasan dengan partisi

  • Saat membuat atau mendaftarkan tabel dari mesin open source, kemampuan terkelola hanya mendukung partisi pada jenis kolom DATE, DATETIME, dan TIMESTAMP dengan transformasi hour, day, month, dan year (kecuali untuk transformasi hour pada kolom DATE), dan jenis kolom INTEGER.
  • Kemampuan terkelola tidak didukung pada tabel dengan transformasi IDENTITY. Anda harus menentukan transformasi secara eksplisit.
  • Perintah CREATE OR REPLACE pada tabel dengan kemampuan terkelola hanya didukung jika menggunakan spesifikasi partisi yang sama. Penggantian berikut tidak didukung:
    • Mengganti tabel yang tidak berpartisi dengan tabel berpartisi.
    • Mengganti tabel berpartisi dengan tabel yang tidak dipartisi.
    • Mengganti tabel berpartisi dengan tabel yang menggunakan spesifikasi partisi yang berbeda.
  • Penamaan kolom partisi kustom tidak didukung. Tabel yang dibuat atau didaftarkan dari mesin open source harus mengikuti konvensi penamaan kolom partisi default mesin (menambahkan _ dan nama transformasi, seperti _hour, _day, _month, atau _year). Misalnya, untuk kolom bernama time_date yang menggunakan transformasi DAY, nilai kolom partisi yang diharapkan adalah: json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

Batasan terkait properti tabel Iceberg kustom

Properti perilaku tabel berikut tidak dapat dikonfigurasi ke nilai non-default saat kemampuan terkelola diaktifkan. Nilai default di-hardcode saat kemampuan terkelola diaktifkan:

Properti Nilai default Detail
format-version 2 Kemampuan terkelola hanya mendukung tabel Iceberg v2.
write.format.default parquet Tabel hanya mendukung file data dalam format Parquet.
write.data.path table location + /data Jalur bucket Cloud Storage default yang dikonfigurasi untuk endpoint katalog REST Apache Iceberg digunakan untuk menulis file data.
write.metadata.path table location + /metadata Jalur bucket Cloud Storage default yang dikonfigurasi untuk endpoint katalog REST Apache Iceberg digunakan untuk menulis file metadata.
write.delete.mode copy-on-write Tugas penulisan dan pengelolaan tabel BigQuery hanya mendukung copy-on-write.
write.update.mode copy-on-write Tugas penulisan dan pengelolaan tabel BigQuery hanya mendukung copy-on-write.
write.merge.mode copy-on-write Tugas penulisan dan pengelolaan tabel BigQuery hanya mendukung copy-on-write.
write.delete.isolation-level Deteksi konflik yang ketat Perubahan yang mengubah file metadata.json (termasuk konflik data, konflik metadata, pembacaan phantom, atau penulisan serentak yang tidak bertentangan) menyebabkan transaksi serentak gagal dan dicoba lagi.
write.update.isolation-level Deteksi konflik yang ketat Perilaku yang sama seperti write.delete.isolation-level.
write.merge.isolation-level Deteksi konflik yang ketat Perilaku yang sama seperti write.delete.isolation-level.

Properti berikut dapat dikonfigurasi saat membuat atau mengubah tabel dari mesin open source:

Properti Nilai default Detail
write.parquet.compression-codec zstd Pengoptimalan penulisan dan penyimpanan BigQuery hanya mendukung format kompresi zstd dan snappy. Format kompresi lainnya (seperti gzip, brotli, dan lz4) tidak didukung.
write.metadata.compression-codec null Dapat dikonfigurasi ke null atau gzip.
history.expire.max-snapshot-age-ms 432000000 (5 hari) Dapat dikonfigurasi ke bilangan bulat non-negatif hingga 2592000000 (30 hari) saat pengelolaan tabel diaktifkan, dengan rekomendasi hingga 7 hari (604800000 md). Tugas pengelolaan tabel menghapus snapshot yang lebih lama dari durasi yang ditentukan.
history.expire.min-snapshots-to-keep 1 Dapat dikonfigurasi ke bilangan bulat positif apa pun hingga 100 saat pengelolaan tabel diaktifkan. Tugas pengelolaan tabel mempertahankan setidaknya jumlah snapshot ini.

Properti penulisan Apache Iceberg lainnya, seperti write.target-file-size-bytes dan write.parquet.page-size-bytes, dapat dikonfigurasi dari mesin open source, tetapi penulisan BigQuery dan tugas pengelolaan tabel mungkin tidak mematuhinya.

Langkah berikutnya