Menyiapkan katalog REST Lakehouse Iceberg

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

Endpoint ini bertindak sebagai satu sumber tepercaya, yang 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.

  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 guna 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:
  • 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 bucket Cloud Storage target. Setelah membuat katalog, berikan peran Storage Object User (roles/storage.objectUser) secara eksplisit di bucket penyimpanan Anda 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:
  • 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 untuk Apache Spark guna 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 untuk 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 terperinci (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 mengueri 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 lokasi gudang katalog Anda (Cloud Storage atau BigQuery).
  2. Jika Anda menggunakan gudang gs:// Cloud Storage, 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.

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 Lakehouse Google Cloud dapat memberikan izin kepada pengguna atas file data tertentu.

Pertimbangan

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.

Kredensial pengguna akhir

Konsol

  1. Buka halaman Lakehouse di Google Cloud konsol.

    Buka Lakehouse

  2. Klik Buat katalog.

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

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

  5. 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 Apache Iceberg yang didukung oleh katalog runtime Lakehouse, 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 guna memastikan interoperabilitas dengan BigQuery. Untuk bucket Cloud Storage di region AS (misalnya US atau us-central1) atau region Uni Eropa (misalnya EU ataueurope-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 bucket Cloud Storage target. Secara default, aksesnya hanya untuk pelihat. 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 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.

  4. Untuk Authentication method, pilih Credential vending mode.

  5. Klik Create.

    Katalog Anda dibuat dan halaman Detail katalog akan terbuka.

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

  7. Pada dialog, klik Konfirmasi.

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

gcloud

Gunakan gcloud biglake iceberg catalogs create perintah.

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

Ganti kode berikut:

  • CATALOG_NAME: nama untuk katalog Anda. 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 mengueri tabel ini dari BigQuery.
  • PROJECT_ID: Google Cloud Project ID Anda.

  • 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 bucket penyimpanan Anda 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

Untuk menggunakan Spark dengan endpoint katalog REST Apache Iceberg di Managed Service untuk Apache Spark, Anda dapat menggunakan properti untuk menyederhanakan konfigurasi, atau mengonfigurasi sesi 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:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Ganti kode berikut:

  • CLUSTER_NAME: Nama untuk cluster Anda.
  • PROJECT_ID: Project ID Google Cloud Anda.
  • REGION: Region cluster Managed Service untuk Apache Spark.
  • DATAPROC_VERSION: Versi image Managed Service untuk Apache Spark—misalnya, 2.2.
  • CATALOG_NAME: Nama untuk Lakehouse Catalog yang akan digunakan di Spark. Link ini bisa sama dengan CATALOG_ID.
  • CATALOG_ID: ID katalog Lakehouse yang Anda buat.

Kemudian, buat sesi Spark tanpa menentukan parameter katalog manual:

from pyspark.sql import SparkSession

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

Konfigurasi manual

Jika Anda tidak menggunakan properti cluster, buat cluster seperti yang dijelaskan di atas (tanpa flag --properties), lalu konfigurasi sesi Spark Anda 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(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 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', '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 untuk Apache Spark mendukung alur otorisasi Google untuk Apache Iceberg dalam rilis berikut:

  • Managed Service untuk Apache Spark di versi image Compute Engine 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

Kirimkan PySpark batch workload ke Managed Service untuk Apache Spark menggunakan properti untuk menyederhanakan konfigurasi (direkomendasikan) atau dengan menentukan semua parameter.

Kirimkan tugas batch dengan properti katalog:

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

Konfigurasi manual

Jika Anda lebih memilih untuk menentukan semua properti secara manual, gunakan 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 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=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 untuk 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 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 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 di katalog runtime Lakehouse.

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 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', '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 menggunakan kode berikut:

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

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

Langkah berikutnya