Membuat katalog

Katalog runtime Lakehouse memungkinkan Anda membuat endpoint katalog di Lakehouse tanpa batas.

Endpoint katalog mengarah ke bucket Cloud Storage yang mendasarinya dan menyediakan lapisan metadata yang memungkinkan mesin kueri dan workload open source berinteraksi langsung dengan tabel Anda. Saat membuat endpoint katalog, Anda dapat memilih antara kredensial pengguna akhir dan mode penjualan kredensial untuk delegasi akses penyimpanan.

Sebelum memulai

1. Baca Tentang katalog runtime Lakehouse untuk memahami cara kerja katalog runtime Lakehouse dan batasan untuk layanan ini.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk membuat katalog dan mendaftarkan tabel, minta administrator untuk memberi Anda peran IAM berikut:

• Membuat katalog:
  • BigLake Admin (roles/biglake.admin) di project Anda
  • Storage Admin (roles/storage.admin) di project Anda
• Membuat (mendaftarkan) tabel: BigLake Admin (roles/biglake.admin) di project Anda. Mendaftarkan tabel memerlukan izin pendaftaran tabel tertentu (biglake.tables.register), yang disertakan dalam peran BigLake Admin.
• Gunakan akun layanan katalog yang disediakan otomatis dalam mode penyediaan kredensial: Storage Object User (roles/storage.objectUser) di bucket Cloud Storage target. Setelah membuat katalog, berikan peran Storage Object User (roles/storage.objectUser) secara eksplisit di bucket penyimpanan Anda ke akun layanan yang disediakan secara otomatis.

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Catatan: Pembuatan akun layanan katalog yang disediakan otomatis akhirnya konsisten, yang berarti perlu waktu bagi akun layanan untuk disebarkan melalui sistem. Jika Anda mencoba memberikan peran ke akun layanan segera setelah pembuatan, permintaan mungkin akan gagal. Untuk mempelajari waktu rata-rata yang diperlukan untuk menerapkan perubahan akses, lihat Penerapan perubahan akses.

Membuat katalog

Ikuti langkah-langkah berikut untuk membuat katalog berdasarkan mode kredensial dan jenis bucket yang Anda inginkan. Untuk mengetahui informasi selengkapnya tentang berbagai jenis katalog, lihat Tentang endpoint katalog REST Apache Iceberg.

Catatan: Saat membuat atau mengelola katalog beberapa bucket di Google Cloud, tentukan jalur Cloud Storage (gs://) untuk lokasi penyimpanan default dan terbatas. Format URI bl://projects/PROJECT_ID/catalogs/CATALOG_ID digunakan secara eksklusif selama konfigurasi klien untuk mengidentifikasi warehouse katalog saat terhubung dari mesin kueri (seperti Apache Spark atau Trino).

Konsol

Membuat katalog beberapa bucket (direkomendasikan)

Konfigurasi ini memungkinkan katalog Anda mengaitkan beberapa bucket dan memungkinkan Anda memberi nama katalog secara independen dari nama bucket apa pun.

1. Buka halaman Lakehouse di konsol Google Cloud .

   Buka Lakehouse

2. Klik Create catalog, lalu pilih katalog runtime Lakehouse.

3. Untuk Catalog type, pilih Iceberg Rest Catalog.

4. Untuk Lakehouse catalog bucket options, pilih Multiple bucket catalog.

5. Untuk Default Catalog Cloud Storage path, masukkan atau cari jalur Cloud Storage yang akan digunakan dengan katalog Anda.

6. Untuk ID Katalog, masukkan nama kustom untuk katalog Anda.

7. Untuk Primary location, pilih lokasi. Lokasi harus berada di dekat region bucket utama.

8. Klik Lanjutkan.

9. Pada langkah Jalur data, jika Anda ingin menambahkan jalur Cloud Storage tambahan, klik Tambahkan jalur, lalu masukkan atau cari jalur.

10. Klik Lanjutkan.

11. Untuk metode autentikasi, pilih End-user credentials atau Credential vending mode.

    Catatan: Jika Anda memilih Kredensial pengguna akhir, katalog runtime Lakehouse tidak akan otomatis mengelola tabel dalam katalog. Anda tidak dapat mengaktifkan tugas pengelolaan tabel seperti pemadatan dan masa berlaku snapshot.

12. Klik Create.

    Katalog Anda akan dibuat, dan halaman Detail katalog akan terbuka.

13. Jika Anda memilih Credential vending mode, lakukan langkah-langkah tambahan berikut:

    1. Di bagian Metode autentikasi, klik Set bucket permissions (atau Set permissions for buckets jika katalog Anda menggunakan lebih dari satu bucket).
    2. Dalam dialog, klik Confirm.

Membuat katalog satu bucket

Perhatian: Hindari penggunaan konfigurasi bucket tunggal untuk project baru. Konfigurasi ini membatasi katalog Anda ke satu bucket dan mengunci nama katalog ke nama bucket.

1. Di halaman Lakehouse, klik Create catalog, lalu pilih katalog runtime Lakehouse.
2. Untuk Catalog type, pilih Iceberg Rest Catalog atau Hive Metastore.
3. Jika Anda memilih Iceberg Rest Catalog, untuk Lakehouse catalog bucket options, pilih Single bucket catalog.
4. Untuk Default Catalog Cloud Storage bucket (atau Default Catalog Cloud Storage path untuk endpoint katalog Apache Hive), masukkan atau cari bucket Cloud Storage yang akan digunakan dengan katalog Anda. Untuk katalog bucket tunggal, Anda hanya dapat memiliki satu katalog per bucket, dan nama katalog cocok dengan nama bucket.
5. Klik Lanjutkan.
6. Untuk metode autentikasi, pilih End-user credentials atau Credential vending mode.
7. Klik Create.
8. Jika Anda memilih Credential vending mode, lakukan langkah-langkah tambahan berikut:
   1. Di bagian metode autentikasi, klik Set bucket permissions.
   2. Dalam dialog, klik Confirm.

gcloud

Membuat katalog beberapa bucket (direkomendasikan)

Konfigurasi ini memungkinkan katalog Anda mengaitkan beberapa bucket dan memungkinkan Anda memberi nama katalog secara independen dari nama bucket apa pun.

Untuk membuat katalog beberapa bucket (direkomendasikan), jalankan perintah gcloud biglake iceberg catalogs create:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    --credential-mode CREDENTIAL_MODE \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    [--primary-location LOCATION]

Ganti kode berikut:

• CATALOG_NAME: nama untuk katalog Anda. Untuk katalog multi-bucket (direkomendasikan), ini adalah nama katalog kustom Anda.
• PROJECT_ID: project ID Google Cloud Anda.
• DEFAULT_LOCATION: lokasi penyimpanan default untuk katalog. Anda dapat menentukan bucket (gs://my-bucket) atau subjalur (gs://my-bucket/path). Semua namespace dan tabel dalam katalog harus berada di jalur yang ditentukan. Misalnya, jika Anda menentukan gs://my-bucket/path, Anda tidak dapat membuat namespace atau tabel di bagian gs://my-bucket/another/path.

• CREDENTIAL_MODE: metode autentikasi. Gunakan end-user untuk kredensial pengguna akhir atau vended-credentials untuk mode penjualan kredensial. Jika Anda menentukan end-user, katalog runtime Lakehouse tidak akan otomatis mengelola tabel dalam katalog. Anda tidak dapat mengaktifkan tugas pengelolaan tabel seperti pemadatan dan masa berlaku snapshot.

  Catatan: Jika menggunakan mode penyediaan kredensial, Anda harus secara eksplisit memberikan peran Storage Object User (roles/storage.objectUser) di semua bucket penyimpanan terkait ke akun layanan runtime Lakehouse yang disediakan otomatis di katalog Anda.

• RESTRICTED_LOCATIONS: opsional: daftar lokasi penyimpanan tambahan yang diizinkan dan dipisahkan koma, dalam format gs://my-bucket-1/...,gs://my-bucket-2/.... Jika Anda menentukan jalur (seperti gs://my-bucket/path), namespace atau tabel apa pun dalam bucket tersebut harus berada di jalur tersebut. Semua lokasi Cloud Storage yang dikonfigurasi di seluruh lokasi default dan lokasi yang dibatasi harus berada dalam grup wilayah geografis atau yurisdiksi yang sama (seperti Amerika Serikat, Eropa, Kanada, atau Asia). Misalnya, Anda tidak dapat menggabungkan bucket di AS dengan bucket di Eropa. Untuk mengetahui daftar lokasi yang didukung, lihat Lokasi Lakehouse.

  Peringatan: Hindari mengonfigurasi jalur yang tumpang-tindih dengan katalog lain untuk mencegah eksposur kredensial yang tidak sah. Untuk mengetahui informasi selengkapnya, lihat Penyimpanan di beberapa bucket.

• LOCATION: opsional: region utama untuk katalog guna memastikan interoperabilitas dengan BigQuery. Untuk bucket Cloud Storage di region AS (misalnya, US atau us-central1) atau region EU (misalnya, EU atau europe-west4), tentukan US atau EU untuk memastikan katalog dapat diakses dan tersedia untuk kueri dari multi-region BigQuery yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Region bucket dan katalog.

Membuat katalog satu bucket

Perhatian: Hindari penggunaan konfigurasi bucket tunggal untuk project baru. Konfigurasi ini membatasi katalog Anda ke satu bucket dan mengunci nama katalog ke nama bucket.

Untuk membuat katalog bucket tunggal, jalankan perintah berikut:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode CREDENTIAL_MODE

Ganti kode berikut:

• CATALOG_NAME: nama untuk katalog Anda. Untuk katalog bucket tunggal, ID ini cocok dengan ID bucket Cloud Storage yang digunakan dengan katalog.
• PROJECT_ID: project ID Google Cloud Anda.
• CREDENTIAL_MODE: metode autentikasi. Gunakan end-user untuk kredensial pengguna akhir atau vended-credentials untuk mode penjualan kredensial.

REST

Membuat endpoint katalog REST Apache Iceberg

Untuk membuat endpoint pengelolaan katalog menggunakan REST API, buat permintaan POST ke endpoint CreateIcebergCatalog:

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg-catalog-id=CATALOG_ID

Isi permintaan harus berisi payload JSON IcebergCatalog yang menentukan konfigurasi katalog, seperti warehouse bucket Cloud Storage yang mendasarinya dan mode autentikasi.

Ganti kode berikut:

• PROJECT_ID: Project ID Google Cloud Anda.
• CATALOG_ID: ID katalog runtime Lakehouse Anda.