Mulai 20 April 2026, BigLake kini disebut Lakehouse untuk Apache Iceberg. Metastore BigLake kini disebut katalog runtime Lakehouse. API Lakehouse, library klien, perintah CLI, dan nama IAM tetap tidak berubah dan masih mereferensikan BigLake.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Menyiapkan endpoint katalog REST Iceberg Lakehouse

Untuk katalog baru, sebaiknya gunakan endpoint katalog REST Apache Iceberg di katalog runtime Lakehouse. Endpoint ini menyediakan antarmuka terkelola sepenuhnya dan standar berdasarkan Apache Iceberg REST Catalog API open source.

Endpoint ini berfungsi sebagai satu sumber tepercaya, yang memungkinkan interoperabilitas yang lancar di seluruh mesin kueri Anda. BigLake memungkinkan mesin seperti Apache Spark menemukan, membaca, dan mengelola tabel Google Cloud Lakehouse Anda.

Pendekatan ini adalah pilihan yang tepat jika Anda menggunakan mesin OSS atau pihak ketiga yang kompatibel untuk mengakses data di Cloud Storage dan memerlukan interoperabilitas dengan mesin lain, termasuk BigQuery. Layanan ini mendukung fitur seperti credential vending untuk kontrol akses terperinci dan replikasi lintas region dan disaster recovery.

Sebaliknya, endpoint Katalog Apache Iceberg kustom untuk BigQuery adalah integrasi sebelumnya. Meskipun alur kerja yang ada dapat terus menggunakannya, katalog REST menawarkan pengalaman yang lebih standar dan kaya fitur.

Sebelum memulai

Pahami katalog runtime Lakehouse dan ringkasan endpoint katalog REST Iceberg sebelum melanjutkan.

Jika memiliki tabel Apache Iceberg versi 1 (V1), Anda harus mengupgradenya sebelum menggunakannya dengan endpoint katalog REST Apache Iceberg. Untuk mengetahui informasi selengkapnya, lihat Mengupgrade tabel Iceberg V1 ke V2.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.
Mengaktifkan BigLake API.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Penggunaan Layanan (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.
Mengaktifkan API

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menggunakan endpoint katalog REST Apache Iceberg di katalog runtime Lakehouse, minta administrator untuk memberi Anda peran IAM berikut:

Lakukan tugas administratif, seperti mengelola akses pengguna katalog, akses penyimpanan, dan mode penjualan kredensial katalog:
- BigLake Admin (roles/biglake.admin) di project
- Admin Penyimpanan (roles/storage.admin) di semua bucket Cloud Storage terkait.
Mendaftarkan tabel dalam katalog Lakehouse: Admin BigLake (roles/biglake.admin) di project.
Membaca data tabel dalam mode penyediaan kredensial: BigLake Viewer (roles/biglake.viewer) di project. Jika Anda menggunakan mesin kueri seperti Managed Service untuk Apache Spark, Managed Service untuk Apache Spark, atau Dataflow untuk membaca data tabel, berikan peran ini ke akun layanan yang Anda gunakan untuk menjalankan tugas di mesin tersebut.
Menulis data tabel dalam mode penyediaan kredensial: BigLake Editor (roles/biglake.editor) di project. Jika Anda menggunakan mesin kueri seperti Managed Service untuk Apache Spark, Managed Service untuk Apache Spark, atau Dataflow untuk menulis data tabel, berikan peran ini ke akun layanan yang Anda gunakan untuk menjalankan tugas di mesin tersebut.
Gunakan akun layanan katalog runtime Lakehouse yang disediakan otomatis dalam mode penyediaan kredensial: Pengguna Objek Penyimpanan (roles/storage.objectUser) di semua bucket Cloud Storage terkait. Setelah membuat katalog, berikan peran Storage Object User (roles/storage.objectUser) secara eksplisit di semua bucket penyimpanan terkait ke akun layanan katalog runtime Lakehouse yang disediakan otomatis untuk katalog Anda.
Membaca resource katalog dan data tabel dalam mode penjualan non-kredensial:
- Pelihat BigLake (roles/biglake.viewer) di project
- Storage Object Viewer (roles/storage.objectViewer) di semua bucket Cloud Storage terkait.
Mengelola resource katalog dan menulis data tabel dalam mode penyediaan non-kredensial:
- BigLake Editor (roles/biglake.editor) di project
- Storage Object User (roles/storage.objectUser) di semua bucket Cloud Storage terkait.

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.

Batasan

Endpoint katalog REST Apache Iceberg tunduk pada batasan berikut:

Batasan umum

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.
Saat menggunakan mode penyediaan kredensial, jika mesin kueri memungkinkan Anda menetapkan properti io-impl untuk koneksi katalog, Anda harus menyetelnya ke org.apache.iceberg.gcp.gcs.GCSFileIO.
Bucket namespace hierarkis saat ini tidak didukung dalam mode Credential Vending.

Batasan tabel

Anda tidak dapat membuat atau mengubah tabel di endpoint katalog REST Apache Iceberg menggunakan pernyataan bahasa definisi data (DDL) atau bahasa pengolahan data (DML) BigQuery. Anda dapat mengubah tabel ini menggunakan BigQuery API (dengan alat command line bq atau library klien), tetapi tindakan ini berisiko membuat perubahan yang tidak kompatibel dengan mesin eksternal.
Tabel yang dikelola melalui endpoint katalog REST Apache Iceberg tidak mendukung kontrol akses terperinci (FGAC), seperti keamanan tingkat baris dan tingkat kolom.
Menetapkan properti tabel Iceberg write.data.path atau write.metadata.path ke nilai selain defaultnya dilarang.
Jalur tabel harus berada dalam jalur namespace induk (misalnya, gs://{namespace_path}/.../{table_name}). Untuk mencegah konflik dan meningkatkan keamanan, akhiran string acak akan otomatis ditambahkan ke lokasi yang dihasilkan (misalnya, gs://{namespace_path}/{table_name}/{random_suffix}).

Batasan data

Hanya file Parquet yang didukung. Untuk mengetahui detail selengkapnya tentang cara BigQuery menangani file Parquet, lihat Memuat data Parquet dari Cloud Storage.
Ukuran file metadata.json Iceberg dibatasi hingga 1 MB. Untuk meminta peningkatan batas ini, hubungi tim Akun Google Anda.

Batasan kueri

Tabel metadata Apache Iceberg (seperti .snapshots atau .files) tidak dapat dikueri di BigQuery menggunakan ID nama lima bagian; Anda dapat mengkueri tabel ini menggunakan Spark.

Pertimbangan

Pertimbangkan konfigurasi berikut saat membuat katalog.

Jenis bucket

Anda dapat memilih untuk membuat katalog satu bucket atau katalog multi-bucket.

Katalog multi-bucket (bl://) (direkomendasikan): Konfigurasi ini memungkinkan katalog Anda mengaitkan beberapa bucket dan memungkinkan Anda memberi nama katalog secara terpisah dari nama bucket.
Bucket tunggal (gs://): Konfigurasi ini membatasi katalog Anda ke satu bucket dan mengunci nama katalog ke nama bucket. Metode ini tidak disarankan untuk project baru.

Mode kredensial (cakupan)

Anda dapat membuat katalog yang menggunakan kredensial pengguna akhir atau mode penyediaan kredensial.

Kredensial pengguna akhir: Katalog meneruskan identitas pengguna akhir yang mengaksesnya ke Cloud Storage untuk pemeriksaan otorisasi.
Mode penyediaan kredensial: Mekanisme delegasi akses penyimpanan yang memungkinkan administrator katalog runtime Lakehouse mengontrol izin langsung pada resource katalog runtime Lakehouse, sehingga pengguna katalog tidak perlu memiliki akses langsung ke bucket Cloud Storage. Hal ini memungkinkan administrator Lakehouse Google Cloud memberikan izin kepada pengguna atas file data tertentu.

Akun layanan katalog runtime Lakehouse yang disediakan otomatis memerlukan peran Storage Object User (roles/storage.objectUser) eksplisit di semua bucket Cloud Storage terkait. Secara default, pengguna tidak memiliki akses apa pun. Tanpa peran ini, kredensial yang disediakan tidak akan memiliki cakupan yang memadai untuk melakukan penulisan penyimpanan. Jika Anda menggunakan alat seperti gcloud atau Terraform, Anda harus memberikan peran ini secara manual.

Pembuatan akun layanan katalog yang disediakan otomatis pada akhirnya akan konsisten. Artinya, perlu waktu agar akun layanan dapat ditransmisikan melalui sistem. Jika Anda mencoba memberikan peran ke akun layanan segera setelah pembuatan, permintaan mungkin gagal. Untuk mempelajari waktu rata-rata yang diperlukan agar perubahan akses diterapkan, lihat Penerapan perubahan akses.

Lokasi

Pahami persyaratan lokasi sebelum membuat katalog.

Saat Anda membuat namespace, namespace tersebut akan otomatis menggunakan region yang sama dengan katalog Anda.
Jika katalog Anda menggunakan bucket multi-region dan Anda ingin menggunakannya dengan multi-region BigQuery (US atau EU), Anda harus menghapus dan membuat ulang katalog untuk menentukan lokasi utama.

Menyiapkan endpoint katalog REST Iceberg

Sebelum menyiapkan katalog, sebaiknya baca Ringkasan endpoint katalog REST Apache Iceberg untuk memahami hierarki resource, jenis katalog, dan struktur penamaannya.

Berikut adalah langkah-langkah umum yang harus diikuti saat menggunakan endpoint katalog REST Apache Iceberg di katalog runtime Lakehouse:

Pilih jenis katalog Anda—katalog multi-bucket (bl://) (direkomendasikan) atau katalog single-bucket (gs://).
Buat katalog yang mengarah ke lokasi gudang Anda.
Konfigurasi aplikasi klien Anda untuk menggunakan endpoint katalog REST Apache Iceberg.
Buat namespace atau skema untuk mengatur tabel Anda.
Buat dan kueri tabel menggunakan klien yang telah Anda konfigurasi.

Membuat katalog

Ikuti langkah-langkah berikut untuk membuat katalog berdasarkan mode kredensial dan jenis bucket yang Anda inginkan.

Konsol

Membuat katalog multi-bucket (bl://) (direkomendasikan)

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

Buka halaman Lakehouse di konsol Google Cloud .

Buka Lakehouse
Klik Buat katalog.
Untuk Catalog type, pilih Iceberg Rest Catalog.
Untuk Lakehouse catalog bucket options, pilih Multiple bucket catalog.
Untuk Jalur Cloud Storage Katalog Default, masukkan atau jelajahi jalur Cloud Storage yang akan digunakan dengan katalog Anda.
Untuk ID Katalog, masukkan nama kustom untuk katalog Anda.
Untuk Lokasi utama, pilih lokasi. Lokasi harus dekat dengan region bucket utama.
Klik Lanjutkan.
Pada langkah Jalur data, tambahkan jalur Cloud Storage tambahan jika diperlukan.
Klik Lanjutkan.
Untuk Authentication method, pilih End-user credentials atau Credential vending mode.
Klik Create.

Katalog Anda dibuat dan halaman Detail katalog akan terbuka.
Jika Anda memilih Credential vending mode, lakukan langkah-langkah tambahan berikut:
1. Di bagian Metode autentikasi, klik Setel izin bucket.
2. Pada dialog, klik Konfirmasi.

Membuat katalog bucket tunggal (`gs://`)

Untuk Catalog type, pilih Iceberg Rest Catalog.
Untuk Lakehouse catalog bucket options, pilih Single bucket catalog.
Untuk Jalur Cloud Storage Katalog Default, masukkan atau jelajahi jalur Cloud Storage yang akan digunakan dengan katalog Anda. (Untuk katalog bucket tunggal (gs://), Anda hanya dapat memiliki satu katalog per bucket, dan nama katalog cocok dengan nama bucket).
Klik Lanjutkan.
Untuk Authentication method, pilih End-user credentials atau Credential vending mode.
Klik Create.
Jika Anda memilih Credential vending mode, lakukan langkah-langkah tambahan berikut:
1. Di bagian Metode autentikasi, klik Setel izin bucket.
2. Pada dialog, klik Konfirmasi.

gcloud

Membuat katalog multi-bucket (bl://) (direkomendasikan)

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

Untuk membuat katalog multi-bucket (bl://) (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 (bl://) (direkomendasikan), ini adalah nama katalog kustom Anda. Untuk katalog bucket tunggal (gs://), ID ini cocok dengan ID bucket Cloud Storage yang digunakan dengan katalog REST.
PROJECT_ID: Google Cloud Project ID Anda.
DEFAULT_LOCATION: Tentukan 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 gs://my-bucket/another/path.
CREDENTIAL_MODE: metode autentikasi. Gunakan end-user untuk End-user credentials atau vended-credentials untuk Credential vending mode.

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 di katalog Anda.
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), semua namespace atau tabel dalam bucket tersebut harus berada di jalur tersebut. Semua lokasi penyimpanan cloud yang dikonfigurasi di seluruh lokasi default dan lokasi terbatas harus berada dalam grup wilayah geografis atau wilayah hukum 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) Wilayah 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 dikueri dari multi-region BigQuery yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Region bucket dan katalog.

Membuat katalog bucket tunggal (`gs://`)

Untuk membuat katalog satu bucket (gs://), 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 multi-bucket (bl://) (direkomendasikan), ini adalah nama katalog kustom Anda. Untuk katalog bucket tunggal (gs://), ID ini cocok dengan ID bucket Cloud Storage yang digunakan dengan katalog REST.
PROJECT_ID: project ID Google Cloud Anda.
CREDENTIAL_MODE: metode autentikasi. Gunakan end-user untuk End-user credentials atau vended-credentials untuk Credential vending mode.

Mengonfigurasi aplikasi klien

Setelah membuat katalog, konfigurasikan aplikasi klien Anda untuk menggunakannya. Contoh ini menunjukkan cara mengonfigurasi dengan atau tanpa penyediaan kredensial.

Cluster

Buat cluster Managed Service untuk Apache Spark di Compute Engine menggunakan properti konfigurasi yang disederhanakan (direkomendasikan), atau dengan menentukan properti secara manual.

Konfigurasi yang disederhanakan menggunakan properti (direkomendasikan)

Buat cluster dengan properti katalog:

gcloud dataproc clusters create CLUSTER_NAME \
  --enable-component-gateway \
  --project=PROJECT_ID \
  --region=REGION \
  --optional-components=ICEBERG \
  --image-version=DATAPROC_VERSION \
  --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Ganti kode berikut:

CLUSTER_NAME: nama untuk cluster Anda.
PROJECT_ID: Google Cloud Project ID Anda.
REGION: region cluster Managed Service untuk Apache Spark.
DATAPROC_VERSION: versi image Managed Service untuk Apache Spark—misalnya, 2.3.
CATALOG_NAME: nama untuk katalog Spark lokal (misalnya, my_catalog). Nama ini bisa sama dengan CATALOG_ID.
CATALOG_ID: ID katalog yang Anda buat.

Di file aplikasi PySpark, buat SparkSession tanpa menentukan konfigurasi katalog:

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

Konfigurasi manual

Jika Anda tidak menggunakan properti konfigurasi yang disederhanakan, buat cluster seperti yang dijelaskan di atas, tetapi tanpa tanda --properties. Kemudian, konfigurasi SparkSession secara manual:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .getOrCreate()

Ganti kode berikut:

CATALOG_NAME: nama untuk katalog Spark lokal (misalnya, my_catalog).
APP_NAME: nama untuk sesi Spark Anda.
REST_API_VERSION: ditetapkan ke v1 untuk versi API yang stabil.
WAREHOUSE_PATH: Jalur ke gudang Anda. Untuk katalog BigLake, gunakan bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Untuk katalog bucket Cloud Storage, gunakan gs://CLOUD_STORAGE_BUCKET_NAME.
PROJECT_ID: project yang ditagih untuk penggunaan endpoint katalog REST Apache Iceberg, yang mungkin berbeda dengan project yang memiliki bucket Cloud Storage. Untuk mengetahui detail tentang konfigurasi project saat menggunakan REST API, lihat Parameter sistem.

Mengonfigurasi dengan penyediaan kredensial

Untuk menggunakan penyediaan kredensial, Anda harus menggunakan katalog dalam mode penyediaan kredensial dan menambahkan header X-Iceberg-Access-Delegation ke permintaan katalog REST Iceberg dengan nilai vended-credentials dengan menambahkan baris berikut ke builder SparkSession:

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Contoh dengan penyediaan kredensial

Contoh berikut mengonfigurasi mesin kueri dengan penyediaan kredensial:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .getOrCreate()

Untuk mengetahui informasi selengkapnya, lihat bagian Header di RESTCatalog dalam dokumentasi Apache Iceberg.

Cluster Managed Service untuk Apache Spark mendukung alur otorisasi Google untuk Apache Iceberg dalam rilis berikut:

Managed Service untuk Apache Spark di Compute Engine versi image 2.2 2.2.65 dan yang lebih baru.
Managed Service untuk Apache Spark di versi image Compute Engine 2.3 2.3.11 dan yang lebih baru.

Serverless

Kirim workload batch PySpark ke Managed Service untuk Apache Spark menggunakan properti konfigurasi yang disederhanakan (direkomendasikan), atau dengan menentukan properti secara manual.

Konfigurasi yang disederhanakan menggunakan properti (direkomendasikan)

Kirimkan tugas batch dengan properti katalog:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Ganti kode berikut:

PYSPARK_FILE: jalur Cloud Storage gs:// ke file aplikasi PySpark Anda.
PROJECT_ID: Google Cloud Project ID Anda.
REGION: region untuk workload batch Managed Service untuk Apache Spark.
RUNTIME_VERSION: versi runtime Managed Service untuk Apache Spark, misalnya 2.3.
CATALOG_NAME: nama untuk katalog Spark lokal (misalnya, my_catalog). Nama ini bisa sama dengan CATALOG_ID.
CATALOG_ID: ID katalog yang Anda buat.

Di file aplikasi PySpark, buat SparkSession tanpa menentukan konfigurasi katalog:

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

Konfigurasi manual

Jika Anda tidak menggunakan properti konfigurasi yang disederhanakan, Anda harus menentukan konfigurasi katalog secara manual:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

Ganti kode berikut:

PYSPARK_FILE: jalur Cloud Storage gs:// ke file aplikasi PySpark Anda.
REGION: region untuk workload batch Managed Service untuk Apache Spark.
RUNTIME_VERSION: versi runtime Managed Service untuk Apache Spark, misalnya 2.3.
CATALOG_NAME: nama untuk katalog Spark lokal (misalnya, my_catalog).
REST_API_VERSION: ditetapkan ke v1 untuk versi API yang stabil.
WAREHOUSE_PATH: Jalur ke gudang Anda. Untuk katalog BigLake, gunakan bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Untuk katalog bucket Cloud Storage, gunakan gs://CLOUD_STORAGE_BUCKET_NAME.
PROJECT_ID: project yang ditagih untuk penggunaan endpoint katalog REST Apache Iceberg, yang mungkin berbeda dengan project yang memiliki bucket Cloud Storage. Untuk mengetahui detail tentang konfigurasi project saat menggunakan REST API, lihat Parameter sistem.

Mengonfigurasi dengan penyediaan kredensial

Untuk menggunakan penyediaan kredensial, Anda harus menggunakan katalog dalam mode penyediaan kredensial dan menambahkan header X-Iceberg-Access-Delegation ke permintaan endpoint katalog REST Apache Iceberg dengan nilai vended-credentials dengan menambahkan baris berikut ke konfigurasi Managed Service untuk Apache Spark:

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Contoh dengan penyediaan kredensial

Contoh berikut mengonfigurasi mesin kueri dengan penyediaan kredensial:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\"
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions

Untuk mengetahui informasi selengkapnya, lihat bagian Header di RESTCatalog dalam dokumentasi Apache Iceberg.

Managed Service untuk Apache Spark mendukung alur otorisasi Google untuk Apache Iceberg dalam versi runtime berikut:

Managed Service untuk Apache Spark 2.2 runtime 2.2.60 dan yang lebih baru
Managed Service untuk Apache Spark 2.3 runtime 2.3.10 dan yang lebih baru

Trino

Untuk menggunakan Trino dengan endpoint katalog REST Apache Iceberg, buat cluster Managed Service untuk Apache Spark dengan komponen Trino dan konfigurasi properti katalog menggunakan flag gcloud dataproc clusters create --properties. Contoh berikut membuat katalog Trino bernama CATALOG_NAME:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

Ganti kode berikut:

CLUSTER_NAME: nama untuk cluster Anda.
REGION: region cluster Managed Service untuk Apache Spark.
DATAPROC_VERSION: Versi image Managed Service untuk Apache Spark, misalnya 2.2.
NETWORK_ID: ID jaringan cluster. Untuk mengetahui informasi selengkapnya, lihat Konfigurasi jaringan cluster Managed Service untuk Apache Spark.
CATALOG_NAME: nama katalog Trino Anda menggunakan endpoint katalog REST Apache Iceberg.
REST_API_VERSION: ditetapkan ke v1 untuk versi API yang stabil.
WAREHOUSE_PATH: Jalur ke gudang Anda. Untuk katalog BigLake, gunakan bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Untuk katalog bucket Cloud Storage, gunakan gs://CLOUD_STORAGE_BUCKET_NAME.
PROJECT_ID: Project ID Google Cloud Anda yang akan digunakan untuk katalog runtime Lakehouse.

Setelah pembuatan cluster, hubungkan ke instance VM utama, dan gunakan Trino CLI:

trino --catalog=CATALOG_NAME

Managed Service untuk Apache Spark Trino mendukung alur otorisasi Google untuk Apache Iceberg dalam rilis berikut:

Managed Service untuk Apache Spark di Compute Engine versi runtime 2.2 2.2.65 dan yang lebih baru
Managed Service untuk Apache Spark di versi runtime Compute Engine 2.3 2.3.11 dan yang lebih baru
Managed Service untuk Apache Spark di Compute Engine 3.0 tidak didukung.

Mengonfigurasi dengan penyediaan kredensial

Pemberian kredensial hanya didukung di Trino versi 481 dan yang lebih baru.

Apache Iceberg 1.10 atau yang lebih baru

Rilis Apache Iceberg 1.10 dan yang lebih baru memiliki dukungan bawaan untuk alur otorisasi Google di GoogleAuthManager. Berikut adalah contoh cara mengonfigurasi Spark untuk menggunakan endpoint katalog REST Apache Iceberg.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ganti kode berikut:

CATALOG_NAME: nama untuk katalog Spark lokal (misalnya, my_catalog).
APP_NAME: nama untuk sesi Spark Anda.
REST_API_VERSION: ditetapkan ke v1 untuk versi API yang stabil.
WAREHOUSE_PATH: Jalur ke gudang Anda. Untuk katalog BigLake, gunakan bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Untuk katalog bucket Cloud Storage, gunakan gs://CLOUD_STORAGE_BUCKET_NAME.
PROJECT_ID: project yang ditagih untuk penggunaan endpoint katalog REST Apache Iceberg, yang mungkin berbeda dengan project yang memiliki bucket Cloud Storage. Untuk mengetahui detail tentang konfigurasi project saat menggunakan REST API, lihat Parameter sistem.

Mengonfigurasi dengan penyediaan kredensial

Contoh sebelumnya tidak menggunakan penjualan kredensial. Untuk menggunakan penyediaan kredensial, Anda harus menggunakan katalog dalam mode penyediaan kredensial dan menambahkan header X-Iceberg-Access-Delegation ke permintaan endpoint katalog REST Apache Iceberg dengan nilai vended-credentials dengan menambahkan baris berikut ke builder SparkSession:

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Contoh dengan penyediaan kredensial

Contoh berikut mengonfigurasi mesin kueri dengan penyediaan kredensial:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Untuk mengetahui informasi selengkapnya, lihat bagian Header di RESTCatalog dalam dokumentasi Apache Iceberg.

Rilis Apache Iceberg sebelumnya

Untuk rilis Apache Iceberg open source sebelum 1.10, Anda dapat mengonfigurasi autentikasi OAuth standar dengan mengonfigurasi sesi dengan berikut ini:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ganti kode berikut:

CATALOG_NAME: nama untuk katalog Spark lokal (misalnya, my_catalog).
APP_NAME: nama untuk sesi Spark Anda.
REST_API_VERSION: ditetapkan ke v1 untuk versi API yang stabil.
WAREHOUSE_PATH: Jalur ke gudang Anda. Untuk katalog BigLake, gunakan bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Untuk katalog bucket Cloud Storage, gunakan gs://CLOUD_STORAGE_BUCKET_NAME.
PROJECT_ID: project yang ditagih untuk penggunaan endpoint katalog REST Apache Iceberg, yang mungkin berbeda dengan project yang memiliki bucket Cloud Storage. Untuk mengetahui detail tentang konfigurasi project saat menggunakan REST API, lihat Parameter sistem.
TOKEN: token autentikasi Anda, yang valid selama satu jam—misalnya, token yang dibuat menggunakan gcloud auth application-default print-access-token.

Mengonfigurasi dengan penyediaan kredensial

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Contoh dengan penyediaan kredensial

Contoh berikut mengonfigurasi mesin kueri dengan penyediaan kredensial:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Untuk mengetahui informasi selengkapnya, lihat bagian Header di RESTCatalog dalam dokumentasi Apache Iceberg.

Membuat namespace atau skema

Setelah mengonfigurasi klien, buat namespace atau skema untuk mengatur tabel. Sintaksis untuk membuat namespace atau skema bervariasi bergantung pada mesin kueri Anda. Contoh berikut menunjukkan cara membuatnya menggunakan Spark dan Trino.

Konsol

Di konsol Google Cloud , buka Lakehouse.

Buka Lakehouse
Pilih katalog yang ada atau buat katalog jika Anda belum memilikinya.
Di menu bar, klik + Create namespace.
Untuk Nama namespace, masukkan nama unik untuk namespace Anda.
Untuk Location, tentukan jalur yang akan dikaitkan dengan namespace Anda:
- Beberapa bucket (bl://) (direkomendasikan): Anda dapat menetapkan lokasi kustom apa pun selama berada di bawah lokasi yang diizinkan oleh katalog (default_location atau restricted_locations). Jika Anda tidak menentukan lokasi, namespace akan dibuat di bawah lokasi default katalog (misalnya, gs://{path-to-default-location}/{namespace_name}).
- Bucket tunggal (gs://): Lokasi namespace diwarisi secara otomatis dari bucket tunggal katalog.
Klik Create.

Spark

Warehouse Cloud Storage

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")

Ganti NAMESPACE_NAME dengan nama untuk namespace Anda.

Trino

Warehouse Cloud Storage

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

Ganti kode berikut:

CATALOG_NAME: nama katalog Trino Anda menggunakan endpoint katalog REST Apache Iceberg.
SCHEMA_NAME: nama untuk skema Anda.

Mengupgrade katalog

Jika memiliki katalog bucket tunggal (gs://), Anda dapat mengupgrade katalog tersebut ke jenis katalog multi-bucket (bl://) (direkomendasikan). Dengan mengupgrade, Anda dapat mengaitkan beberapa bucket dan mengonfigurasi lokasi terbatas sambil mempertahankan nama katalog asli.

Untuk mengupgrade katalog, lihat Memperbarui katalog.

Langkah berikutnya

Pelajari cara mengelola katalog di konsol. Google Cloud
Pelajari tabel katalog REST Lakehouse untuk Apache Iceberg.

Menyiapkan endpoint katalog REST Iceberg Lakehouse Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Peran yang diperlukan

Batasan

Pertimbangan

Jenis bucket

Mode kredensial (cakupan)

Lokasi

Menyiapkan endpoint katalog REST Iceberg

Membuat katalog

Konsol

Membuat katalog bucket tunggal (gs://)

gcloud

Membuat katalog bucket tunggal (gs://)

Mengonfigurasi aplikasi klien

Cluster

Konfigurasi yang disederhanakan menggunakan properti (direkomendasikan)

Konfigurasi manual

Mengonfigurasi dengan penyediaan kredensial

Contoh dengan penyediaan kredensial

Serverless

Konfigurasi yang disederhanakan menggunakan properti (direkomendasikan)

Konfigurasi manual

Mengonfigurasi dengan penyediaan kredensial

Contoh dengan penyediaan kredensial

Trino

Mengonfigurasi dengan penyediaan kredensial

Apache Iceberg 1.10 atau yang lebih baru

Mengonfigurasi dengan penyediaan kredensial

Contoh dengan penyediaan kredensial

Rilis Apache Iceberg sebelumnya

Mengonfigurasi dengan penyediaan kredensial

Contoh dengan penyediaan kredensial

Membuat namespace atau skema

Konsol

Spark

Warehouse Cloud Storage

Trino

Warehouse Cloud Storage

Mengupgrade katalog

Langkah berikutnya

Menyiapkan endpoint katalog REST Iceberg Lakehouse

Membuat katalog bucket tunggal (`gs://`)

Membuat katalog bucket tunggal (`gs://`)