使用 BigLake metastore Iceberg REST 目錄

建議您使用 BigLake metastore 中的 Apache Iceberg REST 目錄，為新工作流程使用 BigLake metastore。這個資料庫提供所有 Iceberg 資料的單一可靠資料來源，可在查詢引擎之間建立互通性。查詢引擎 (例如 Apache Spark) 可透過此目錄，以一致的方式探索、讀取中繼資料，以及管理 Iceberg 資料表。

如果您使用開放原始碼引擎存取 Cloud Storage 中的資料，且需要與其他引擎 (包括 BigQuery) 互通，這個方法就是不錯的選擇。支援精細存取權控管的憑證販售，以及跨區域複製和災難復原等功能。

相較之下，BigQuery 的自訂 Iceberg 目錄是較早的整合項目。現有工作流程仍可繼續使用，但 REST 目錄提供更標準化且功能豐富的體驗。

事前準備

繼續操作前，請先熟悉 BigLake metastore 和 Iceberg REST 目錄總覽。

確認專案已啟用計費功能 Google Cloud 。
啟用 BigLake API。
啟用 API 時所需的角色
如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。
啟用 API

必要的角色

如要取得在 BigLake metastore 中使用 Iceberg REST 目錄所需的權限，請要求管理員授予下列 IAM 角色：

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

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

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

限制

Iceberg REST 目錄有下列限制：

一般限制

使用 Dataproc on Compute Engine 2.3 映像檔版本 2.3.16 以上時，只有 BigQuery 目錄同盟支援 Trino。
使用憑證臨時配發模式時，您必須將 io-impl 屬性設為 org.apache.iceberg.gcp.gcs.GCSFileIO。系統不支援預設值 org.apache.iceberg.hadoop.HadoopFileIO。

資料限制

系統僅支援 Parquet 檔案。如要進一步瞭解 BigQuery 如何處理 Parquet 檔案，請參閱「從 Cloud Storage 載入 Parquet 資料」。

查詢限制

您無法在 BigQuery 中，建立由 REST 目錄管理的 Iceberg 資料表檢視區塊。
您無法在 BigQuery 中使用五部分名稱 ID 查詢 Iceberg 中繼資料表 (例如 .snapshots 或 .files)，但可以使用 Spark 查詢這些資料表。

設定 Iceberg REST 目錄

設定目錄前，建議先閱讀 Iceberg REST 目錄總覽，瞭解資源階層、目錄類型和命名結構。

在 BigLake Metastore 中使用 Apache Iceberg REST 目錄時，請按照下列一般步驟操作：

根據 Iceberg REST 目錄總覽，選擇目錄倉庫位置 (Cloud Storage 或 BigQuery)。
如果您使用 Cloud Storage gs:// 倉庫，請建立指向倉庫位置的目錄。
設定用戶端應用程式，以使用 Iceberg REST 目錄。
建立命名空間或結構定義，整理資料表。
使用已設定的用戶端建立及查詢資料表。

建立目錄

您可以建立使用使用者憑證或憑證販售模式的目錄。

有了使用者憑證，目錄就能將存取目錄的使用者身分傳遞至 Cloud Storage，以進行授權檢查。
憑證販售是一種儲存空間存取權委派機制，可讓 BigLake Metastore 管理員直接控管 BigLake Metastore 資源的權限，因此目錄使用者不必直接存取 Cloud Storage bucket。BigLake 管理員可藉此授予使用者特定資料檔案的權限。

使用者憑證

控制台

在 Google Cloud 控制台中開啟「BigLake」BigLake頁面。

前往 BigLake
按一下「建立目錄」。
在「選取 Cloud Storage bucket」欄位中，輸入要與目錄搭配使用的 Cloud Storage bucket 名稱。或者，按一下「瀏覽」選擇現有值區，或建立新值區。每個 Cloud Storage bucket 只能有一個目錄。
在「Authentication method」部分，選取「End-user credentials」。
點選「建立」。

gcloud

使用 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

更改下列內容：

CATALOG_NAME：目錄名稱。如果是Apache Iceberg 的受管理 BigLake 資料表，這個名稱通常會與 REST 目錄使用的 Cloud Storage 值區 ID 相符。舉例來說，如果值區是 gs://bucket-id，目錄名稱可能是 bucket-id。從 BigQuery 查詢這些資料表時，這個名稱也會做為目錄 ID。
PROJECT_ID：您的 Google Cloud 專案 ID。

憑證臨時配發模式

目錄管理員在建立或更新目錄時，會啟用憑證販售功能。身為目錄使用者，您可以在設定 Iceberg REST 目錄時指定存取權委派，指示 Iceberg REST 目錄傳回範圍縮減的儲存空間憑證。

控制台

在 Google Cloud 控制台開啟「BigLake」BigLake頁面。

前往 BigLake
按一下「建立目錄」。「建立目錄」頁面隨即開啟。
在「選取 Cloud Storage bucket」，輸入要與目錄搭配使用的 Cloud Storage bucket 名稱。或者，按一下「瀏覽」，從現有值區清單中選擇，或建立新值區。每個 Cloud Storage bucket 只能有一個目錄。
在「Authentication method」部分，選取「Credential vending mode」。
點選「建立」。

目錄建立完成後，系統會開啟「目錄詳細資料」頁面。
在「驗證方法」下方，按一下「設定 bucket 權限」。
在對話方塊中，按一下「確認」。

這會驗證目錄的服務帳戶是否具備儲存空間 bucket 的「Storage 物件使用者」角色。

設定用戶端應用程式

建立目錄後，請設定用戶端應用程式以使用該目錄。這些範例說明如何設定憑證販售功能。

叢集

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

更改下列內容：

CATALOG_NAME：Iceberg REST 目錄的名稱。
APP_NAME：Spark 工作階段名稱。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。
PROJECT_ID：使用 Iceberg REST 目錄時，系統會向這個專案收取費用，這可能與擁有 Cloud Storage bucket 的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。

使用憑證臨時配發功能設定

如要使用憑證販售功能，您必須以憑證販售模式使用目錄，並將 X-Iceberg-Access-Delegation 標頭新增至 Iceberg REST 目錄要求，方法是在 SparkSession 建構工具中新增下列程式碼行，並將值設為 vended-credentials：

.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 說明文件的「Headers in the 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=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"

更改下列內容：

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 目錄的名稱。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。

使用憑證臨時配發功能設定

如要使用憑證販售功能，您必須以憑證販售模式使用目錄，並將 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 說明文件的「Headers in the 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=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"

更改下列內容：

CLUSTER_NAME：叢集名稱。

REGION：Dataproc 叢集區域。

DATAPROC_VERSION：Dataproc 映像檔版本，例如 2.2。

NETWORK_ID：叢集網路 ID。詳情請參閱「Dataproc 叢集網路設定」。
CATALOG_NAME：使用 Iceberg REST 目錄的 Trino 目錄名稱。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。
PROJECT_ID：您要用於 BigLake metastore 的 Google Cloud 專案 ID。

建立叢集後，請連線至主要 VM 執行個體，並使用 Trino CLI：

trino --catalog=CATALOG_NAME

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

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

使用憑證臨時配發功能設定

Dataproc Trino 不支援憑證販售。

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

更改下列內容：

CATALOG_NAME：Iceberg REST 目錄的名稱。
APP_NAME：Spark 工作階段名稱。
WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。
PROJECT_ID：使用 Iceberg REST 目錄時的計費專案，可能與擁有 Cloud Storage bucket 的專案不同。如要瞭解使用 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 說明文件的「Headers in the 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', '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()

更改下列內容：

CATALOG_NAME：Iceberg REST 目錄的名稱。

APP_NAME：Spark 工作階段名稱。

WAREHOUSE_PATH：倉庫的路徑。使用 gs://CLOUD_STORAGE_BUCKET_NAME。如要使用 BigQuery 目錄聯合，請參閱「搭配使用目錄聯合與 BigQuery」。
PROJECT_ID：使用 Iceberg REST 目錄時的計費專案，可能與擁有 Cloud Storage bucket 的專案不同。如要瞭解使用 REST API 時的專案設定詳情，請參閱系統參數。
TOKEN：您的驗證權杖，效期為一小時，例如使用 gcloud auth application-default print-access-token 產生的權杖。

使用憑證臨時配發功能設定

.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}.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 說明文件的「Headers in the RESTCatalog」一節。

建立命名空間或結構定義

設定用戶端後，請建立命名空間或結構定義，整理資料表。建立命名空間或結構定義的語法會因查詢引擎而異。下列範例說明如何使用 Spark 和 Trino 建立這些檢視區塊。

Spark

Cloud Storage 倉儲

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

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

Trino

Cloud Storage 倉儲

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

更改下列內容：

CATALOG_NAME：使用 Iceberg REST 目錄的 Trino 目錄名稱。
SCHEMA_NAME：結構定義名稱。

在 BigQuery 中查詢資料表

在 BigQuery 中，透過 Iceberg REST 目錄建立資料表後，查詢方式取決於您是否使用 Cloud Storage bucket 倉庫或 BigQuery 聯合。

Cloud Storage bucket 倉庫：如果您使用 gs:// 倉庫路徑設定用戶端，請使用四部分名稱 (P.C.N.T) project.catalog.namespace.table 從 BigQuery 查詢資料表。如要進一步瞭解 P.C.N.T 結構，請參閱「Iceberg REST 目錄概念」。catalog 元件是 BigLake metastore 目錄資源的名稱。如要進一步瞭解如何查詢資料表，請參閱查詢資料表。
BigQuery 聯邦：如果您使用 bq:// 倉庫路徑設定用戶端，您建立的資料表會顯示在 BigQuery 中，且可使用標準 BigQuery SQL 直接查詢：
```
SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;
```
更改下列內容：
- NAMESPACE_NAME：命名空間名稱。
- TABLE_NAME：資料表名稱。

搭配使用目錄同盟與 BigQuery

如要瞭解目錄同盟，請參閱 Iceberg REST 目錄概念。如要啟用聯盟，請在「設定用戶端應用程式」中，使用用戶端設定範例的 WAREHOUSE_PATH 欄位，以 bq://projects/PROJECT_ID 倉庫格式設定用戶端。您也可以選擇加入 BigQuery 位置，使用 bq://projects/PROJECT_ID/locations/LOCATION 格式將日後的請求限制在單一位置。

由於這些資源是由 BigQuery 管理，您必須具備適用的必要權限。

為聯盟設定用戶端後，即可為聯盟資料表建立命名空間。

Spark

如要使用 BigQuery 目錄同盟，請加入 LOCATION 和 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;")

更改下列內容：

NAMESPACE_NAME：命名空間名稱。
BUCKET_NAME：您用於目錄的 Cloud Storage bucket。
LOCATION：BigQuery 位置。預設值為 US 多區域位置。

Trino

如要使用 BigQuery 目錄聯盟，請加入 LOCATION 和 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;

更改下列內容：

CATALOG_NAME：使用 Iceberg REST 目錄的 Trino 目錄名稱。
SCHEMA_NAME：結構定義名稱。
BUCKET_NAME：您用於目錄的 Cloud Storage bucket。
LOCATION：BigQuery 位置。預設值為 US 多區域位置。

定價

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

後續步驟

瞭解如何在 Google Cloud 控制台中管理目錄。
瞭解 Apache Iceberg 專用 BigLake 資料表。

使用 BigLake metastore Iceberg REST 目錄 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

限制

設定 Iceberg REST 目錄

建立目錄

使用者憑證

控制台

gcloud

憑證臨時配發模式

控制台

設定用戶端應用程式

叢集

使用憑證臨時配發功能設定

憑證臨時配發範例

無伺服器

使用憑證臨時配發功能設定

憑證臨時配發範例

Trino

使用憑證臨時配發功能設定

Iceberg 1.10 以上版本

使用憑證臨時配發功能設定

憑證臨時配發範例

先前的 Iceberg 版本

使用憑證臨時配發功能設定

憑證臨時配發範例

建立命名空間或結構定義

Spark

Cloud Storage 倉儲

Trino

Cloud Storage 倉儲

在 BigQuery 中查詢資料表

搭配使用目錄同盟與 BigQuery

Spark

Trino

定價

後續步驟

使用 BigLake metastore Iceberg REST 目錄