Membuat kueri BigQuery menggunakan gabungan katalog

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

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

Cara kerja gabungan katalog BigQuery

Gabungan 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. Menggabungkan ke gudang BigQuery dari katalog runtime Lakehouse: Menggunakan Lakehouse untuk Apache Iceberg REST API katalog runtime Lakehouse, Anda menggabungkan ke gudang yang ditentukan oleh format jalur gudang bq://projects/PROJECT_ID (atau versi regional, bq://projects/PROJECT_ID/locations/LOCATION). Hal ini memungkinkan Anda 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.

Pertimbangan

  • Karena gabungan katalog BigQuery tidak membuat resource katalog Lakehouse khusus, konsep dan konfigurasi tingkat katalog lainnya—seperti hierarki resource, region bucket dan katalog, serta struktur penamaan P.C.N.T empat bagian—tidak berlaku untuk metode ini. Di API yang mendasarinya, hal ini sesuai dengan konfigurasi CATALOG_TYPE_BIGQUERY. Perhatikan bahwa delegasi akses penyimpanan (penjualan kredensial) tidak didukung untuk katalog BigQuery gabungan.

  • Gabungan katalog BigQuery berbeda dengan Lakehouse lintas cloud. Meskipun gabungan katalog BigQuery mengekspos tabel Google Cloud ke mesin OSS eksternal, Lakehouse lintas cloud menghubungkan Google Cloud ke katalog eksternal jarak jauh, seperti Databricks Unity Catalog, untuk mengkueri data yang disimpan di penyedia cloud lain langsung dari BigQuery dan mesin OSS tanpa memigrasikan data. Untuk mengetahui informasi selengkapnya tentang alur kerja tersebut, lihat Tentang Lakehouse lintas cloud.

Perbandingan dengan tabel yang dikelola oleh endpoint katalog REST Apache Iceberg

Gabungan 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 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 BigQuery API dan mesin eksternal seperti Spark.

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

  • Membaca resource katalog dan mengkueri data tabel:
  • Melakukan operasi bahasa pengolahan data (DML) dengan gabungan 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 untuk 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 gabungan katalog BigQuery

Untuk mengaktifkan gabungan katalog BigQuery, konfigurasikan 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 guna membatasi permintaan mendatang ke satu lokasi menggunakan bq://projects/PROJECT_ID/locations/LOCATION format.

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

Membuat namespace untuk tabel gabungan

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

Spark

Untuk menggunakan gabungan 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 default-nya adalah multi-region US.

Trino

Untuk menggunakan gabungan 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 default-nya adalah multi-region US.

Mengkueri tabel gabungan di BigQuery

Tabel yang Anda buat di bawah katalog gabungan terlihat di BigQuery dan dapat dikueri langsung menggunakan BigQuery SQL 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