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 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 mengupgradenya ke versi yang didukung. Untuk mengetahui informasi selengkapnya, lihat Mengupgrade tabel Iceberg V1 ke V2.

Kepatuhan API dan operasi REST

Katalog runtime Lakehouse menerapkan standar terbuka Apache Iceberg REST Catalog API. 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 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 gudang yang ditetapkan (seperti satu atau beberapa bucket Cloud Storage) 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 (direkomendasikan) atau katalog bucket tunggal.

Kedua opsi mendukung penyediaan kredensial.

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

  • Katalog multi-bucket: Tetapkan jalur gudang ke bl://projects/PROJECT_ID/catalogs/CATALOG_ID.
  • Katalog bucket tunggal: Tetapkan jalur gudang ke gs://CLOUD_STORAGE_BUCKET_NAME.

Katalog multi-bucket (direkomendasikan)

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

Pertimbangan:

  • Konfigurasi gudang klien (bl://): Saat mengonfigurasi klien Iceberg untuk terhubung ke katalog multi-bucket, tentukan jalur gudang 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://).
  • Jumlah maksimum bucket: 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. 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), 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 yang dibatasi). 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 lokasi tersebut berada di jalur yang dikonfigurasi di lokasi default atau terbatas. Perhatikan bahwa tabel yang dibuat di katalog ini akan memiliki sufiks string acak yang ditambahkan secara otomatis 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 bucket tunggal

Ini adalah pendekatan lama di mana katalog secara langsung mengelola metadata dan file data Apache Iceberg dalam satu bucket Cloud Storage (gs://) yang Anda tentukan. Di API pokok, 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 memiliki nama yang sama. Gunakan nama ini saat 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 bucket tunggal lama sangat tidak disarankan untuk project baru. Konfigurasi ini memiliki beberapa batasan penting:

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

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

  • 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 bucket tunggal yang ada ke katalog multi-bucket (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:

  • Katalog multi-bucket: (direkomendasikan): Region katalog berasal dari bucket yang dikonfigurasi di default_location.
  • Katalog satu bucket: 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 cocok persis dengan region bucket.
  • Dual-region: Region katalog cocok dengan dual-region bucket (seperti ASIA1 atau NAM4).
  • Multi-region: Wilayah 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.

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.

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: Google Cloud ID project 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.

Langkah Berikutnya