搭配使用 BigLake metastore 和 Iceberg REST 目錄

BigLake metastore 中的受管理 Apache Iceberg REST 目錄，可為所有 Iceberg 資料提供單一事實來源，在所有查詢引擎之間建立互通性。查詢引擎 (例如 Apache Spark) 可透過這個目錄，以一致的方式探索、讀取中繼資料，以及管理 Iceberg 資料表。

您透過 Iceberg REST 目錄使用的 Iceberg 資料表稱為 Apache Iceberg 專用 BigLake 資料表 (預先發布版)。這些是您從開放原始碼引擎建立，並儲存在 Cloud Storage 中的 Iceberg 資料表。開放原始碼引擎或 BigQuery 都能讀取這些資料。只有開放原始碼引擎支援寫入作業。本文將這些資料表稱為 BigLake Iceberg 資料表。

事前準備

  1. Verify that billing is enabled for your Google Cloud project.

    瞭解如何檢查專案是否已啟用計費功能。

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

  3. 選用：請管理員首次設定憑證販售。
  4. 選用：瞭解 BigLake Metastore 的運作方式，以及使用這項服務的原因。

必要的角色

如要在 BigLake 中繼資料存放區使用 Iceberg REST 目錄，請要求管理員授予下列 IAM 角色：

  • 執行管理工作，例如管理目錄使用者存取權、儲存空間存取權和目錄的憑證模式：
  • 以憑證販售模式讀取資料表資料： 專案的 BigLake 檢視者 (roles/biglake.viewer)
  • 以憑證販售模式寫入資料表資料： 專案的 BigLake 編輯者 (roles/biglake.editor)
  • 在非憑證臨時配發模式下讀取目錄資源和資料表資料：
    • 專案的「BigLake 檢視者」 (roles/biglake.viewer)
    • Storage 物件檢視者 (roles/storage.objectViewer) 在 Cloud Storage 值區上
  • 在非憑證臨時配發模式下管理目錄資源及寫入資料表資料：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

設定憑證臨時配發模式

憑證販售模式是一種儲存空間存取權委派機制，可讓 BigLake Metastore 管理員直接控管 BigLake Metastore 資源的權限，因此目錄使用者不必直接存取 Cloud Storage 值區。BigLake 管理員可藉此授予使用者特定資料檔案的權限。

目錄管理員會在 Iceberg REST 目錄用戶端啟用憑證販售功能。

目錄使用者可以指定存取權委派，指示 Iceberg REST 目錄傳回範圍縮減的儲存空間憑證。存取權委派是 Iceberg REST 目錄 API 規格的一部分。詳情請參閱「使用 Iceberg REST 目錄設定查詢引擎」。

如要初始化目錄並啟用憑證臨時配發模式，請按照下列步驟操作。

  1. 使用下列指令初始化目錄：

    curl -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/config?warehouse=gs://CLOUD_STORAGE_BUCKET_NAME

    更改下列內容：

    • PROJECT_ID：您的 Google Cloud 專案 ID。
    • CLOUD_STORAGE_BUCKET_NAME：儲存 Iceberg 資料表的 Cloud Storage 值區名稱。

    curl 指令的輸出內容如下所示。目錄前置字元值位於回應的 overrides.prefix 欄位中：

    {
  "overrides": {
    "catalog_credential_mode": "CREDENTIAL_MODE_END_USER",
    "prefix": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME"
  },
  "endpoints": [
    "GET /v1/{prefix}/namespaces",
    "POST /v1/{prefix}/namespaces",
    "GET /v1/{prefix}/namespaces/{namespace}",
    "HEAD /v1/{prefix}/namespaces/{namespace}",
    "DELETE /v1/{prefix}/namespaces/{namespace}",
    "POST /v1/{prefix}/namespaces/{namespace}/properties",
    "GET /v1/{prefix}/namespaces/{namespace}/tables",
    "POST /v1/{prefix}/namespaces/{namespace}/tables",
    "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "POST /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}"
  ]
}

  2. 啟用憑證販售模式，並擷取服務帳戶，以便使用下列指令授予權限：

    curl -X PATCH -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/PREFIX?update_mask=credential_mode -d '{"credential_mode":"CREDENTIAL_MODE_VENDED_CREDENTIALS"}'

    將 PREFIX 替換為上一個指令輸出內容中的 prefix 欄位。

    curl 指令輸出內容會包含服務帳戶，類似於下列內容：

    {
  "name": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME",
  "credential_mode": "CREDENTIAL_MODE_VENDED_CREDENTIALS",
  "biglake-service-account": "BIGLAKE_SERVICE_ACCOUNT"
}

  3. 為確保您在上一個步驟中擷取的 BigLake 服務帳戶具備使用憑證販售模式的必要權限，請管理員將儲存空間 bucket 的「Storage 物件使用者」(roles/storage.objectUser) 角色授予該帳戶。

限制

Iceberg REST 目錄有下列限制：

  • 不支援多區域值區、雙區域值區，以及採用自訂區域放置方式的值區。
  • 使用憑證臨時配發模式時，您必須將 io-impl 屬性設為 org.apache.iceberg.gcp.gcs.GCSFileIO。系統不支援預設值 org.apache.iceberg.hadoop.HadoopFileIO。

設定 Iceberg REST 目錄

叢集

如要在 Dataproc 上搭配使用 Spark 和 Iceberg REST 目錄，請先建立含有 Iceberg 元件的叢集：

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

更改下列內容：

  • CLUSTER_NAME：叢集名稱。
  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • REGION：Dataproc 叢集的區域。
  • DATAPROC_VERSION：Dataproc 映像檔版本，例如 2.2。

建立叢集後，請設定 Spark 工作階段，以使用 Iceberg REST 目錄：

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

更改下列內容：

  • CATALOG_NAME：Iceberg REST 目錄的名稱。
  • APP_NAME：Spark 工作階段的名稱。
  • CLOUD_STORAGE_BUCKET_NAME：儲存 BigLake Iceberg 資料表的 Cloud Storage bucket 名稱。
  • PROJECT_ID：使用 Iceberg REST 目錄時的計費專案，可能與擁有 Cloud Storage 值區的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。

這個範例未使用憑證臨時配發功能。如要使用憑證販售，您必須將 X-Iceberg-Access-Delegation 標頭新增至 Iceberg REST 目錄要求，並將值設為 vended-credentials，方法是在 SparkSession 建構工具中新增下列程式碼：

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

憑證臨時配發範例

以下範例會使用憑證販售功能設定查詢引擎：

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()

詳情請參閱 Iceberg 說明文件的「RESTCatalog 中的標頭」一節。

在下列版本中，Dataproc 叢集支援 Iceberg 的 Google 授權流程：

  • Dataproc on Compute Engine 2.2 映像檔版本 2.2.65 以上。
  • Dataproc on Compute Engine 2.3 映像檔版本 2.3.11 以上。

無伺服器

將 PySpark 批次工作負載提交至 Google Cloud Serverless for Apache Spark，並採用下列設定：

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"

更改下列內容：

  • PYSPARK_FILE：PySpark 應用程式檔案的 gs:// Cloud Storage 路徑。
  • PROJECT_ID：您的 Google Cloud 專案 ID。
  • REGION：Dataproc 批次工作負載的區域。
  • RUNTIME_VERSION：Serverless for Apache Spark 執行階段版本，例如 2.2。
  • CATALOG_NAME：Iceberg REST 目錄的名稱。
  • CLOUD_STORAGE_BUCKET_NAME：儲存 BigLake Iceberg 資料表的 Cloud Storage bucket 名稱。

如要使用憑證販售功能，您必須將 X-Iceberg-Access-Delegation 標頭新增至 Iceberg REST 目錄要求，並將值設為 vended-credentials，方法是在 Serverless for Apache Spark 設定中新增下列程式碼行：

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

憑證臨時配發範例

以下範例會使用憑證販售功能設定查詢引擎：

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"

詳情請參閱 Iceberg 說明文件的「RESTCatalog 中的標頭」一節。

在下列執行階段版本中，Serverless for Apache Spark 支援 Iceberg 的 Google 授權流程：

  • Serverless for Apache Spark 2.2 執行階段 2.2.60 以上版本
  • Serverless for Apache Spark 2.3 執行階段 2.3.10 以上版本

Trino

如要搭配 Iceberg REST 目錄使用 Trino，請建立含有 Trino 元件的 Dataproc 叢集，並使用 gcloud dataproc clusters create --properties 旗標設定目錄屬性。以下範例會建立名為 CATALOG_NAME 的 Trino 目錄：

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=gs://CLOUD_STORAGE_BUCKET_NAME,\
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"

更改下列內容：

  • CLUSTER_NAME：叢集名稱。
  • REGION：Dataproc 叢集區域。
  • DATAPROC_VERSION：Dataproc 映像檔版本，例如 2.2。
  • NETWORK_ID：叢集網路 ID。詳情請參閱「Dataproc 叢集網路設定」。
  • CATALOG_NAME：使用 Iceberg REST 目錄的 Trino 目錄名稱。
  • CLOUD_STORAGE_BUCKET_NAME：儲存 BigLake Iceberg 資料表的 Cloud Storage bucket 名稱。
  • PROJECT_ID：您要用於 BigLake metastore 的 Google Cloud 專案 ID。

叢集建立完成後，請使用 SSH 連線至主要 VM 執行個體，然後使用 Trino CLI，如下所示：

trino

在下列版本中，Dataproc Trino 支援 Iceberg 的 Google 授權流程：

  • Dataproc on Compute Engine 2.2 執行階段版本 2.2.65 以上版本
  • Dataproc on Compute Engine 2.3 執行階段版本 2.3.11 以上版本
  • 系統不支援 Dataproc on Compute Engine 3.0。

Iceberg 1.10 以上版本

開放原始碼 Iceberg 1.10 以上版本已內建支援 GoogleAuthManager 的 Google 授權流程。以下範例說明如何設定 Apache Spark，以使用 BigLake Metastore Iceberg REST 目錄。

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

更改下列內容：

  • CATALOG_NAME：Iceberg REST 目錄的名稱。
  • APP_NAME：Spark 工作階段的名稱。
  • CLOUD_STORAGE_BUCKET_NAME：儲存 BigLake Iceberg 資料表的 Cloud Storage bucket 名稱。
  • PROJECT_ID：使用 Iceberg REST 目錄時，系統會向這個專案收取費用，這可能與擁有 Cloud Storage 值區的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。

上述範例未使用憑證臨時配發。如要使用憑證販售，您必須將 X-Iceberg-Access-Delegation 標頭新增至 Iceberg REST 目錄要求，並將值設為 vended-credentials，方法是在 SparkSession 建構工具中新增下列程式碼：

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

憑證臨時配發範例

以下範例會使用憑證販售功能設定查詢引擎：

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()

詳情請參閱 Iceberg 說明文件的「RESTCatalog 中的標頭」一節。

先前的 Iceberg 版本

如果是 1.10 之前的開放原始碼 Iceberg 版本，您可以透過設定含有下列項目的工作階段，設定標準 OAuth 驗證：

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

更改下列內容：

  • CATALOG_NAME：Iceberg REST 目錄的名稱。
  • APP_NAME：Spark 工作階段的名稱。
  • CLOUD_STORAGE_BUCKET_NAME：儲存 BigLake Iceberg 資料表的 Cloud Storage bucket 名稱。
  • PROJECT_ID：使用 Iceberg REST 目錄時，系統會向這個專案收取費用，這可能與擁有 Cloud Storage 值區的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。
  • TOKEN：您的驗證權杖，效期為一小時，例如使用 gcloud auth application-default print-access-token 產生的權杖。

上述範例未使用憑證臨時配發。如要使用憑證販售，您必須將 X-Iceberg-Access-Delegation 標頭新增至 Iceberg REST 目錄要求，並將值設為 vended-credentials，方法是在 SparkSession 建構工具中新增下列程式碼：

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

憑證臨時配發範例

以下範例會使用憑證販售功能設定查詢引擎：

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', '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()

詳情請參閱 Iceberg 說明文件的「RESTCatalog 中的標頭」一節。

建立命名空間

Spark 

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

spark.sql("USE NAMESPACE_NAME;")

將 NAMESPACE_NAME 替換為命名空間的名稱。

Trino 

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;

USE CATALOG_NAME.SCHEMA_NAME;

更改下列內容：

  • CATALOG_NAME：使用 Iceberg REST 目錄的 Trino 目錄名稱。
  • SCHEMA_NAME：架構名稱。

建立資料表

Spark 

spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG;")

spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

更改下列內容：

  • NAMESPACE_NAME：命名空間名稱
  • TABLE_NAME：資料表名稱

Trino 

CREATE TABLE TABLE_NAME (id int, data varchar);

DESCRIBE TABLE_NAME;

將 TABLE_NAME 替換為資料表的名稱。

列出表格

Spark 

spark.sql("SHOW TABLES").show()

Trino 

SHOW TABLES;

將資料插入資料表

以下範例會在資料表中插入範例資料：

Spark 

spark.sql("INSERT INTO TABLE_NAME VALUES (1, \"first row\"), (2, \"second row\"), (3, \"third row\");")

Trino 

INSERT INTO TABLE_NAME VALUES (1, 'first row'), (2, 'second row'), (3, 'third row');

查詢資料表

以下範例會選取資料表中的所有資料：

Spark 

spark.sql("SELECT * FROM TABLE_NAME;").show()

Trino 

SELECT * FROM TABLE_NAME;

下列範例會從 BigQuery 查詢相同資料表：

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

更改下列內容：

  • CLOUD_STORAGE_BUCKET_NAME：Iceberg REST 目錄的 Cloud Storage 值區名稱。舉例來說，如果 URI 是 gs://iceberg_bucket，請使用 iceberg_bucket。

  • NAMESPACE_OR_SCHEMA_NAME：使用 Spark 時的資料表命名空間，或使用 Trino 時的資料表結構定義名稱。

  • TABLE_NAME：資料表名稱。

變更資料表結構定義

以下範例會在資料表中新增資料欄：

Spark 

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

更改下列內容：

  • NAMESPACE_NAME：命名空間名稱
  • TABLE_NAME：資料表名稱

Trino 

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

更改下列內容：

  • SCHEMA_NAME：結構定義名稱
  • TABLE_NAME：資料表名稱

刪除資料表

以下範例會從指定命名空間刪除資料表：

Spark 

spark.sql("DROP TABLE TABLE_NAME;")

Trino 

DROP TABLE TABLE_NAME;

定價

如需定價詳情，請參閱 BigLake 定價。

後續步驟