使用 BigLake metastore Iceberg REST 目录

建议在新工作流中使用 BigLake metastore 中的 Apache Iceberg REST 目录。它为所有 Iceberg 数据提供单一可信来源，从而在查询引擎之间实现互操作性。它使 Apache Spark 等查询引擎能够以一致的方式发现、读取元数据并管理 Iceberg 表。

如果您使用开源引擎访问 Cloud Storage 中的数据，并且需要与其他引擎（包括 BigQuery）实现互操作性，那么此方法是不错的选择。它支持凭据自动售卖等功能，可实现精细的访问权限控制，还支持跨区域复制和灾难恢复。

相比之下，适用于 BigQuery 的自定义 Iceberg 目录是较早的集成。虽然现有工作流可以继续使用它，但 REST 目录可提供更标准化且功能更丰富的体验。

准备工作

在继续操作之前，请先熟悉 BigLake metastore。

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

所需的角色

如需获得在 BigLake metastore 中使用 Iceberg REST 目录所需的权限，请让管理员为您授予以下 IAM 角色：

• 执行管理任务，例如管理目录用户访问权限、存储访问权限和目录的凭证自动售卖模式：
  • 针对项目的 BigLake Admin (roles/biglake.admin) 角色
  • 针对 Cloud Storage 存储桶的 Storage Admin (roles/storage.admin)　角色
• 在凭据自动售卖模式下读取表数据： 针对项目的 BigLake Viewer (roles/biglake.viewer)　角色
• 以凭据自动售卖模式写入表数据：项目的 BigLake Editor (roles/biglake.editor) 角色
• 在非凭证自动售卖模式下读取目录资源和表数据：
  • 项目的 BigLake Viewer (roles/biglake.viewer)　角色
  • 针对 Cloud Storage 存储桶的 Storage Object Viewer (roles/storage.objectViewer)　角色
• 在非凭证自动售卖模式下管理目录资源和写入表数据：
  • 项目的 BigLake Editor (roles/biglake.editor) 角色
  • 针对 Cloud Storage 存储桶的 Storage Object User (roles/storage.objectUser) 角色

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

限制

Iceberg REST 目录存在以下限制：

• 使用凭证分发模式时，您必须将 io-impl 属性设置为 org.apache.iceberg.gcp.gcs.GCSFileIO。默认值 org.apache.iceberg.hadoop.HadoopFileIO 不受支持。
• 只有在使用 Dataproc on Compute Engine 2.3 映像版本 2.3.16 及更高版本时，Trino 才支持 BigQuery 目录联合。

目录资源

BigLake metastore 中的 Apache Iceberg REST 目录使用资源层次结构来整理数据。

Apache Iceberg REST 目录资源

下表简要介绍了 BigLake metastore 中 Apache Iceberg REST 目录使用的资源。

资源	说明
目录	顶级容器，目录可让您通过将命名空间和表拆分为不同的目录，将它们整理为逻辑组。
命名空间	用于整理目录中表的逻辑分组，其功能类似于数据库、架构或目录。
表	表包含可查询的行和列的定义。

支持的目录

配置客户端时，您需要指定仓库位置。此选择决定了目录的运作方式以及如何与其他 Google Cloud服务集成。

目录类型	说明
Cloud Storage 存储桶	目录中的所有数据都存储在单个 Cloud Storage 存储桶中；对于在多个存储分区中共享的数据，需要多个目录。
BigQuery 联合	让您可以使用 Iceberg REST 目录来管理和查询对 BigQuery 可见的表。如需了解详情，请参阅将目录联合与 BigQuery 搭配使用。

目录仓库详情

推荐

• Cloud Storage 存储桶仓库 (gs://)：这是标准方法，其中目录直接管理您指定的 Cloud Storage 存储桶中的 Iceberg 元数据和数据文件。此选项可让您直接控制数据布局，并支持凭据自动售卖，以实现精细的访问权限控制。这样一来，您就可以创建和管理适用于 Apache Iceberg 的 BigLake 表。

  重要提示： 对于使用 Cloud Storage 存储桶作为数据仓库的目录，目录名称也是目录资源的标识符。

  例如，如果您创建了一个存储桶来存储目录，并将其命名为 iceberg-bucket，则目录名称和存储桶名称均为 iceberg-bucket。稍后，当您使用 P.C.N.T 语法在 BigQuery 中查询目录时，系统会使用此值。例如：my-project.biglake-catalog-id.quickstart_namespace.quickstart_table。

旧版

• BigQuery 联合 (bq://)：此方法可让您使用 Iceberg REST 目录来管理和查询 BigQuery 可见的表，而无需创建目录资源。如需了解详情，请参阅将目录联合与 BigQuery 搭配使用。

P.C.N.T 命名结构

从 BigQuery 查询 BigLake metastore 表时，您需要使用四部分命名结构，通常称为 P.C.N.T：

• 项目：目录所属的 Google Cloud 项目 ID。
• Catalog：BigLake metastore 目录的名称。
• Namespace：Iceberg 命名空间（相当于 BigQuery 数据集）。
• Table：表的名称。

例如 my-project.biglake-catalog-id.my-namespace.my-table。

设置 Iceberg REST 目录

在 BigLake metastore 中使用 Apache Iceberg REST 目录时，请按照以下常规步骤操作：

1. 了解并选择目录数据仓库位置，可以是 Cloud Storage 或 BigQuery。
2. 如果您使用的是 Cloud Storage gs:// 数据仓库，请创建一个指向数据仓库位置的目录。
3. 将客户端应用配置为使用 Iceberg REST 目录。
4. 创建命名空间或架构来整理表。
5. 使用配置的客户端创建和查询表。

创建目录

您可以创建使用最终用户凭据或凭据贩售模式的目录。

• 借助最终用户凭据，目录会将访问它的最终用户的身份传递给 Cloud Storage 以进行授权检查。

• 凭据贩卖是一种存储访问权限委托机制，可让 BigLake Metastore 管理员直接控制 BigLake Metastore 资源的权限，从而无需目录用户直接访问 Cloud Storage 存储分区。借助此功能，BigLake 管理员可以向用户授予对特定数据文件的权限。

最终用户凭据

控制台

1. 在 Google Cloud 控制台中打开 BigLake 页面。

   前往 BigLake

2. 点击创建目录。

3. 在选择 Cloud Storage 存储桶字段中，输入要与目录搭配使用的 Cloud Storage 存储桶的名称。或者，点击浏览以选择现有存储桶或创建新存储桶。每个 Cloud Storage 存储桶只能有一个目录。

4. 对于身份验证方法，选择最终用户凭据。

5. 点击创建。

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 查询这些表时，此名称也会用作目录标识符。
• PROJECT_ID：您的 Google Cloud 项目 ID。

凭证分发模式

目录管理员可以在创建或更新目录时启用凭据自动发放功能。作为目录用户，您可以在配置 Iceberg REST 目录时指定访问权限委托，从而指示 Iceberg REST 目录返回降级后的存储凭据。

控制台

1. 在 Google Cloud 控制台中，打开 BigLake 页面。

   前往 BigLake

2. 点击 创建目录。系统会打开创建目录页面。

3. 在选择 Cloud Storage 存储桶部分，输入要与目录搭配使用的 Cloud Storage 存储桶的名称。或者，点击浏览，从现有存储分区列表中进行选择或创建新存储分区。每个 Cloud Storage 存储桶只能有一个目录。

4. 对于身份验证方法，请选择凭据自动发放模式。

5. 点击创建。

   系统会创建您的目录，并打开目录详情页面。

6. 在身份验证方法下，点击设置存储桶权限。

7. 在对话框中，点击确认。

   这会验证目录的服务账号是否具有存储桶的 Storage Object User 角色。

配置客户端应用

创建目录后，请配置客户端应用以使用该目录。这些示例展示了如何配置凭据自动售卖功能（有或没有）。

集群

如需在 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 存储桶的项目不同。如需详细了解使用 REST API 时的项目配置，请参阅系统参数。

通过凭证分发进行配置

如需使用凭据自动售卖，您必须使用处于凭据自动售卖模式的目录，并向 Iceberg REST 目录请求添加 X-Iceberg-Access-Delegation 标头，其值为 vended-credentials，方法是将以下行添加到 SparkSession build 中：

.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 及更高版本。

无服务器

向 Google Cloud Serverless for Apache Spark 提交 PySpark 批处理工作负载，并采用以下配置：

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 标头添加到值为 vended-credentials 的 Iceberg REST 目录请求中，方法是在 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

如需将 Trino 与 Iceberg REST Catalog 搭配使用，请创建包含 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。

创建集群后，连接到主虚拟机实例，然后使用 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 及更高版本
• 不支持 Dataproc on Compute Engine 3.0。

通过凭证分发进行配置

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 存储桶的项目不同。如需详细了解使用 REST API 时的项目配置，请参阅系统参数。

通过凭证分发进行配置

上述示例未使用凭据自动售卖功能。如需使用凭据分发，您必须使用凭据分发模式下的目录，并通过将以下行添加到 SparkSession 构建器中，向 Iceberg REST 目录请求添加值为 vended-credentials 的 X-Iceberg-Access-Delegation 标头：

.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', '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 存储桶的项目不同。如需详细了解使用 REST API 时的项目配置，请参阅系统参数。
• TOKEN：您的身份验证令牌，有效期为一小时，例如使用 gcloud auth application-default print-access-token 生成的令牌。

通过凭证分发进行配置

上述示例未使用凭据自动售卖功能。如需使用凭据分发，您必须使用凭据分发模式下的目录，并通过将以下行添加到 SparkSession 构建器中，向 Iceberg REST 目录请求添加值为 vended-credentials 的 X-Iceberg-Access-Delegation 标头：

.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 文档的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 存储桶数据仓库还是 BigQuery 联合查询。

• Cloud Storage 存储桶仓库：如果您为客户端配置了 gs:// 仓库路径，请使用四部分名称 (P.C.N.T) project.catalog.namespace.table 从 BigQuery 查询表。 catalog 组件是 BigLake metastore 目录资源的名称。如需了解详情，请参阅查询表。

• BigQuery 联邦：如果您使用 bq:// 仓库路径配置了客户端，则您创建的表会在 BigQuery 中显示，并且可以使用标准 BigQuery SQL 直接查询：

  SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

  替换以下内容：

  • NAMESPACE_NAME：您的命名空间名称。
  • TABLE_NAME：表格的名称。

将目录联合与 BigQuery 配合使用

您可以使用 Iceberg REST 目录接口来管理和查询 BigQuery 可见的表。BigQuery 联合目录不需要您创建目录资源；任何已启用 BigQuery API 的项目都可以使用它们。借助此功能，您可以：

• 在 BigQuery 中创建和管理外部 Iceberg 表。
• 使用 Iceberg REST 目录查询 BigQuery 中的 Apache Iceberg BigLake 表。

由于这些资源由 BigQuery 管理，因此您必须拥有适用的必需权限。联合目录不支持凭据自动售卖。

如需启用联合查询，请在使用 Iceberg REST 目录中的客户端配置示例中，使用 WAREHOUSE_PATH 字段中的 bq://projects/PROJECT_ID 仓库格式配置客户端。您还可以选择添加 BigQuery 位置，以使用 bq://projects/PROJECT_ID/locations/LOCATION 格式将未来的请求限制为单个位置。

为联合配置客户端后，您可以为联合表创建命名空间。

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 存储桶。
• 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 存储桶。
• LOCATION：BigQuery 位置。默认值为 US 多区域。

价格

如需详细了解价格，请参阅 BigLake 价格。

后续步骤

• 了解如何在 Google Cloud 控制台中管理目录。

• 了解适用于 Apache Iceberg 的 BigLake 表。