Konsep endpoint katalog REST Apache Iceberg

Lakehouse untuk Apache Iceberg 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, perilaku perutean regional, dan opsi federasi kueri.

Kemampuan dan kepatuhan

Katalog runtime Lakehouse dibuat untuk berintegrasi dengan mesin kueri yang kompatibel dengan 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 mengupgrade tabel tersebut ke versi yang didukung. Untuk mengetahui informasi selengkapnya, lihat Mengupgrade tabel Iceberg V1 ke V2.

Kepatuhan API dan operasi REST

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

Hierarki resource

Endpoint katalog REST Apache Iceberg menggunakan hierarki resource untuk mengatur data Anda. Tabel berikut memberikan gambaran umum tingkat tinggi tentang resource 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. Setiap katalog didukung oleh lokasi penyimpanan data warehouse yang ditetapkan (seperti bucket Cloud Storage atau proxy federasi BigQuery) yang menyimpan file data dan metadata dasarnya.
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.

Katalog dan lokasi penyimpanan

Konfigurasi katalog menentukan cara pengoperasian dan integrasinya dengan layanan Google Cloud. Anda dapat mengonfigurasi katalog multi-bucket (bl://) (direkomendasikan) atau katalog bucket tunggal (gs://).

Kedua opsi mendukung penyediaan kredensial untuk kontrol akses terperinci.

Multi-bucket (bl://) (direkomendasikan)

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

Pertimbangan:

  • 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 gs://my-bucket/another/path. Untuk namespace yang dibuat tanpa lokasi yang ditentukan, default_location akan digunakan.
  • Lokasi terbatas: 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), semua resource yang dibuat menggunakan konfigurasi tersebut harus berada di jalur tersebut (misalnya, gs://my-bucket/another/path tidak dapat menghosting namespace atau tabel).
  • Persyaratan grup wilayah geografis: Meskipun bucket dapat berupa 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 terbatas harus berada dalam grup wilayah 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 yang berbeda atau lokasi terbatas). 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, selama berada di jalur yang dikonfigurasi di lokasi default atau terbatas. Perhatikan bahwa tabel yang dibuat di katalog ini akan memiliki sufiks 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 keamanan dan pengelolaan tabel.

Satu bucket (gs://)

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

Untuk katalog bucket Cloud Storage, nama katalog ditetapkan ke nama bucket Anda.

Misalnya, jika Anda membuat bucket untuk menyimpan katalog dan menamainya iceberg-bucket, nama katalog dan nama bucket Anda adalah iceberg-bucket. 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.

Pertimbangan:

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

    • Nama katalog: Dikunci ke nama bucket Cloud Storage yang mendasarinya.
    • Project: Dikunci ke project bucket (katalog lintas project tidak didukung).
    • Wilayah: Diturunkan secara ketat dari lokasi bucket dan tidak dapat disesuaikan.
    • Penyimpanan: Membatasi katalog Anda ke satu bucket (tidak ada lokasi yang dibatasi).

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

  • Upgrade ke multi-bucket (bl://) (direkomendasikan): Anda dapat mengupgrade katalog bucket tunggal (gs://) yang ada ke katalog multi-bucket (bl://) (direkomendasikan). Katalog yang diupgrade mempertahankan nama bucket aslinya. Setelah itu, Anda dapat mengaitkan beberapa bucket dengan katalog dan mengonfigurasi lokasi terbatas.

Region bucket dan katalog

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

  • Multi-bucket (bl://) (direkomendasikan): Region katalog berasal dari bucket yang dikonfigurasi di default_location.
  • Bucket tunggal (gs://): Region katalog sepenuhnya berasal dari bucket yang terkait dengan katalog dan tidak dapat disesuaikan.

Wilayah katalog yang dipetakan bervariasi, bergantung pada jenis wilayah 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 sesuai 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 di katalog ini, BigQuery akan merutekan kueri ke region utama katalog. Jika Anda membuat kueri 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

Untuk mengizinkan BigQuery membuat kueri 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 adalah:

  • 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.

Membuat kueri katalog dari BigQuery

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

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

Langkah Berikutnya