使用 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，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。
启用 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) 角色
使用 BigQuery 目录联合执行数据操纵语言 (DML) 操作：
- 项目的 BigQuery Data Editor (roles/bigquery.dataEditor) 角色
- 针对 Cloud Storage 存储桶的 Storage Admin (roles/storage.admin) 角色。如果您使用 Managed Service for Apache Spark 等查询引擎执行 DML 操作，请向您用于在该引擎中运行作业的服务账号授予这些角色。

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

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

限制

Iceberg REST 目录存在以下限制：

一般限制

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

表格限制

通过 REST 目录管理的表不支持精细访问权限控制 (FGAC)，例如行级和列级安全性。

数据限制

仅支持 Parquet 文件。如需详细了解 BigQuery 如何处理 Parquet 文件，请参阅从 Cloud Storage 加载 Parquet 数据。
Iceberg metadata.json 文件大小上限为 1MB。如需申请提高此限额，请与您的 Google 客户支持团队联系。

查询限制

无法在 BigQuery 中创建由 REST 目录管理的 Iceberg 表的视图。
无法在 BigQuery 中使用五部分名称标识符查询 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 存储分区。借助此功能，BigLake 管理员可以向用户授予对特定数据文件的权限。

最终用户凭据

控制台

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

前往 BigLake
点击创建目录。
在选择 Cloud Storage 存储桶字段中，输入要与目录搭配使用的 Cloud Storage 存储桶的名称。或者，点击浏览以选择现有存储桶或创建新存储桶。每个 Cloud Storage 存储桶只能有一个目录。
对于身份验证方法，选择最终用户凭据。
点击创建。

gcloud

使用 gcloud biglake iceberg catalogs create 命令。

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

替换以下内容：

CATALOG_NAME：目录的名称。对于 Apache Iceberg 的受管理 BigLake 表，此名称通常与用于 REST 目录的 Cloud Storage 存储桶 ID 相匹配；例如，如果您的存储桶为 gs://bucket-id，则目录名称可能为 bucket-id。从 BigQuery 查询这些表时，此名称也用作目录标识符。
PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：（可选）目录的主要区域。对于 Cloud Storage 美国或欧盟多区域存储分区，请指定 US 或 EU，以确保可以从相应的 BigQuery 区域访问目录。如需了解详情，请参阅目录地区。

凭证分发模式

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

控制台

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

前往 BigLake
点击 创建目录。系统会打开创建目录页面。
在选择 Cloud Storage 存储桶部分，输入要与目录搭配使用的 Cloud Storage 存储桶的名称。或者，点击浏览，从现有存储分区列表中选择一个存储分区或创建一个新存储分区。每个 Cloud Storage 存储桶只能有一个目录。
对于身份验证方法，请选择凭证分发模式。
点击创建。

系统会创建您的目录，并打开目录详情页面。
在身份验证方法下，点击设置存储桶权限。
在对话框中，点击确认。

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

配置客户端应用

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

集群

如需在 Managed Service for Apache Spark 上将 Spark 与 Iceberg REST Catalog 搭配使用，请先创建一个包含 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：Managed Service for Apache Spark 集群的区域。
DATAPROC_VERSION：Managed Service for Apache Spark 映像版本，例如 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 构建器中：

.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 部分中的“标头”。

在以下版本中，适用于 Apache Spark 的托管式服务集群支持 Iceberg 的 Google 授权流程：

Compute Engine 2.2 映像版本 2.2.65 及更高版本上的 Managed Service for Apache Spark。
Compute Engine 2.3 映像版本 2.3.11 及更高版本上的 Managed Service for Apache Spark。

无服务器

向 Managed Service 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：Managed Service for Apache Spark 批量工作负载的区域。
RUNTIME_VERSION：Managed Service 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 目录请求中，方法是在 Managed Service 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.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

如需了解详情，请参阅 Iceberg 文档的 RESTCatalog 部分中的“标头”。

Managed Service for Apache Spark 在以下运行时版本中支持 Iceberg 的 Google 授权流程：

Managed Service for Apache Spark 2.2 运行时 2.2.60 及更高版本
Managed Service for Apache Spark 2.3 运行时 2.3.10 及更高版本

Trino

如需将 Trino 与 Iceberg REST 目录搭配使用，请创建包含 Trino 组件的 Managed Service for Apache Spark 集群，并使用 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：Managed Service for Apache Spark 集群区域。
DATAPROC_VERSION：Managed Service for Apache Spark 映像版本，例如 2.2。
NETWORK_ID：集群网络 ID。如需了解详情，请参阅 Managed Service for Apache Spark 集群网络配置。
CATALOG_NAME：使用 Iceberg REST Catalog 的 Trino 目录的名称。
WAREHOUSE_PATH：数据仓库的路径。请使用 gs://CLOUD_STORAGE_BUCKET_NAME。
PROJECT_ID：要用于 BigLake metastore 的 Google Cloud 项目 ID。

创建集群后，连接到主虚拟机实例，然后使用 Trino CLI：

trino --catalog=CATALOG_NAME

Managed Service for Apache Spark Trino 在以下版本中支持 Iceberg 的 Google 授权流程：

Compute Engine 2.2 运行时版本 2.2.65 及更高版本上的 Managed Service for Apache Spark
Compute Engine 2.3 运行时版本 2.3.11 及更高版本上的 Managed Service for Apache Spark
不支持 Compute Engine 3.0 上的 Apache Spark 托管服务。

通过凭证分发进行配置

Managed Service for Apache Spark 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 生成的令牌。

通过凭证分发进行配置

.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 Catalog 的 Trino 目录的名称。
SCHEMA_NAME：架构的名称。

在 BigQuery 中查询表

您在 BigQuery 中通过 Iceberg REST 目录创建的表的查询方式取决于您使用的是 Cloud Storage 存储桶仓库还是 BigQuery 联合查询。

Cloud Storage 存储桶仓库：如果您使用 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 存储桶。
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 Catalog 的 Trino 目录的名称。
SCHEMA_NAME：架构的名称。
BUCKET_NAME：您在目录中使用的 Cloud Storage 存储桶。
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 目录