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, yang berfokus pada endpoint Apache Iceberg REST catalog endpoint, 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 tingkat tinggi tentang sumber daya ini:

Resource Deskripsi
Katalog Sebagai penampung tingkat teratas, 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 gudang. Pilihan ini menentukan cara kerja katalog Anda dan cara mengintegrasikannya dengan layananGoogle Cloud lain. 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.
Penggabungan katalog BigQuery Memungkinkan Anda menggunakan endpoint katalog REST Apache Iceberg untuk mengelola dan mengkueri tabel yang terlihat oleh BigQuery. Untuk informasi selengkapnya, lihat Federasi katalog dengan BigQuery.

Detail gudang

Direkomendasikan

  • Warehouse bucket Cloud Storage (gs://): Ini adalah pendekatan standar di mana katalog mengelola secara langsung metadata Apache Iceberg dan file data dalam bucket Cloud Storage yang Anda tentukan. Opsi ini memberi Anda kontrol langsung atas tata letak data dan mendukung penyediaan kredensial untuk kontrol akses terperinci. Dengan peran ini, Anda dapat 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. Kolom 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://): Dengan pendekatan ini, Anda dapat menggunakan endpoint katalog REST Apache Iceberg untuk mengelola dan mengkueri tabel yang terlihat oleh BigQuery, tanpa perlu membuat resource katalog. Untuk informasi selengkapnya, lihat Federasi katalog dengan BigQuery.

Region bucket dan katalog

Untuk gudang bucket Cloud Storage di katalog runtime Lakehouse, sistem memilih region katalog agar cocok dengan region bucket yang mendasarinya:

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

  • Bucket dual-region: Mencakup dual region standar dan yang ditentukan pengguna, seperti ASIA1 dan NAM4. Region katalog cocok dengan region ganda.

  • Bucket multiregion: Sistem memilih lokasi regional untuk katalog dalam domain geografis multiregion. 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 pada 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 Uni Eropa Cloud Storage: Tentukan EU atau europe-west4.
  • Multi-region AS Cloud Storage: 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 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: Google Cloud Project ID yang memiliki katalog.
  • Catalog: Nama katalog runtime Lakehouse.
  • Namespace: Namespace Apache Iceberg (setara dengan set data BigQuery).
  • Tabel: 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 mengueri tabel yang terlihat oleh BigQuery.

Katalog gabungan 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 yang berlaku. Pemberian kredensial tidak didukung untuk katalog gabungan.

Untuk mengaktifkan federasi, konfigurasi klien Anda dengan format pergudangan 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 format bq://projects/PROJECT_ID/locations/LOCATION.

Langkah Berikutnya