Mengonfigurasi opsi tabel

Dengan mengonfigurasi opsi tabel, Anda dapat memilih untuk mengaktifkan interoperabilitas penulisan BigQuery atau pengelolaan tabel (pengoptimalan penyimpanan otomatis) untuk tabel Apache Iceberg di katalog runtime Lakehouse. Opsi ini berfungsi sebagai setelan dasar yang memperluas kemampuan untuk operasi pada tabel.

Dengan mengonfigurasi properti tabel tertentu, Anda dapat mengaktifkan interoperabilitas tulis dengan DML BigQuery atau mengaktifkan pengelolaan tabel otomatis (pengoptimalan penyimpanan).

Saat menggunakan tabel dalam katalog runtime Lakehouse, ada baiknya memahami berbagai jenis tabel dan kemampuan keikutsertaannya. Untuk mempelajari lebih lanjut cara menggunakan tabel Apache Iceberg secara khusus, lihat Ringkasan tabel Apache Iceberg.

Sebelum memulai

  1. Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

  2. Mengaktifkan BigLake API.

    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 Admin Penggunaan Layanan (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:

  • Mengonfigurasi properti tabel dalam mode penyediaan kredensial: Editor BigLake (roles/biglake.editor) - project
  • Konfigurasi properti tabel dalam mode penyediaan non-kredensial:
    • Editor BigLake (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

Hanya tabel Apache Iceberg V2 (GA) dan V3 (Pratinjau) yang didukung. Tabel Iceberg V1 tidak didukung. Untuk mengupgrade tabel V1 yang ada, lihat Mengupgrade tabel Iceberg V1 ke V2.

Persyaratan penjualan kredensial

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

Mengaktifkan DML BigQuery

Mengaktifkan pernyataan bahasa pengolahan data (DML) BigQuery memungkinkan interoperabilitas penulisan 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 di tabel Apache Iceberg di BigQuery.

Mengaktifkan DML BigQuery untuk tabel baru

Saat Anda membuat tabel dari BigQuery, DML BigQuery dan pengelolaan tabel otomatis diaktifkan secara default. Saat Anda membuat tabel dari mesin open source, konfigurasi 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 sudah 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 hanya dapat dibaca untuk BigQuery dan menghentikan pengelolaan tabel otomatis.

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 dan 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. Tindakan ini berjalan otomatis di latar belakang setelah mutasi data. Snapshot daluwarsa berdasarkan properti tabel Iceberg yang dikonfigurasi pengguna history.expire.max-snapshot-age-ms dan history.expire.min-snapshots-to-keep pada tabel. Tindakan ini menghapus entri snapshot yang sudah berakhir dengan membuat satu definisi snapshot tambahan lagi yang diwujudkan oleh file metadata baru yang tidak lagi menyertakan 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 yatim piatu tidak ditangani oleh pengelolaan tabel otomatis. Untuk mengetahui informasi selengkapnya, lihat Batasan.

  • Penggabungan (pemadatan): Penggabungan bertanggung jawab untuk mempertahankan bentuk data, dengan menggabungkan file kecil menjadi file yang lebih besar. Penggabungan berjalan secara otomatis di latar belakang setelah mutasi data apa pun. File dipilih untuk pemadatan jika ukuran rata-rata yang tidak dikompresi kurang dari 50% dari ukuran file target 256 MB. Setiap operasi penggabungan menghasilkan snapshot tabel baru. Tugas penggabungan biasanya akan mengalah dan mencoba lagi setelah operasi DML yang sedang berjalan. Namun, untuk mencegah pengoptimalan penyimpanan yang tidak terbatas, tugas penggabungan dipicu secara paksa setiap 24 jam jika data memenuhi syarat untuk digabungkan.

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

    Frekuensi tugas pengelolaan tabel berkorelasi langsung dengan aktivitas mutasi data. 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. Sebaliknya, volume tulis yang tinggi dapat menghasilkan aktivitas tugas yang lebih terlihat di INFORMATION_SCHEMA.

Mengaktifkan pengelolaan tabel untuk tabel baru

Saat Anda membuat tabel dari BigQuery, DML dan pengelolaan tabel otomatis 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 sudah ada, perbarui properti tabel.

Misalnya, di Spark SQL:

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

Menonaktifkan pengelolaan tabel

Menonaktifkan pengelolaan tabel akan mencegah tugas pengoptimalan latar belakang mendatang dimasukkan dalam antrean, meskipun tugas yang sedang berlangsung akan selesai. Menonaktifkan pengelolaan tabel tidak 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 otomatis) meliputi:

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 format-version 3 Apache Iceberg. Hanya tabel format-versi 2 (spesifikasi Iceberg v2) yang dapat diikutsertakan dalam kemampuan terkelola.
  • Kemampuan terkelola tidak didukung untuk tabel yang memiliki partisi lanjutan, seperti partisi menurut STRING, partisi multi-kolom, atau evolusi partisi.
  • Kemampuan terkelola tidak didukung untuk tabel yang dikonfigurasi dengan urutan pengurutan (misalnya, menggunakan prosedur WRITE ORDER BY atau menyetel write.distribution.mode = range).
  • Kemampuan terkelola tidak didukung untuk tabel Iceberg v2 yang menggunakan mode gabungkan saat dibaca. Hanya tabel yang menggunakan mode update, penghapusan, dan penggabungan salin saat menulis 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 mereferensikan jalur atau kolom bertingkat dalam struktur.
  • Kemampuan terkelola tidak didukung untuk tabel dengan data kustom atau lokasi metadata (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, semua pembaruan skema dari Spark akan gagal karena Spark membaca NUMERIC sebagai NUMERIC(38,9). Sebagai solusi sementara, saat membuat tabel dengan jenis NUMERIC di BigQuery, tetapkan presisi ke NUMERIC(38,9) secara eksplisit.
  • Masalah umum: Menghapus kolom di BigQuery menggunakan DDL (ALTER TABLE ... DROP COLUMN) yang segera diikuti dengan menambahkan kembali kolom dengan nama yang sama tidak didukung.

Batasan dengan perjalanan waktu

  • Jika pengelolaan tabel diaktifkan, nilai maksimum yang direkomendasikan untuk properti history.expire.max-snapshot-age-ms adalah 7 hari.
  • Konfigurasi level project atau tingkat set data BigQuery untuk time travel 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. Setelan retensi kustom yang 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 penghentian masa berlaku snapshot.
  • Pengelolaan tabel otomatis tidak akan menghentikan 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 turunan yang dibuat oleh BigQuery atau mesin open source tidak dibersihkan oleh pengelolaan tabel otomatis. Mesin open source dapat melakukan pembersihan file yatim (misalnya, menggunakan prosedur remove_orphan_files Spark dengan opsi prefix_listing yang ditetapkan ke true).

  • Gabungkan tidak mendukung pengurutan z dan pengurutan linear. Jika tabel Anda berisi properti ini, tata letak tidak dijamin akan dipertahankan setelah penggabungan dijalankan. Jika tabel Anda berisi properti ini, tindakan terbaik adalah tidak mengaktifkan 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 transformasi hour pada kolom DATE), dan jenis kolom INTEGER.
  • Kemampuan terkelola tidak didukung pada tabel dengan transformasi IDENTITY. Pengguna 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 dipartisi dengan tabel berpartisi.
    • Mengganti tabel berpartisi dengan tabel yang tidak berpartisi.
    • Mengganti tabel berpartisi dengan tabel 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 pada properti tabel Iceberg kustom

Properti perilaku tabel berikut tidak dapat dikonfigurasi ke nilai selain default jika kemampuan terkelola diaktifkan. Nilai default dikodekan secara permanen 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 katalog REST Lakehouse digunakan untuk menulis file data.
write.metadata.path table location + /metadata Jalur bucket Cloud Storage default yang dikonfigurasi untuk katalog REST Lakehouse digunakan untuk menulis file metadata.
write.delete.mode copy-on-write Tugas penulisan dan pengelolaan tabel BigQuery hanya mendukung salin saat menulis.
write.update.mode copy-on-write Tugas penulisan dan pengelolaan tabel BigQuery hanya mendukung salin saat menulis.
write.merge.mode copy-on-write Tugas penulisan dan pengelolaan tabel BigQuery hanya mendukung salin saat menulis.
write.delete.isolation-level Deteksi konflik ketat Perubahan yang mengubah file metadata.json (termasuk konflik data, konflik metadata, pembacaan phantom, atau penulisan serentak yang tidak berkonflik) menyebabkan transaksi serentak gagal dan dicoba lagi.
write.update.isolation-level Deteksi konflik ketat Perilaku yang sama seperti write.delete.isolation-level.
write.merge.isolation-level Deteksi konflik 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 positif apa pun, tetapi direkomendasikan hingga 7 hari (604800000 md) jika pengelolaan tabel diaktifkan. 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. 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 tugas penulisan dan pengelolaan tabel BigQuery mungkin tidak mematuhinya.

Langkah berikutnya