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.

  1. Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

  2. 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 penjualan kredensial katalog:
  • Mendaftarkan tabel dalam katalog BigLake: 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:
  • Mengelola resource katalog dan menulis data tabel dalam mode penyediaan non-kredensial:

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.
  • Trino hanya didukung dengan federasi katalog BigQuery saat menggunakan Managed Service untuk Apache Spark di Compute Engine versi image 2.3.16 dan yang lebih baru.
  • 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.

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:

  1. Berdasarkan ringkasan endpoint katalog REST Iceberg, pilih jenis katalog Anda. Hal ini memungkinkan Anda mengonfigurasi katalog multi-bucket (bl://) (direkomendasikan) atau katalog single-bucket (gs://).
  2. Buat katalog yang mengarah ke lokasi gudang Anda.
  3. Konfigurasi aplikasi klien Anda untuk menggunakan endpoint katalog REST Apache Iceberg.
  4. Buat namespace atau skema untuk mengatur tabel Anda.
  5. Buat dan kueri tabel menggunakan klien yang telah Anda konfigurasi.

Pertimbangan

Pertimbangkan opsi berikut untuk konfigurasi penyimpanan dan mode kredensial.

Mode kredensial (Cakupan)

Anda dapat membuat katalog yang menggunakan kredensial pengguna akhir atau mode penjualan 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.

Jenis bucket

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

  • Multi-bucket (bl://) (direkomendasikan): Konfigurasi ini memungkinkan katalog Anda mengaitkan beberapa bucket dan memungkinkan Anda memberi nama katalog secara terpisah dari nama bucket. Katalog multi-bucket tidak didukung di konsol Google Cloud .
  • 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.

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.

Membuat katalog

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

Kredensial pengguna akhir

Konsol

  1. Buka halaman Lakehouse di konsol Google Cloud .

    Buka Lakehouse

  2. Klik Buat katalog.

  3. Untuk Catalog type, pilih Cloud Storage bucket.

  4. Masukkan atau cari bucket Cloud Storage yang akan digunakan dengan katalog Anda (untuk katalog satu bucket (gs://), Anda hanya dapat memiliki satu katalog per bucket, dan nama katalog cocok dengan nama bucket).

  5. Untuk Authentication method, pilih End-user credentials.

  6. Klik Create.

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 \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode end-user \
    [--primary-location LOCATION]

Membuat katalog bucket tunggal (gs://)

Untuk membuat katalog bucket tunggal (gs://), jalankan perintah berikut:

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

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. Nama ini juga digunakan sebagai ID katalog saat mengueri tabel ini dari BigQuery.
  • 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.
  • 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 yurisdiksi yang sama (seperti Amerika Serikat, Eropa, Kanada, atau Asia). Misalnya, Anda tidak dapat menggabungkan bucket di Amerika Serikat dengan bucket di Eropa. Untuk mengetahui daftar lokasi yang didukung, lihat Lokasi lakehouse. Peringatan Keamanan: 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.

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 lebih kecil dengan menentukan delegasi akses saat Anda mengonfigurasi endpoint katalog REST Apache Iceberg.

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.

Konsol

  1. Di konsol Google Cloud , buka halaman Lakehouse.

    Buka Lakehouse

  2. Klik Buat katalog. Halaman Buat katalog akan terbuka.

  3. Untuk Catalog type, pilih Cloud Storage bucket.

  4. Masukkan atau cari bucket Cloud Storage yang akan digunakan dengan katalog Anda (untuk katalog satu bucket (gs://), Anda hanya dapat memiliki satu katalog per bucket, dan nama katalog cocok dengan nama bucket).

  5. Untuk Authentication method, pilih Credential vending mode.

  6. Klik Create.

    Katalog Anda dibuat dan halaman Detail katalog akan terbuka.

  7. Di bagian Metode autentikasi, klik Setel izin bucket.

  8. Pada dialog, klik Konfirmasi.

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

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 \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

Membuat katalog bucket tunggal (gs://)

Untuk membuat katalog bucket tunggal (gs://), jalankan perintah berikut:

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

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. Nama ini juga digunakan sebagai ID katalog saat mengueri tabel ini dari BigQuery.
  • 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.
  • 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 yurisdiksi yang sama (seperti Amerika Serikat, Eropa, Kanada, atau Asia). Misalnya, Anda tidak dapat menggabungkan bucket di Amerika Serikat dengan bucket di Eropa. Untuk mengetahui daftar lokasi yang didukung, lihat Lokasi lakehouse. Peringatan Keamanan: 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.

    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.

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.

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. 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 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.

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 for 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 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 for 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. 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 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 for Apache Spark dengan komponen Trino dan konfigurasi properti katalog menggunakan tanda 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 for 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 Compute Engine versi runtime 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. 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 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. 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

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}.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

  1. Di konsol Google Cloud , buka Lakehouse.

    Buka Lakehouse

  2. Pilih katalog yang ada atau buat katalog jika Anda belum memilikinya.

  3. Di menu bar, klik + Create namespace.

  4. Untuk Nama namespace, masukkan nama unik untuk namespace Anda.

  5. Untuk Location, tentukan jalur yang akan dikaitkan dengan namespace Anda:

    • Multi-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}). Perhatikan bahwa katalog multi-bucket (bl://) (direkomendasikan) tidak dapat dikelola di konsol.
    • Bucket tunggal (gs://): Lokasi namespace diwarisi secara otomatis dari bucket tunggal katalog.

  6. 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://) yang sudah ada, 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