BigQuery Metastore 联邦

Polaris 可以将目录（catalog）操作联邦（federate）到 BigQuery Metastore 目录上。这样，BigQuery Metastore 可以继续作为 Iceberg 表元数据的权威数据源（source of truth），而 Polaris 负责代理访问、策略以及多引擎连接。

构建时启用

BigQuery 工厂（factory）作为可选扩展打包，不会内置到默认的服务器构建中。在组装运行时或容器镜像时，需要将 NonRESTCatalogs Gradle 属性设置为包含 BIGQUERY（以及你需要的任何其他非 REST 后端）来引入该扩展：

./gradlew :polaris-server:assemble :polaris-server:quarkusAppPartsBuild --rerun \
  -PNonRESTCatalogs=BIGQUERY -Dquarkus.container-image.build=true

runtime/server/build.gradle.kts 仅在存在该标志时才会接入扩展，因此未使用该标志构建的二进制文件将拒绝 BigQuery 联邦请求。

功能配置

构建了支持 BigQuery 元数据存储的 Polaris 后，请在 application.properties 文件（或等效的配置机制，例如环境变量或 Kubernetes ConfigMap）中启用所需的功能标志：

# Allows BIGQUERY connection type
polaris.features."SUPPORTED_CATALOG_CONNECTION_TYPES"=["BIGQUERY"]

# Allows IMPLICIT authentication, needed for BigQuery Metastore federation
polaris.features."SUPPORTED_EXTERNAL_CATALOG_AUTHENTICATION_TYPES"=["IMPLICIT"]

# Enables the federation feature itself
polaris.features."ENABLE_CATALOG_FEDERATION"=true

对于 Kubernetes 部署，请将以下属性添加到挂载到 Polaris 容器的 ConfigMap 中（通常位于 /deployment/config/application.properties）。

运行时要求

• BigQuery API 访问： Polaris 部署必须能够通过 HTTPS 访问 BigQuery API（bigquery.googleapis.com）。
• 身份验证： BigQuery Metastore 联邦仅支持 IMPLICIT 身份验证，即 Polaris 使用在进程启动时解析的 Google 应用默认凭据（ADC）。ADC 会从 GOOGLE_APPLICATION_CREDENTIALS 环境变量、GCP 计算资源上挂载的服务账号，或开发过程中本地的 gcloud 凭据中解析获取。详情请参阅 Google 的应用默认凭据文档。请确保在启动服务器前已准备好有效的凭据。
• IAM： Polaris 使用的身份必须对目标项目中的 BigQuery 数据集具有读取权限，并对 GCS 数据仓库存储桶具有读取权限（如果 Polaris 需要提交表元数据，则需要读写权限）。

创建联邦目录

使用 Management API 创建一个连接类型为 BIGQUERY 的外部目录。以下请求注册一个目录，用于代理 GCP 项目 my-gcp-project 中的 BigQuery Metastore，并将 analytics_dataset 作为默认数据仓库：

curl -X POST https://<polaris-host>/management/v1/catalogs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "type": "EXTERNAL",
        "name": "analytics_bigquery",
        "storageConfigInfo": {
          "storageType": "GCS"
        },
        "properties": {
          "default-base-location": "gs://analytics-bucket/warehouse/"
        },
        "connectionConfigInfo": {
          "connectionType": "BIGQUERY",
          "properties": {
            "gcp.bigquery.project-id": "my-gcp-project",
            "warehouse": "analytics_dataset"
          },
          "authenticationParameters": {
            "authenticationType": "IMPLICIT"
          }
        }
      }'

connectionConfigInfo.properties 映射携带由 Iceberg 的 BigQueryProperties 消费的 BigQuery 特定配置：

• gcp.bigquery.project-id（必填）：拥有 BigQuery 数据集的 GCP 项目。
• warehouse（必填）：用作新表默认仓库的 BigQuery 数据集名称。
• gcp.bigquery.location（可选）：数据集所在的 BigQuery 位置（区域）。
• gcp.bigquery.list-all-tables（可选）：当为 true（默认值）时，listTables 会返回 BigQuery 数据集中的所有表，而不区分类型。设置为 false 可仅筛选出 BigQuery Metastore 管理的 Iceberg 表。

以下可选属性允许 Polaris 通过服务账号模拟（service account impersonation），以其他服务账号的身份发起 BigQuery 调用：

• gcp.bigquery.impersonate.service-account：目标服务账号邮箱。
• gcp.bigquery.impersonate.lifetime-seconds：被模拟凭据的有效期。
• gcp.bigquery.impersonate.scopes：被模拟凭据的 OAuth 作用域。
• gcp.bigquery.impersonate.delegates：委托服务账号链。

限制与运维注意事项

• 单一身份： 由于仅允许 IMPLICIT 认证，Polaris 无法在单个部署中混用多个 BigQuery 身份（BigQueryMetastoreFederatedCatalogFactory 会拒绝其他认证类型）。请规划部署拓扑，使 Polaris 进程身份与目标项目保持一致。
• 通用表： BigQuery 扩展仅暴露在 BigQuery Metastore 中注册的 Iceberg 表。通用表联邦尚未实现（BigQueryMetastoreFederatedCatalogFactory#createGenericCatalog 会抛出 UnsupportedOperationException）。
• 列表中的混合表类型： 默认情况下，listTables 会返回 BigQuery 数据集中的所有表，包括非 Iceberg 表。对于并非由 BigQuery Metastore 管理的 Iceberg 表的条目，loadTable 将返回 404。设置 gcp.bigquery.list-all-tables=false 可进行筛选。