Konsep endpoint katalog REST Apache Iceberg

Katalog runtime Lakehouse menyediakan pengelolaan metadata terpusat untuk Google Cloud Lakehouse. Dokumen ini menjelaskan konsep inti katalog runtime Lakehouse, dengan berfokus pada endpoint endpoint katalog REST Apache Iceberg, hierarki resource-nya, dan jenis katalog lain yang didukung.

Hierarki resource

Endpoint katalog REST Apache Iceberg menggunakan hierarki resource untuk mengatur data Anda. Tabel berikut memberikan gambaran umum tentang resource ini:

Resource Deskripsi
Katalog Sebagai penampung tingkat atas, katalog memungkinkan Anda mengatur namespace dan tabel ke dalam grup logis dengan membaginya ke dalam katalog yang berbeda.
Namespace Pengelompokan logis yang digunakan untuk mengatur tabel dalam katalog, ini berfungsi seperti database, skema, atau direktori.
Tabel Tabel berisi definisi baris dan kolom yang dapat dikueri.

Jenis katalog yang didukung

Saat mengonfigurasi klien, Anda menentukan lokasi warehouse. Pilihan ini menentukan cara katalog Anda beroperasi dan berintegrasi dengan layanan lain Google Cloud Tabel berikut menjelaskan jenis katalog yang didukung:

Jenis Katalog Deskripsi
Bucket Cloud Storage Semua data dalam katalog disimpan dalam satu bucket Cloud Storage; untuk data yang dibagikan di beberapa bucket, diperlukan beberapa katalog.

Detail warehouse

Direkomendasikan

  • Warehouse bucket Cloud Storage (gs://): Ini adalah pendekatan standar tempat katalog mengelola metadata dan file data Apache Iceberg secara langsung dalam bucket Cloud Storage yang Anda tentukan. Opsi ini memberi Anda kontrol langsung atas tata letak data dan mendukung penjualan kredensial untuk kontrol akses terperinci. Hal ini memungkinkan Anda membuat dan mengelola tabel katalog REST Iceberg Lakehouse.

    Misalnya, jika Anda membuat bucket untuk menyimpan katalog dan menamainya iceberg-bucket, nama katalog dan nama bucket Anda adalah iceberg-bucket. Nama ini akan digunakan nanti saat Anda membuat kueri katalog di BigQuery, menggunakan sintaksis P.C.N.T. Misalnya, my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Alternatif

  • Penggabungan katalog BigQuery (bq://): Pendekatan ini memungkinkan Anda menggunakan endpoint katalog REST Apache Iceberg untuk mengelola dan membuat kueri tabel yang terlihat oleh BigQuery, tanpa perlu membuat resource katalog. Untuk mengetahui informasi selengkapnya, lihat Penggabungan katalog dengan BigQuery.

Region bucket dan katalog

Untuk warehouse bucket Cloud Storage di katalog runtime Lakehouse, sistem akan memilih region katalog agar sesuai dengan region bucket yang mendasarinya:

  • Bucket satu region: Region katalog cocok dengan region bucket.

  • Bucket dua region: Mencakup dua region yang telah ditentukan dan ditentukan pengguna, seperti ASIA1 dan NAM4. Region katalog cocok dengan dua region.

  • Bucket multi-region: Sistem memilih lokasi regional untuk katalog dalam domain geografis multi-region. Secara default, lokasi ini mungkin tidak cocok dengan lokasi BigQuery umum seperti US dan EU. Sebagai gantinya, lokasi tersebut adalah lokasi regional dalam domain geografis (misalnya, us-central1 dan us-east4 untuk bucket multi-region US).

Saat BigQuery menjalankan kueri atas tabel dalam katalog ini, BigQuery akan merutekan kueri ke region di region utama katalog. Jika Anda menjalankan kueri di region virtual tertentu (seperti US atau EU) dan metadata katalog tidak ada di lokasi tersebut, kueri mungkin gagal.

Menentukan region utama untuk multi-region AS dan Uni Eropa

Untuk katalog yang menggunakan bucket multi-region US atau EU, Anda dapat menentukan region utama saat membuat katalog untuk memastikan BigQuery dapat mengaksesnya dari region yang sesuai.

  • Multi-region Cloud Storage Uni Eropa: Tentukan EU atau europe-west4.
  • Multi-region Cloud Storage AS: Tentukan US atau us-central1.

Sistem memilih replika utama katalog saat Anda membuatnya, tetapi Anda dapat memperbaruinya secara dinamis dengan memanggil FailoverCatalog. Untuk mengetahui informasi selengkapnya tentang cara menentukan lokasi utama, lihat menggunakan endpoint katalog REST Apache Iceberg.

Membuat kueri katalog

Saat membuat kueri tabel katalog runtime Lakehouse dari BigQuery, Anda menggunakan struktur penamaan empat bagian, yang sering disebut sebagai P.C.N.T:

  • Project: Project ID yang memiliki katalog. Google Cloud
  • Catalog: Nama katalog runtime Lakehouse.
  • Namespace: Namespace Apache Iceberg (setara dengan set data BigQuery).
  • Table: Nama tabel.

Misalnya, my-project.lakehouse-catalog-id.my-namespace.my-table.

Penggabungan katalog dengan BigQuery

Anda dapat menggunakan antarmuka endpoint katalog REST Apache Iceberg untuk mengelola dan membuat kueri tabel yang terlihat oleh BigQuery.

Katalog penggabungan katalog BigQuery tidak mengharuskan Anda membuat resource katalog; katalog ini dapat digunakan di project mana pun yang mengaktifkan BigQuery API. Hal ini memungkinkan Anda:

Karena resource ini dikelola oleh BigQuery, Anda harus memiliki izin yang diperlukan dan berlaku. Penjualan kredensial tidak didukung untuk katalog gabungan.

Untuk mengaktifkan penggabungan, konfigurasikan klien Anda dengan format warehouse bq://projects/PROJECT_ID di kolom WAREHOUSE_PATH dalam contoh konfigurasi klien di menggunakan endpoint katalog REST Apache Iceberg. Anda juga dapat memilih untuk menyertakan lokasi BigQuery guna membatasi permintaan mendatang ke satu lokasi menggunakan bq://projects/PROJECT_ID/locations/LOCATION format.

Langkah Berikutnya