As of April 20th, 2026, BigLake is now called Google Cloud Lakehouse. BigLake metastore is now called the Lakehouse runtime catalog. Lakehouse APIs, client libraries, CLI commands, and IAM names remain unchanged and still reference BigLake.

Menggunakan katalog REST Iceberg Lakehouse

Untuk alur kerja baru, sebaiknya gunakan endpoint katalog REST Apache Iceberg dalam katalog runtime Lakehouse.

Endpoint ini berfungsi sebagai sumber kebenaran tunggal, sehingga memungkinkan interoperabilitas yang lancar di seluruh mesin kueri Anda. Dengan demikian, mesin seperti Apache Spark dapat menemukan, membaca, dan mengelola tabel Google Cloud Lakehouse Anda secara konsisten.

Pendekatan ini adalah pilihan yang baik jika Anda menggunakan mesin open source 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.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.
Mengaktifkan BigLake API.
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. 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 pemberian kredensial katalog:
- BigLake Admin (roles/biglake.admin) di project
- Storage Admin (roles/storage.admin) di bucket Cloud Storage
Membaca data tabel dalam mode penyediaan kredensial: BigLake Viewer (roles/biglake.viewer) di project
Menulis data tabel dalam mode penyediaan kredensial: BigLake Editor (roles/biglake.editor) di project
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 bucket Cloud Storage
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 bucket Cloud Storage
Lakukan operasi bahasa pengolahan data (DML) dengan federasi katalog BigQuery:
- BigQuery Data Editor (roles/bigquery.dataEditor) di project
- Storage Admin (roles/storage.admin) di bucket Cloud Storage. Jika Anda menggunakan mesin kueri seperti Managed Service for Apache Spark untuk melakukan operasi DML, berikan peran ini ke akun layanan yang Anda gunakan untuk menjalankan tugas di mesin tersebut.

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

Trino hanya didukung dengan federasi katalog BigQuery saat menggunakan versi image Managed Service for Apache Spark di Compute Engine 2.3.16 dan yang lebih baru.
Saat menggunakan mode penyediaan kredensial, Anda harus menyetel properti io-impl ke org.apache.iceberg.gcp.gcs.GCSFileIO. Default, org.apache.iceberg.hadoop.HadoopFileIO, tidak didukung.

Batasan tabel

Tabel yang dikelola melalui endpoint katalog REST Apache Iceberg tidak mendukung kontrol akses mendetail (FGAC), seperti keamanan tingkat baris dan tingkat kolom.

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 Iceberg metadata.json dibatasi hingga 1 MB. Untuk meminta peningkatan batas ini, hubungi tim Akun Google Anda.

Batasan kueri

Tampilan atas tabel Apache Iceberg yang dikelola oleh endpoint katalog REST Apache Iceberg tidak dapat dibuat di BigQuery.
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.

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:

Berdasarkan Ringkasan endpoint katalog REST Iceberg, pilih lokasi gudang katalog Anda (Cloud Storage atau BigQuery).
Jika Anda menggunakan gudang gs:// Cloud Storage, 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

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

Dengan kredensial pengguna akhir, katalog meneruskan identitas pengguna akhir yang mengaksesnya ke Cloud Storage untuk pemeriksaan otorisasi.
Pemberian kredensial adalah mekanisme delegasi akses penyimpanan yang memungkinkan administrator katalog runtime Lakehouse mengontrol izin secara langsung pada resource katalog runtime Lakehouse, sehingga pengguna katalog tidak perlu memiliki akses langsung ke bucket Cloud Storage. Dengan fitur ini, administrator Google Cloud Lakehouse dapat memberikan izin kepada pengguna atas file data tertentu.

Kredensial pengguna akhir

Konsol

Buka halaman Lakehouse di Google Cloud konsol.

Buka Google Cloud Lakehouse
Klik Buat katalog.
Di kolom Pilih bucket Cloud Storage, masukkan nama bucket Cloud Storage yang akan digunakan dengan katalog Anda. Atau, klik Jelajahi untuk memilih bucket yang ada atau membuat bucket baru. Anda hanya dapat memiliki satu katalog per bucket Cloud Storage.
Untuk Authentication method, pilih End-user credentials.
Klik Create.

gcloud

Gunakan gcloud biglake iceberg catalogs create perintah.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user \
    [--primary-location LOCATION]

Ganti kode berikut:

CATALOG_NAME: nama untuk katalog Anda. Untuk tabel katalog REST Lakehouse terkelola untuk Apache Iceberg, nama ini sering kali cocok dengan ID bucket Cloud Storage yang digunakan dengan katalog REST—misalnya, jika bucket Anda adalah gs://bucket-id, nama katalognya mungkin bucket-id. Nama ini juga digunakan sebagai ID katalog saat melakukan kueri tabel ini dari BigQuery.
PROJECT_ID: Google Cloud Project ID Anda.
LOCATION: (Opsional) Wilayah utama untuk katalog. Untuk bucket multi-region Cloud Storage AS atau Uni Eropa, tentukan US atau EU untuk memastikan katalog dapat diakses dari region BigQuery yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Region katalog.

Mode penyediaan kredensial

Administrator katalog mengaktifkan penyediaan kredensial saat membuat atau memperbarui katalog. Sebagai pengguna katalog, Anda kemudian dapat menginstruksikan endpoint katalog REST Apache Iceberg untuk menampilkan kredensial penyimpanan yang cakupannya dikecilkan dengan menentukan delegasi akses saat Anda mengonfigurasi endpoint katalog REST Apache Iceberg.

Konsol

Di konsol Google Cloud , buka halaman Lakehouse.

Buka Google Cloud Lakehouse
Klik Buat katalog. Halaman Buat katalog akan terbuka.
Untuk Pilih bucket Cloud Storage, masukkan nama bucket Cloud Storage yang akan digunakan dengan katalog Anda. Atau, klik Jelajahi untuk memilih dari daftar bucket yang ada atau membuat bucket baru. Anda hanya dapat memiliki satu katalog per bucket Cloud Storage.
Untuk Authentication method, pilih Credential vending mode.
Klik Create.

Katalog Anda dibuat dan halaman Detail katalog akan terbuka.
Di bagian Authentication method, klik Set bucket permissions.
Pada dialog, klik Konfirmasi.

Hal ini memverifikasi bahwa akun layanan katalog Anda memiliki peran Storage Object User di bucket penyimpanan Anda.

Mengonfigurasi aplikasi klien

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

Cluster

Untuk menggunakan Spark dengan endpoint katalog REST Apache Iceberg di Managed Service for Apache Spark, buat terlebih dahulu cluster yang menyertakan komponen Apache Iceberg:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION

Ganti kode berikut:

CLUSTER_NAME: nama untuk cluster Anda.
PROJECT_ID: Google Cloud Project ID Anda.
REGION: region untuk cluster Managed Service for Apache Spark.
DATAPROC_VERSION: versi image Managed Service for Apache Spark, misalnya 2.2.

Setelah membuat cluster, konfigurasikan sesi Spark Anda 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 endpoint katalog REST Apache Iceberg Anda.
APP_NAME: nama untuk sesi Spark Anda.
REST_API_VERSION: ditetapkan ke v1 untuk API versi stabil. Setel ke v1beta jika Anda perlu mengatasi masalah umum terkait pembuatan silsilah data.
WAREHOUSE_PATH: Jalur ke gudang Anda. Gunakan gs://CLOUD_STORAGE_BUCKET_NAME. Untuk menggunakan penggabungan katalog BigQuery, lihat Menggunakan penggabungan katalog dengan BigQuery.
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 pengambilan 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', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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.

Cluster Managed Service for 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 for Apache Spark pada versi image Compute Engine 2.3 2.3.11 dan yang lebih baru.

Serverless

Kirimkan workload batch PySpark ke Managed Service for Apache Spark dengan konfigurasi berikut:

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.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    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.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

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 for Apache Spark.
RUNTIME_VERSION: versi runtime Managed Service for Apache Spark, misalnya 2.2.
CATALOG_NAME: nama endpoint katalog REST Apache Iceberg Anda.
REST_API_VERSION: ditetapkan ke v1 untuk API versi stabil. Setel ke v1beta jika Anda perlu mengatasi masalah umum terkait pembuatan silsilah data.
WAREHOUSE_PATH: Jalur ke gudang Anda. Gunakan gs://CLOUD_STORAGE_BUCKET_NAME. Untuk menggunakan penggabungan katalog BigQuery, lihat Menggunakan penggabungan katalog dengan BigQuery.

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 for 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 pengambilan 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=gs://CLOUD_STORAGE_BUCKET_NAME,\
    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.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

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 for 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 for Apache Spark.
DATAPROC_VERSION: Versi image Managed Service for Apache Spark, misalnya 2.2.
NETWORK_ID: ID jaringan cluster. Untuk mengetahui informasi selengkapnya, lihat Konfigurasi jaringan cluster Managed Service for Apache Spark.
CATALOG_NAME: nama katalog Trino Anda menggunakan Endpoint katalog REST Apache Iceberg.
REST_API_VERSION: ditetapkan ke v1 untuk API versi stabil. Setel ke v1beta jika Anda perlu mengatasi masalah umum terkait pembuatan silsilah data.
WAREHOUSE_PATH: Jalur ke gudang Anda. Gunakan gs://CLOUD_STORAGE_BUCKET_NAME.
PROJECT_ID: project ID Anda yang akan digunakan untuk katalog runtime Lakehouse. Google Cloud

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 for Apache Spark di Compute Engine versi runtime 2.2 2.2.65 dan yang lebih baru
Managed Service untuk Apache Spark di Compute Engine versi runtime 2.3 2.3.11 dan yang lebih baru
Managed Service for Apache Spark di Compute Engine 3.0 tidak didukung.

Mengonfigurasi dengan penyediaan kredensial

Pemberian kredensial tidak didukung di Managed Service untuk Apache Spark Trino.

Apache Iceberg 1.10 atau yang lebih baru

Rilis Apache Iceberg 1.10 dan yang lebih baru open source memiliki dukungan bawaan untuk alur otorisasi Google di GoogleAuthManager. Berikut adalah contoh cara mengonfigurasi Spark untuk menggunakan endpoint katalog runtime Lakehouse dan 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 endpoint katalog REST Apache Iceberg Anda.
APP_NAME: nama untuk sesi Spark Anda.
REST_API_VERSION: ditetapkan ke v1 untuk API versi stabil. Setel ke v1beta jika Anda perlu mengatasi masalah umum terkait pembuatan silsilah data.
WAREHOUSE_PATH: Jalur ke gudang Anda. Gunakan gs://CLOUD_STORAGE_BUCKET_NAME. Untuk menggunakan penggabungan katalog BigQuery, lihat Menggunakan penggabungan katalog dengan BigQuery.
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 pengambilan 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', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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 endpoint katalog REST Apache Iceberg Anda.
APP_NAME: nama untuk sesi Spark Anda.
REST_API_VERSION: ditetapkan ke v1 untuk API versi stabil. Setel ke v1beta jika Anda perlu mengatasi masalah umum terkait pembuatan silsilah data.
WAREHOUSE_PATH: Jalur ke gudang Anda. Gunakan gs://CLOUD_STORAGE_BUCKET_NAME. Untuk menggunakan penggabungan katalog BigQuery, lihat Menggunakan penggabungan katalog dengan BigQuery.
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 pengambilan 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', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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.

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.

Mengkueri tabel di BigQuery

Cara Anda membuat kueri tabel yang Anda buat melalui endpoint katalog REST Apache Iceberg di BigQuery bergantung pada apakah Anda menggunakan warehouse bucket Cloud Storage atau federasi BigQuery.

Warehouse bucket Cloud Storage: Jika Anda mengonfigurasi klien dengan jalur warehouse gs://, kueri tabel dari BigQuery menggunakan nama empat bagian (P.C.N.T) project.catalog.namespace.table. Untuk mengetahui informasi selengkapnya tentang struktur P.C.N.T, lihat Konsep katalog REST Iceberg. Komponen catalog adalah nama resource katalog runtime Lakehouse Anda. Untuk mengetahui informasi selengkapnya tentang cara membuat kueri tabel, lihat Membuat kueri tabel.
Federasi BigQuery: Jika Anda mengonfigurasi klien dengan jalur gudang bq://, tabel yang Anda buat akan terlihat di BigQuery dan dapat dikueri langsung menggunakan SQL BigQuery standar:
```
SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;
```
Ganti kode berikut:
- NAMESPACE_NAME: nama namespace Anda.
- TABLE_NAME: nama tabel Anda.

Menggunakan federasi katalog dengan BigQuery

Untuk mempelajari federasi katalog, lihat Konsep katalog REST Iceberg. Untuk mengaktifkan federasi, konfigurasi klien Anda dengan format pergudangan bq://projects/PROJECT_ID di kolom WAREHOUSE_PATH dalam contoh konfigurasi klien di Mengonfigurasi aplikasi klien. Anda juga dapat memilih untuk menyertakan lokasi BigQuery guna membatasi permintaan mendatang ke satu lokasi menggunakan format bq://projects/PROJECT_ID/locations/LOCATION.

Karena resource ini dikelola oleh BigQuery, Anda harus memiliki izin yang diperlukan yang berlaku.

Setelah mengonfigurasi klien untuk federasi, Anda dapat membuat namespace untuk tabel gabungan.

Spark

Untuk menggunakan federasi katalog BigQuery, sertakan klausa LOCATION dan DBPROPERTIES:

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

Ganti kode berikut:

NAMESPACE_NAME: nama untuk namespace Anda.
BUCKET_NAME: bucket Cloud Storage yang Anda gunakan dengan katalog Anda.
LOCATION: a lokasi BigQuery. Nilai defaultnya adalah multi-region US.

Trino

Untuk menggunakan federasi katalog BigQuery, sertakan properti LOCATION dan gcp-region:

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
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.
BUCKET_NAME: bucket Cloud Storage yang Anda gunakan dengan katalog Anda.
LOCATION: a lokasi BigQuery. Nilai defaultnya adalah multi-region US.

Harga

Untuk mengetahui detail harga, lihat Harga Google Cloud Lakehouse.

Langkah berikutnya

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

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

Sebelum memulai

Peran yang diperlukan

Batasan

Menyiapkan endpoint katalog REST Iceberg

Membuat katalog

Kredensial pengguna akhir

Konsol

gcloud

Mode penyediaan kredensial

Konsol

Mengonfigurasi aplikasi klien

Cluster

Mengonfigurasi dengan penyediaan kredensial

Contoh dengan penyediaan kredensial

Serverless

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

Spark

Warehouse Cloud Storage

Trino

Warehouse Cloud Storage

Mengkueri tabel di BigQuery

Menggunakan federasi katalog dengan BigQuery

Spark

Trino

Harga

Langkah berikutnya

Menggunakan katalog REST Iceberg Lakehouse