Mengonfigurasi opsi tabel

Mengonfigurasi opsi tabel memungkinkan Anda memilih interoperabilitas tulis 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 BigQuery DML atau mengaktifkan pengelolaan tabel otomatis (pengoptimalan penyimpanan).

Saat menggunakan tabel di katalog runtime Lakehouse, sebaiknya pahami berbagai jenis tabel dan kemampuan memilihnya. Untuk mempelajari lebih lanjut cara menggunakan tabel Apache Iceberg secara khusus, lihat Ringkasan tabel Apache Iceberg tables.

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

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

Peran yang diperlukan

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

  • Mengonfigurasi properti tabel dalam mode penjualan kredensial: Editor BigLake (roles/biglake.editor) - project
  • Mengonfigurasi properti tabel dalam mode non-penjualan 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 memilih pengelolaan tabel otomatis, katalog runtime Lakehouse Anda harus mengaktifkan penjualan kredensial di tingkat katalog. Tugas latar belakang pengelolaan tabel menggunakan akun layanan penjualan kredensial untuk mengautentikasi dan memperbarui file data penyimpanan yang mendasarinya.

Mengaktifkan BigQuery DML

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 pernyataan yang tidak didukung di tabel Apache Iceberg di BigQuery.

Mengaktifkan BigQuery DML untuk tabel baru

Saat Anda membuat tabel dari BigQuery, BigQuery DML dan pengelolaan tabel otomatis akan 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 BigQuery DML untuk tabel yang sudah ada

Untuk mengaktifkan BigQuery DML di 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 BigQuery DML

Menonaktifkan BigQuery DML akan membuat tabel bersifat hanya baca 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. Proses ini berjalan otomatis di latar belakang setelah mutasi data apa pun. Masa berlaku snapshot berakhir berdasarkan properti tabel Iceberg yang dikonfigurasi pengguna history.expire.max-snapshot-age-ms dan history.expire.min-snapshots-to-keep di tabel. Proses ini menghapus entri snapshot yang masa berlakunya berakhir dari file metadata.json, diikuti dengan penghapusan fisik file data dan metadata yang hanya dimiliki oleh snapshot yang masa berlakunya berakhir dan tidak lagi direferensikan oleh snapshot aktif.

    • 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 otomatis di latar belakang setelah mutasi data apa pun. File dipilih untuk pemadatan jika ukuran rata-rata yang tidak dikompresi kurang dari 50% ukuran file target sebesar 256 MB. Setiap operasi penggabungan menghasilkan snapshot tabel baru. Tugas penggabungan biasanya akan memberikan hasil dan mencoba lagi setelah operasi DML berjalan. Namun, untuk mencegah pengoptimalan penyimpanan yang tidak terbatas, tugas penggabungan akan dipicu secara paksa setiap 24 jam jika data memenuhi syarat untuk digabungkan.

  • Memantau tugas pengelolaan tabel: Semua tugas pengelolaan tabel latar belakang dicatat di log 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 cara 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 penulisan 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 akan diaktifkan secara default. Saat Anda membuat tabel dari mesin open source, konfigurasikan properti gcp.biglake.table-management.enabled. Mengaktifkan pengelolaan tabel akan otomatis mengaktifkan BigQuery DML 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 sudah ada

Untuk mengaktifkan pengelolaan tabel di 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 ke dalam antrean, meskipun tugas yang sedang berlangsung akan selesai. Menonaktifkan pengelolaan tabel tidak akan menonaktifkan BigQuery DML.

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 tulis BigQuery dan pengelolaan tabel otomatis) 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 (spesifikasi Iceberg v2) yang dapat memilih 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 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, hapus, dan gabungkan copy-on-write yang dapat memilih 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 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, semua 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 segera diikuti dengan menambahkan kembali kolom dengan nama yang sama tidak didukung.

Batasan terkait perjalanan waktu

  • Jika pengelolaan tabel diaktifkan, nilai maksimum yang direkomendasikan untuk properti history.expire.max-snapshot-age-ms adalah 7 hari.
  • Konfigurasi tingkat project atau tingkat 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 otomatis tidak mengakhiri masa berlaku skema atau spesifikasi partisi. File metadata.json mempertahankan histori lengkap skema dan spesifikasi partisi, meskipun tidak ada snapshot yang merujuk ke ID skema tersebut.

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

  • Penggabungan tidak mendukung pengurutan z dan pengurutan linear. Jika tabel Anda berisi properti ini, tata letak tidak dijamin akan dipertahankan setelah penggabungan berjalan. Jika tabel Anda berisi properti ini, tindakan terbaiknya adalah tidak mengaktifkan pengelolaan tabel.

Batasan terkait partisi

  • Saat membuat atau mendaftarkan tabel dari mesin open source, kemampuan terkelola hanya mendukung partisi pada DATE, TIMESTAMP, dan TIMESTAMPTZ jenis kolom dengan hour, day, month, dan year transformasi (kecuali transformasi hour pada kolom DATE).
  • 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 yang dipartisi.
    • Mengganti tabel yang dipartisi dengan tabel yang tidak dipartisi.
    • Mengganti tabel yang dipartisi 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 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 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 tulis BigQuery dan pengelolaan tabel hanya mendukung copy-on-write.
write.update.mode copy-on-write Tugas tulis BigQuery dan pengelolaan tabel hanya mendukung copy-on-write.
write.merge.mode copy-on-write Tugas tulis BigQuery dan pengelolaan tabel hanya mendukung copy-on-write.
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 konflik) akan menyebabkan transaksi serentak gagal dan mencoba lagi.
write.update.isolation-level Deteksi konflik ketat Perilaku yang sama dengan write.delete.isolation-level.
write.merge.isolation-level Deteksi konflik ketat Perilaku yang sama dengan 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 Tugas tulis BigQuery dan pengoptimalan penyimpanan 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) saat 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 tulis Apache Iceberg lainnya, seperti write.target-file-size-bytes dan write.parquet.page-size-bytes, dapat dikonfigurasi dari mesin open source, tetapi tugas tulis BigQuery dan pengelolaan tabel mungkin tidak mematuhinya.

Langkah berikutnya