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 dan perilaku perutean regional yang didukung.

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-nya 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 atas, 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 ditentukan (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, 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 (direkomendasikan) atau katalog satu bucket.

Kedua opsi mendukung penjualan kredensial.

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

  • Katalog multi-bucket: Tetapkan jalur data warehouse ke bl://projects/PROJECT_ID/catalogs/CATALOG_ID.
  • Katalog satu bucket: Tetapkan jalur data warehouse ke gs://CLOUD_STORAGE_BUCKET_NAME.

Katalog multi-bucket (direkomendasikan)

Pendekatan ini memungkinkan Anda 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 data warehouse klien (bl://): Saat mengonfigurasi klien Iceberg untuk terhubung ke katalog multi-bucket, tentukan jalur data warehouse menggunakan format URI bl://: bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Format bl:// hanya digunakan 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://).
  • Bucket maksimum: Anda dapat menentukan maksimum 15 bucket 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 gs://my-bucket/another/path. default_location digunakan untuk namespace yang dibuat tanpa lokasi yang ditentukan.
  • Lokasi yang dibatasi: Anda juga dapat memberikan konfigurasi opsional restricted_locations 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 region geografis: Meskipun bucket dapat lintas project, lintas region, dan memiliki konfigurasi yang berbeda (seperti region tunggal, 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 lokasi yang dibatasi. Perhatikan bahwa tabel yang dibuat di 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 keamanan dan pengelolaan tabel.

Katalog satu bucket

Ini adalah pendekatan lama yang memungkinkan 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 CATALOG_TYPE_GCS_BUCKET konfigurasi.

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

Misalnya, jika Anda memberi nama bucket iceberg-bucket, katalog dan bucket Anda akan memiliki nama yang sama. 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 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).

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

  • 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 katalog multi-bucket (direkomendasikan): Anda dapat mengupgrade katalog satu bucket yang ada ke katalog multi-bucket (direkomendasikan). Katalog yang diupgrade akan mempertahankan nama bucket aslinya. 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 diturunkan dari bucket yang dikonfigurasi di default_location.
  • Katalog satu bucket: Region katalog diturunkan secara ketat dari bucket yang terkait dengan katalog dan tidak dapat di sesuaikan.

Region katalog yang dipetakan bervariasi bergantung pada jenis region bucket:

  • Region tunggal: Region katalog cocok 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 BigQuery menjalankan kueri atas tabel di 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

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

  • Bucket multi-region US atau EU.
  • Bucket region tunggal 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.

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

Langkah Berikutnya