Tentang endpoint katalog REST Apache Iceberg

Lakehouse tanpa batas mengelola metadata melalui katalog runtime Lakehouse. Saat Anda menggunakan endpoint katalog REST Apache Iceberg, sistem akan mengatur data ke dalam hierarki resource yang ketat. Konfigurasi katalog menentukan jenis penyimpanan yang didukung dan perilaku perutean regional.

Kemampuan dan kepatuhan

Katalog runtime Lakehouse dibuat untuk diintegrasikan dengan mesin kueri yang mematuhi Iceberg dengan mendukung format tabel standar dan mematuhi API terbuka.

Format tabel yang didukung

Tabel Apache Iceberg V2 (GA) dan tabel V3 (Pratinjau) didukung. Tabel Iceberg V1 tidak didukung. Sebelum menggunakan tabel V1 yang ada dengan endpoint katalog REST Apache Iceberg, Anda harus mengupgradenya ke versi yang didukung. Untuk mengetahui informasi selengkapnya, lihat Mengupgrade tabel Iceberg V1 ke V2.

Kepatuhan API dan operasi REST

Katalog runtime Lakehouse mengimplementasikan Apache Iceberg REST Catalog API standar terbuka. Mesin kueri klien berinteraksi dengan katalog menggunakan REST catalog API standar. Untuk mengetahui informasi selengkapnya, lihat Cara Lakehouse mengimplementasikan Apache Iceberg REST Catalog API.

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 container tingkat teratas, katalog memungkinkan Anda mengatur namespace dan tabel ke dalam grup logis dengan membaginya ke dalam katalog yang berbeda. Setiap katalog didukung oleh lokasi penyimpanan warehouse yang ditetapkan (seperti satu atau beberapa bucket Cloud Storage) yang menyimpan metadata dan file data yang mendasarinya.
Namespace Pengelompokan logis yang digunakan untuk mengatur tabel dalam katalog, yang berfungsi seperti database, skema, atau direktori.
Tabel Tabel berisi definisi baris dan kolom yang dapat dikueri.

Katalog dan lokasi penyimpanan

Konfigurasi katalog menentukan cara katalog beroperasi dan berintegrasi dengan layanan Google Cloud. Anda dapat mengonfigurasi katalog multi-bucket (direkomendasikan) atau katalog satu bucket.

Kedua opsi tersebut mendukung penyediaan kredensial.

Saat mengonfigurasi mesin kueri klien (seperti Spark atau Trino) untuk terhubung ke endpoint katalog REST Apache Iceberg, Anda menentukan jalur warehouse berdasarkan jenis katalog:

  • Katalog beberapa bucket: Tetapkan jalur warehouse ke bl://projects/PROJECT_ID/catalogs/CATALOG_ID.
  • Katalog bucket tunggal: Tetapkan jalur warehouse ke gs://CLOUD_STORAGE_BUCKET_NAME.

Katalog multi-bucket (direkomendasikan)

Dengan pendekatan ini, Anda dapat memberi nama katalog secara independen dari nama bucket apa pun, dan memungkinkan Anda mengonfigurasi beberapa bucket untuk satu katalog. Di API yang mendasarinya, hal ini sesuai dengan konfigurasi CATALOG_TYPE_BIGLAKE.

Pertimbangan:

  • Konfigurasi warehouse klien (bl://): Saat mengonfigurasi klien Iceberg untuk terhubung ke katalog multi-bucket, tentukan jalur warehouse menggunakan format URI bl://: bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Format bl:// digunakan secara eksklusif selama konfigurasi klien untuk mengidentifikasi katalog. Saat membuat atau mengonfigurasi katalog itu sendiri di Google Cloud, lokasi penyimpanan (default_location dan restricted_locations) selalu ditentukan sebagai jalur Cloud Storage (gs://).
  • Lokasi penyimpanan maksimum: Selain default_location, Anda dapat menentukan hingga 128 bucket atau subjalur Cloud Storage di restricted_locations per katalog.
  • Lokasi default: Anda memberikan jalur ke bucket (default_location) atau subjalur (seperti gs://my-bucket/path) untuk bertindak sebagai lokasi penyimpanan default. Semua resource katalog (namespace dan tabel) harus berada di jalur yang ditentukan. Misalnya, jika Anda menentukan gs://my-bucket/path, Anda tidak dapat menghosting namespace atau tabel di bawah gs://my-bucket/another/path. Untuk namespace yang dibuat tanpa lokasi yang ditentukan, default_location akan digunakan.
  • Lokasi yang dibatasi: Anda juga dapat memberikan konfigurasi restricted_locations opsional untuk bucket atau jalur tambahan tempat namespace dan tabel dapat dibuat. Jika Anda menentukan subjalur (seperti gs://my-bucket/path), resource apa pun yang dibuat menggunakan konfigurasi tersebut harus berada di jalur tersebut (misalnya, gs://my-bucket/another/path tidak dapat menghosting namespace atau tabel).
  • Persyaratan grup region geografis: Meskipun bucket dapat bersifat lintas project, lintas region, dan memiliki konfigurasi yang berbeda (seperti single-region, dual-region, atau multi-region), semua lokasi Cloud Storage di seluruh lokasi default dan lokasi yang dibatasi harus berada dalam grup region geografis yang sama (seperti AS, Eropa, Kanada, atau Asia). Misalnya, Anda tidak dapat mengonfigurasi bucket multi-region AS dengan bucket di Eropa atau Kanada.
  • Beberapa katalog per bucket: Anda dapat memiliki beberapa katalog yang mengarah ke bucket yang sama (misalnya, menggunakan lokasi default atau lokasi yang dibatasi yang berbeda). Namun, konfigurasi ini sangat tidak disarankan karena dapat menyebabkan konflik metadata, penimpaan data yang tidak disengaja, atau masalah keamanan seperti kebocoran izin.
  • Namespace: memungkinkan penentuan lokasi namespace kustom, asalkan berada di jalur yang dikonfigurasi di lokasi default atau yang dibatasi. Perhatikan bahwa tabel yang dibuat dalam katalog ini akan memiliki akhiran string acak yang otomatis ditambahkan ke jalur fisiknya untuk mencegah konflik (misalnya, gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Untuk mengetahui informasi selengkapnya, lihat Aturan pengelolaan dan keamanan tabel.

Katalog bucket tunggal

Ini adalah pendekatan lama, yaitu katalog mengelola metadata dan file data Apache Iceberg secara langsung dalam satu bucket Cloud Storage (gs://) yang Anda tentukan. Di API yang mendasarinya, hal ini sesuai dengan konfigurasi CATALOG_TYPE_GCS_BUCKET.

Untuk katalog bucket tunggal, nama katalog ditetapkan ke nama bucket Anda.

Misalnya, jika Anda memberi nama bucket iceberg-bucket, katalog dan bucket Anda akan menggunakan nama tersebut. Gunakan nama ini saat mengkueri katalog Anda di BigQuery menggunakan sintaksis P.C.N.T, misalnya, my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Pertimbangan:

  • Batasan jenis katalog lama. Penggunaan konfigurasi bucket tunggal lama sangat tidak disarankan untuk project baru. Konfigurasi ini memiliki beberapa batasan penting:

    • Nama katalog: Terkunci ke nama bucket Cloud Storage yang mendasarinya.
    • Project: Terkunci ke project bucket (katalog lintas project tidak didukung).
    • Region: Berasal sepenuhnya dari lokasi bucket dan tidak dapat disesuaikan.
    • Penyimpanan: Membatasi katalog Anda ke satu bucket (tidak ada lokasi yang dibatasi).

  • Konfigurasi warehouse klien (gs://): Saat mengonfigurasi klien Iceberg untuk katalog bucket tunggal, tentukan jalur bucket Cloud Storage (gs://CLOUD_STORAGE_BUCKET_NAME) sebagai lokasi warehouse.

  • Batasan satu katalog per bucket: Untuk jenis katalog lama ini, Anda hanya dapat memiliki satu katalog per bucket, dan nama katalog harus sama dengan nama bucket.

  • Mengupgrade ke katalog multi-bucket (direkomendasikan): Anda dapat mengupgrade katalog single-bucket yang ada ke katalog multi-bucket (direkomendasikan). Katalog yang diupgrade mempertahankan nama bucket asli. Setelah itu, Anda dapat mengaitkan beberapa bucket dengan katalog dan mengonfigurasi lokasi yang dibatasi.

Region bucket dan katalog

Region endpoint katalog di katalog runtime Lakehouse ditentukan oleh region bucket Cloud Storage yang mendasarinya:

  • Katalog multi-bucket: (direkomendasikan): Region katalog berasal dari bucket yang dikonfigurasi di default_location.
  • Katalog bucket tunggal: Region katalog sepenuhnya berasal dari bucket yang terkait dengan katalog dan tidak dapat disesuaikan.

Region katalog yang dipetakan bervariasi bergantung pada jenis region bucket:

  • Satu region: Region katalog sama persis dengan region bucket.
  • Dual-region: Region katalog cocok dengan dual-region bucket (seperti ASIA1 atau NAM4).
  • Multi-region: Region katalog ditetapkan ke lokasi regional tertentu dalam domain geografis multi-region. Secara default, hal ini mungkin tidak selaras dengan multi-region BigQuery umum seperti US dan EU (misalnya, bucket multi-region US dipetakan ke us-central1 atau us-east4).

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

Region utama untuk multi-region

Agar BigQuery dapat mengkueri tabel katalog Anda dari multi-region US atau EU, tentukan US atau EU sebagai region utama saat Anda membuat katalog.

Anda dapat menentukan multi-region (US atau EU) sebagai region utama dalam konfigurasi berikut:

Jika bucket default_location:

  • Bucket multi-region US atau EU.
  • Bucket satu region dalam multi-region tersebut (seperti us-central1 atau europe-west4).
  • Bucket dual-region atau dual-region kustom dalam area tersebut (seperti NAM4 atau EUR4).

Replika utama ditentukan saat Anda membuat katalog, tetapi Anda dapat melakukan failover secara dinamis dengan memanggil FailoverCatalog. Untuk mengetahui informasi selengkapnya, lihat Membuat katalog.

Untuk merutekan permintaan langsung ke region tertentu untuk persyaratan residensi dan kedaulatan data, Anda dapat menggunakan endpoint regional (biglake.LOCATION.rep.googleapis.com). Untuk mengetahui informasi selengkapnya, lihat Endpoint regional Lakehouse.

Membuat kueri katalog dari BigQuery

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

  • Project: Project ID Google Cloud yang memiliki katalog.
  • 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.

Langkah Berikutnya