Menggunakan katalog REST Iceberg BigLake Metastore

Katalog REST Apache Iceberg di BigLake Metastore adalah cara yang direkomendasikan untuk menggunakan BigLake Metastore untuk alur kerja baru. Hal ini menciptakan interoperabilitas antar-mesin kueri Anda dengan menawarkan satu sumber tepercaya untuk semua data Iceberg Anda. BigLake Metastore memungkinkan mesin kueri, seperti Apache Spark, menemukan, membaca metadata dari, dan mengelola tabel Iceberg 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 penyediaan kredensial untuk kontrol akses terperinci dan replikasi lintas region dan pemulihan bencana.

Sebaliknya, katalog 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 metastore BigLake sebelum melanjutkan.

Verify that billing is enabled for your Google Cloud project.
Enable the BigLake API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the API

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menggunakan katalog REST Iceberg di metastore BigLake, minta administrator Anda 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

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

Katalog REST Iceberg tunduk pada batasan berikut:

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.
Trino hanya didukung dengan federasi katalog BigQuery saat menggunakan versi image Dataproc di Compute Engine 2.3, yaitu 2.3.16 dan yang lebih baru.

Resource katalog

Katalog REST Apache Iceberg di BigLake Metastore menggunakan hierarki resource untuk mengatur data Anda.

Resource katalog REST Apache Iceberg

Tabel berikut memberikan gambaran umum tentang resource yang digunakan oleh katalog REST Apache Iceberg di metastore BigLake.

Resource	Deskripsi
Katalog	Sebagai penampung tingkat teratas, katalog memungkinkan Anda mengatur namespace dan tabel ke dalam grup logis dengan membaginya ke dalam katalog yang berbeda.
Namespace	Pengelompokan logis yang digunakan untuk mengatur tabel dalam katalog, ini berfungsi seperti database, skema, atau direktori.
Tabel	Tabel berisi definisi baris dan kolom yang dapat dikueri.

Katalog yang didukung

Saat mengonfigurasi klien, Anda menentukan lokasi gudang. Pilihan ini menentukan cara kerja katalog Anda dan cara mengintegrasikannya dengan layanan lain. Google Cloud

Jenis Katalog	Deskripsi
Bucket Cloud Storage	Semua data dalam katalog disimpan dalam satu bucket Cloud Storage; untuk data yang dibagikan di beberapa bucket, diperlukan beberapa katalog.
Penggabungan BigQuery	Memungkinkan Anda menggunakan katalog REST Iceberg untuk mengelola dan mengkueri tabel yang terlihat oleh BigQuery. Untuk informasi selengkapnya, lihat Menggunakan federasi katalog dengan BigQuery.

Detail gudang katalog

Direkomendasikan

Warehouse bucket Cloud Storage (gs://): Ini adalah pendekatan standar di mana katalog mengelola file data dan metadata Iceberg secara langsung dalam bucket Cloud Storage yang Anda tentukan. Opsi ini memberi Anda kontrol langsung atas tata letak data dan mendukung penjualan kredensial untuk kontrol akses terperinci. Dengan demikian, Anda dapat membuat dan mengelola tabel BigLake untuk Apache Iceberg.

Penting: Untuk katalog yang menggunakan bucket Cloud Storage sebagai gudang, nama katalog juga merupakan ID resource katalog.

Misalnya, jika Anda membuat bucket untuk menyimpan katalog dan menamainya iceberg-bucket, nama katalog dan nama bucket Anda adalah iceberg-bucket. Ini akan digunakan nanti saat Anda mengkueri katalog di BigQuery, menggunakan sintaksis P.C.N.T. Contohnya, my-project.biglake-catalog-id.quickstart_namespace.quickstart_table.

Lama

Penggabungan BigQuery (bq://): Pendekatan ini memungkinkan Anda menggunakan katalog REST Iceberg untuk mengelola dan membuat kueri tabel yang terlihat oleh BigQuery, tanpa perlu membuat resource katalog. Untuk mengetahui informasi selengkapnya, lihat Menggunakan federasi katalog dengan BigQuery.

Struktur penamaan P.C.N.T

Saat membuat kueri tabel metastore BigLake dari BigQuery, Anda menggunakan struktur penamaan empat bagian, yang sering disebut sebagai P.C.N.T:

Project: Google Cloud Project ID yang memiliki katalog.
Catalog: Nama katalog metastore BigLake.
Namespace: Namespace Iceberg (setara dengan set data BigQuery).
Tabel: Nama tabel.

Misalnya, my-project.biglake-catalog-id.my-namespace.my-table.

Menyiapkan katalog REST Iceberg

Berikut adalah langkah-langkah umum yang harus diikuti saat menggunakan katalog REST Apache Iceberg di metastore BigLake:

Pahami dan pilih lokasi gudang katalog Anda, baik 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 katalog REST 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 metastore BigLake mengontrol izin secara langsung pada resource metastore BigLake, sehingga pengguna katalog tidak perlu memiliki akses langsung ke bucket Cloud Storage. Dengan fitur ini, administrator BigLake dapat memberikan izin kepada pengguna atas file data tertentu.

Kredensial pengguna akhir

Konsol

Buka halaman BigLake di Google Cloud konsol.

Buka BigLake
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 perintah gcloud beta biglake iceberg catalogs create.

gcloud beta 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 tabel BigLake 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.

Mode penyediaan kredensial

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

Konsol

Di Konsol Google Cloud , buka halaman BigLake.

Buka BigLake
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 penjualan kredensial.

Cluster

Untuk menggunakan Spark dengan katalog REST Iceberg di Dataproc, pertama-tama buat cluster yang menyertakan komponen 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 Dataproc.
DATAPROC_VERSION: versi image Dataproc, misalnya 2.2.

Setelah membuat cluster, konfigurasi sesi Spark untuk menggunakan katalog REST 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ganti kode berikut:

CATALOG_NAME: nama katalog REST Iceberg Anda.
APP_NAME: nama untuk sesi Spark Anda.
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 katalog REST 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 Iceberg.

Cluster Dataproc mendukung alur otorisasi Google untuk Iceberg dalam rilis berikut:

Versi image Dataproc di Compute Engine 2.2 2.2.65 dan yang lebih baru.
Versi image Dataproc di Compute Engine 2.3 2.3.11 dan yang lebih baru.

Serverless

Kirimkan workload batch PySpark ke Google Cloud Serverless 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/v1/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,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false"

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 Dataproc.
RUNTIME_VERSION: versi runtime Serverless for Apache Spark, misalnya 2.2.
CATALOG_NAME: nama katalog REST Iceberg Anda.
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

.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/v1/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.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

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

Serverless for Apache Spark mendukung alur otorisasi Google untuk Iceberg dalam versi runtime berikut:

Runtime Serverless for Apache Spark 2.2 2.2.60 dan yang lebih baru
Runtime Serverless for Apache Spark 2.3 versi 2.3.10 dan yang lebih baru

Trino

Untuk menggunakan Trino dengan katalog REST Iceberg, buat cluster Dataproc dengan komponen Trino dan konfigurasikan 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/v1/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 Dataproc.
DATAPROC_VERSION: Versi image Dataproc, misalnya 2.2.
NETWORK_ID: ID jaringan cluster. Untuk mengetahui informasi selengkapnya, lihat Konfigurasi jaringan cluster Dataproc.
CATALOG_NAME: nama katalog Trino Anda menggunakan katalog REST Iceberg.
WAREHOUSE_PATH: Jalur ke gudang Anda. Gunakan gs://CLOUD_STORAGE_BUCKET_NAME.
PROJECT_ID: project ID Google Cloud Anda yang akan digunakan untuk metastore BigLake.

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

trino --catalog=CATALOG_NAME

Dataproc Trino mendukung alur otorisasi Google untuk Iceberg dalam rilis berikut:

Versi runtime Dataproc di Compute Engine 2.2 2.2.65 dan yang lebih baru
Versi runtime Dataproc di Compute Engine 2.3 2.3.11 dan yang lebih baru
Dataproc di Compute Engine 3.0 tidak didukung.

Mengonfigurasi dengan penyediaan kredensial

Pemberian kredensial tidak didukung di Dataproc Trino.

Iceberg 1.10 atau yang lebih baru

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

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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ganti kode berikut:

CATALOG_NAME: nama katalog REST Iceberg Anda.
APP_NAME: nama untuk sesi Spark Anda.
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 katalog REST 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 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 Iceberg.

Rilis Iceberg sebelumnya

Untuk rilis 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ganti kode berikut:

CATALOG_NAME: nama katalog REST Iceberg Anda.
APP_NAME: nama untuk sesi Spark Anda.
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 katalog REST Iceberg, yang mungkin berbeda dengan project yang memiliki bucket Cloud Storage. Untuk mengetahui detail tentang konfigurasi project saat menggunakan REST API, lihat Parameter sistem.
TOKEN: token autentikasi Anda, yang valid selama satu jam—misalnya, token yang dibuat menggunakan gcloud auth application-default print-access-token.

Mengonfigurasi dengan penyediaan kredensial

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

Contoh dengan penyediaan kredensial

Contoh berikut mengonfigurasi mesin kueri dengan penyediaan kredensial:

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 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 katalog REST Iceberg.
SCHEMA_NAME: nama untuk skema Anda.

Mengkueri tabel di BigQuery

Cara Anda membuat kueri tabel yang Anda buat melalui katalog REST 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. Komponen catalog adalah nama resource katalog metastore BigLake Anda. Untuk mengetahui informasi selengkapnya, 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

Anda dapat menggunakan antarmuka katalog REST Iceberg untuk mengelola dan mengueri tabel yang terlihat oleh BigQuery. Katalog federasi BigQuery tidak mengharuskan Anda membuat resource katalog; katalog ini dapat digunakan di project mana pun yang mengaktifkan BigQuery API. Hal ini memungkinkan Anda:

Membuat dan mengelola tabel Iceberg eksternal di BigQuery.
Kueri tabel BigLake untuk Apache Iceberg di BigQuery dengan katalog REST Iceberg.

Karena resource ini dikelola oleh BigQuery, Anda harus memiliki izin yang diperlukan yang berlaku. Pemberian kredensial tidak didukung untuk katalog gabungan.

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

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: 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 katalog REST Iceberg.
SCHEMA_NAME: nama untuk skema Anda.
BUCKET_NAME: bucket Cloud Storage yang Anda gunakan dengan katalog Anda.
LOCATION: lokasi BigQuery. Nilai defaultnya adalah multi-region US.

Harga

Untuk mengetahui detail harga, lihat harga BigLake.

Langkah berikutnya

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

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

Sebelum memulai

Peran yang diperlukan

Batasan

Resource katalog

Resource katalog REST Apache Iceberg

Katalog yang didukung

Detail gudang katalog

Struktur penamaan P.C.N.T

Menyiapkan 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

Iceberg 1.10 atau yang lebih baru

Mengonfigurasi dengan penyediaan kredensial

Contoh dengan penyediaan kredensial

Rilis 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 BigLake Metastore