Membuat kueri BigQuery menggunakan gabungan katalog

Lakehouse untuk Apache Iceberg menyediakan interoperabilitas dengan BigQuery melalui fitur yang dikenal sebagai federasi katalog BigQuery. Fitur ini memungkinkan Anda mengekspos tabel yang dikelola oleh BigQuery, misalnya tabel yang dikelola Iceberg, ke mesin open source (OSS) eksternal seperti Apache Spark dan Trino.

Endpoint katalog REST Apache Iceberg bertindak murni sebagai gateway proxy, bukan membuat penampung katalog Lakehouse khusus untuk menyimpan metadata. Saat mesin eksternal terhubung menggunakan awalan gudang bq://, gateway akan merutekan permintaan katalognya langsung ke katalog internal BigQuery. Dengan begitu, Anda dapat membuat dan mengelola tabel langsung dalam BigQuery menggunakan DDL atau API BigQuery standar, sekaligus memberikan akses hanya baca ke mesin OSS eksternal untuk membuat kueri tabel tersebut melalui endpoint katalog REST.

Cara kerja penggabungan katalog BigQuery

Federasi katalog BigQuery memungkinkan Anda mengekspos tabel BigQuery—seperti tabel terkelola Iceberg dan tabel metastore BigQuery—melalui endpoint katalog REST Apache Iceberg katalog runtime Lakehouse.

Alur gabungan katalog BigQuery berfungsi sebagai berikut:

  1. Membuat tabel di katalog BigQuery: Anda membuat tabel terkelola Iceberg di BigQuery menggunakan pernyataan DDL. Tabel ini ada di katalog BigQuery, diatur oleh daftar kontrol akses (ACL) BigQuery, dan berfungsi sebagai resource REST BigQuery.
  2. Gabungkan ke gudang data BigQuery dari katalog runtime Lakehouse: Dengan menggunakan Lakehouse runtime catalog Apache Iceberg REST API, Anda dapat menggabungkan ke gudang data yang ditentukan oleh format jalur gudang data bq://projects/PROJECT_ID (atau versi regionalnya, bq://projects/PROJECT_ID/locations/LOCATION). Dengan demikian, Anda dapat mengakses Tabel BigQuery dari mesin komputasi seperti Apache Spark melalui Lakehouse untuk Apache Iceberg API. Dalam konfigurasi ini, Anda mendapatkan pengalaman hanya baca dari Spark, tetapi pengalaman baca-tulis dari BigQuery.

Perbandingan dengan tabel yang dikelola oleh endpoint katalog REST Apache Iceberg

Federasi katalog BigQuery berbeda dengan alur kerja saat katalog runtime Lakehouse menggunakan endpoint katalog REST Apache Iceberg dengan cara berikut:

  • Pengelolaan resource dan penyimpanan katalog: Tabel gabungan berada di katalog BigQuery sebagai resource REST BigQuery, dan katalog runtime Lakehouse bertindak sebagai gateway proxy. Saat katalog runtime Lakehouse menggunakan endpoint katalog REST Apache Iceberg, tabel disimpan langsung dalam katalog sebagai resource REST Lakehouse untuk Apache Iceberg.
  • Kontrol akses: Tabel gabungan menggunakan izin IAM BigQuery dan daftar kontrol akses (ACL). Saat endpoint katalog runtime Lakehouse menggunakan endpoint katalog REST Apache Iceberg, tabel menggunakan ACL Lakehouse untuk Apache Iceberg.
  • Kemampuan baca dan tulis mesin: Tabel gabungan menyediakan akses baca-tulis melalui BigQuery, tetapi akses hanya baca dari mesin eksternal seperti Spark. Saat katalog runtime Lakehouse menggunakan endpoint katalog REST Apache Iceberg, tabel mendukung operasi baca-tulis dari API BigQuery dan mesin eksternal seperti Spark.

Sebelum memulai

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

  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 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 menggunakan federasi katalog di BigQuery, minta administrator untuk memberi Anda peran IAM berikut:

  • Membaca resource katalog dan membuat kueri data tabel:
  • Lakukan operasi bahasa pengolahan data (DML) dengan federasi katalog BigQuery:
    • BigQuery Data Editor (roles/bigquery.dataEditor) di project
    • Storage Admin (roles/storage.admin) di bucket Cloud Storage. Jika Anda menggunakan mesin kueri seperti Managed Service untuk Apache Spark guna melakukan operasi DML, berikan peran ini ke akun layanan yang Anda gunakan untuk menjalankan tugas di mesin tersebut.

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 penggabungan katalog BigQuery

Untuk mengaktifkan federasi katalog BigQuery, konfigurasi klien Anda (seperti Apache Spark atau Trino) dengan format gudang bq://projects/PROJECT_ID di kolom WAREHOUSE_PATH dalam contoh konfigurasi klien di Mengonfigurasi aplikasi klien.

Anda juga dapat memilih untuk menyertakan lokasi BigQuery untuk membatasi permintaan mendatang ke satu lokasi menggunakan format bq://projects/PROJECT_ID/locations/LOCATION.

Karena resource ini dikelola oleh BigQuery, Anda harus memiliki izin yang diperlukan yang berlaku.

Membuat namespace untuk tabel gabungan

Setelah mengonfigurasi klien untuk federasi katalog BigQuery, Anda dapat membuat namespace untuk tabel gabungan.

Spark

Untuk menggunakan federasi katalog BigQuery, sertakan klausa LOCATION dan DBPROPERTIES:

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

Ganti kode berikut:

  • NAMESPACE_NAME: nama untuk namespace Anda.
  • BUCKET_NAME: bucket Cloud Storage yang Anda gunakan dengan katalog Anda.
  • LOCATION: lokasi BigQuery. Nilai defaultnya adalah multi-region US.

Trino

Untuk menggunakan federasi katalog BigQuery, sertakan properti LOCATION dan gcp-region:

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

Ganti kode berikut:

  • CATALOG_NAME: nama katalog Trino Anda menggunakan endpoint katalog REST Apache Iceberg.
  • SCHEMA_NAME: nama untuk skema Anda.
  • BUCKET_NAME: bucket Cloud Storage yang Anda gunakan dengan katalog Anda.
  • LOCATION: lokasi BigQuery. Nilai defaultnya adalah multi-region US.

Mengkueri tabel gabungan di BigQuery

Tabel yang Anda buat dalam katalog gabungan terlihat di BigQuery dan dapat dikueri secara langsung menggunakan SQL BigQuery standar (tanpa memerlukan nama P.C.N.T empat bagian):

SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

Ganti kode berikut:

  • NAMESPACE_NAME: nama namespace Anda.
  • TABLE_NAME: nama tabel Anda.

Langkah berikutnya