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 penyediaan 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.
Login ke akun Anda. Google Cloud Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

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

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 diperlukan untuk membuat katalog dan mendaftarkan tabel, minta administrator untuk memberi Anda peran IAM berikut:

• Membuat katalog:
  • Admin BigLake (roles/biglake.admin) di project Anda
  • Admin Penyimpanan (roles/storage.admin) di project Anda
• Membuat (mendaftarkan) tabel: Admin BigLake (roles/biglake.admin) di project Anda. Mendaftarkan tabel memerlukan izin pendaftaran tabel tertentu (biglake.tables.register), yang disertakan dalam peran Admin BigLake.
• Menggunakan akun layanan katalog yang disediakan otomatis dalam mode penyediaan kredensial: Pengguna Objek Penyimpanan (roles/storage.objectUser) di bucket Cloud Storage target. Setelah membuat katalog, berikan peran Pengguna Objek Penyimpanan (roles/storage.objectUser) secara eksplisit di bucket penyimpanan Anda ke akun layanan yang disediakan 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 pada akhirnya konsisten, yang berarti akun layanan memerlukan waktu untuk diterapkan melalui sistem. Jika Anda mencoba memberikan peran ke akun layanan segera setelah pembuatan, permintaan mungkin akan gagal. Untuk mempelajari waktu rata-rata yang diperlukan perubahan akses untuk diterapkan, lihat Penerapan perubahan akses.

Membuat katalog

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

Catatan: Saat membuat atau mengelola katalog multi-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 multi-bucket (direkomendasikan)

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

1. Buka halaman Lakehouse di Google Cloud konsol.

   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 telusuri jalur Cloud Storage yang akan digunakan dengan katalog Anda.

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

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

8. Klik Continue.

9. Pada langkah Data paths , jika Anda ingin menambahkan jalur Cloud Storage tambahan, klik Add path , lalu masukkan atau telusuri jalur.

10. Klik Continue.

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

12. Klik Create.

    Katalog Anda akan dibuat, dan halaman Catalog details 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. Di dialog, klik Confirm.

Membuat katalog satu bucket

Perhatian: Hindari penggunaan konfigurasi satu bucket 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 Lakehouse runtime catalog.
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 telusuri bucket Cloud Storage yang akan digunakan dengan katalog Anda. Untuk katalog satu bucket, Anda hanya dapat memiliki satu katalog per bucket, dan nama katalog cocok dengan nama bucket.
5. Klik Continue.
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. Di dialog, klik Confirm.

gcloud

Membuat katalog multi-bucket (direkomendasikan)

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

Untuk membuat katalog multi-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 bawah jalur yang ditentukan. Misalnya, jika Anda menentukan gs://my-bucket/path, Anda tidak dapat membuat namespace atau tabel di bawah gs://my-bucket/another/path.

• CREDENTIAL_MODE: metode autentikasi. Gunakan end-user untuk kredensial pengguna akhir atau vended-credentials untuk mode penyediaan kredensial.

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

• RESTRICTED_LOCATIONS: opsional: daftar lokasi penyimpanan tambahan yang diizinkan, yang 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 bawah jalur tersebut. Semua lokasi Cloud Storage yang dikonfigurasi di seluruh lokasi default dan lokasi terbatas harus berada dalam grup atau yurisdiksi region geografis 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 kredensial yang tidak sah terekspos. 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 Uni Eropa (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 satu bucket untuk project baru. Konfigurasi ini membatasi katalog Anda ke satu bucket dan mengunci nama katalog ke nama bucket.

Untuk membuat katalog satu bucket, 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 satu bucket, nama ini cocok dengan ID bucket Cloud Storage yang digunakan dengan katalog.
• PROJECT_ID: project ID Anda Google Cloud.
• CREDENTIAL_MODE: metode autentikasi. Gunakan end-user untuk kredensial pengguna akhir atau vended-credentials untuk mode penyediaan kredensial.

REST

Membuat katalog REST Iceberg

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

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 Anda Google Cloud .
• CATALOG_ID: ID katalog runtime Lakehouse Anda.