将 BigQuery 和 Iceberg 数据同步到 AlloyDB

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅 发布阶段说明。

本页面介绍了如何使用 AlloyDB for PostgreSQL 的 Lakehouse Federation 功能同步 BigQuery 原生表、具体化视图、BigQuery 视图、BigLake 外部表（例如Apache Iceberg 受管表）和标准外部表中的数据。Iceberg 是一种用于管理和交换数据的开放表格式。

本页面假定您已有 AlloyDB 集群和主实例， 并且已有 BigQuery 数据集和表。如需了解详情，请参阅 创建数据集以及创建和使用表。

准备工作

1. 确保 the bigquery_fdw.enabled 标志已配置 在 AlloyDB 实例上。
2. 熟悉受支持的 BigQuery 数据类型和列映射。
登录您的 Google Cloud 账号。如果您是 Google Cloud的新用户， 请创建账号，以便在 真实场景中评估我们产品的性能。新客户还可获享 $300 赠金，用于 运行、测试和部署工作负载。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs.

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 APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs.

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 APIs

3. 启用创建和连接到 AlloyDB for PostgreSQL 所需的 Cloud API。

   启用 API

4. 在确认项目步骤中，点击下一步以确认您要更改的项目的名称。

5. 在启用 API 步骤中，点击启用以启用以下内容：

   • AlloyDB API
   • Compute Engine API
   • Cloud Resource Manager API
   • Service Networking API
   • BigQuery Storage API

   如果您计划使用与 AlloyDB 位于同一 Google Cloud 项目中的 VPC 网络配置与 AlloyDB 的网络连接，则需要使用 Service Networking API。

   如果您计划使用位于其他 Google Cloud 项目中的 VPC 网络配置与 AlloyDB 的网络连接，则需要使用 Compute Engine API 和 Cloud Resource Manager API。

所需的角色

如需向 AlloyDB 集群服务帐号授予对 BigQuery 数据集的读取权限，您需要以下权限：

• BigQuery Data Viewer (roles/bigquery.dataViewer) 或具有 bigquery.tables.get 和 bigquery.tables.getData 权限的任何自定义角色。针对表或视图授予此角色后，可提供从表或视图中读取数据和元数据的权限。
• BigQuery Read Session User (roles/bigquery.readSessionUser) 或具有 bigquery.readsessions.create 和 bigquery.readsessions.getData 权限的任何自定义角色。提供创建和使用读取会话的功能。

为 AlloyDB 授予对 BigQuery 数据集的访问权限

在 AlloyDB 集群上启用 Lakehouse Federation 功能后，为 AlloyDB 集群服务账号授予对 BigQuery 数据集的访问权限。

如需使用 gcloud CLI，您可以安装并初始化 Google Cloud CLI，也可以使用Cloud Shell。

1. 打开 gcloud CLI。如果您未安装 gcloud CLI， 请安装并初始化 gcloud CLI，或使用 Cloud Shell。

2. 运行 gcloud beta alloydb clusters describe 命令：

   gcloud beta alloydb clusters describe CLUSTER --region=REGION

   替换以下内容：

   • CLUSTER：AlloyDB 集群 ID。
   • REGION：AlloyDB 集群的位置，例如 asia-east1、us-east1。如需查看完整的区域列表，请参阅 管理实例位置。

   输出包含 serviceAccountEmail 字段，该字段是此集群的服务账号。您还可以在集群详情 页面上找到服务帐号。

3. 授予所需权限。如需了解详情，请参阅使用 IAM 控制对资源的访问权限。

   如果集群服务帐号没有所需的权限，则针对 BigQuery 表执行查询时会显示以下错误：

   • The user does not have bigquery.readsessions.create permissions
   • Permission bigquery.tables.get denied on table
   • Permission bigquery.tables.getData denied on table
   注意：如果未提供 bigquery.readsessions.getData，则系统会返回空结果，而不会出现错误。

配置扩展程序

1. 创建 扩展程序：

   1. 按照 将 psql 客户端连接到实例中的说明，使用 psql 客户端连接到 AlloyDB 实例。 或者，您也可以使用 AlloyDB Studio。如需了解详情，请参阅使用 Google Cloud 控制台管理您的数据

   2. 运行以下命令：

      CREATE EXTENSION bigquery_fdw;
      

      注意：您必须在需要访问 BigQuery 数据集的所有数据库中创建此扩展程序。

2. 创建外部服务器以定义远程 BigQuery 数据集的连接参数。

   CREATE SERVER BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
   

   替换以下内容：

   • BIGQUERY_SERVER_NAME：外部服务器的唯一标识符。在给定的数据库中定义一次。您可以将 BIGQUERY_SERVER_NAME 替换为您的服务器名称。

3. 运行 CREATE USER MAPPING 命令创建用户映射，该命令用于指定连接到外部服务器时要使用的凭证。

   CREATE USER MAPPING FOR USERNAME SERVER BIGQUERY_SERVER_NAME ;
   

   替换以下内容：

   • USERNAME：访问外部表的数据库用户名或 IAM 用户。
   • BIGQUERY_SERVER_NAME：您创建的外部服务器的唯一标识符。

4. 使用 CREATE FOREIGN TABLE 命令定义与您要在 BigQuery 中访问的表对应的外部表。此命令可让您定义远程表的结构。外部表可以包含 BigQuery 中源表的所有列或部分列。

   注意：请确保您使用的数据类型映射到受支持的数据类型。如需了解详情，请参阅受支持的 BigQuery 数据类型和列映射。

   CREATE FOREIGN TABLE TABLENAME (
   COLUMNX_NAME DATA_TYPE,
   COLUMNX_NAME DATA_TYPE,
   ...
   ) SERVER  BIGQUERY_SERVER_NAME OPTIONS (project BIGQUERY_PROJECT_ID, dataset  BIGQUERY_DATASET_NAME, table  BIGQUERY_TABLE_NAME [, mode EXECUTION_MODE]);
   

   替换以下内容：

   • TABLENAME：本地数据库中外部表的名称。
   • COLUMNX_NAME：AlloyDB 列名称。 列名称必须与 BigQuery 源表中相应列的名称 完全匹配。X 表示可以使用多个列创建表。名称还必须与 BigQuery 列的大小写完全匹配。如果 BigQuery 列名称包含大写字母（例如 employeeID），则 AlloyDB 标识符必须用双 引号括起来（例如 "employeeID"），以保留混合大小写或大写字母。
   • DATA_TYPE：列的数据类型。
   • BIGQUERY_SERVER_NAME：您创建的外部服务器的唯一标识符。
   • BIGQUERY_PROJECT_ID：BigQuery 数据集所在项目的 ID。
   • BIGQUERY_DATASET_NAME：表的 BigQuery 数据集的名称。
   • BIGQUERY_TABLE_NAME：BigQuery 表的名称。

   • EXECUTION_MODE：可选。mode 选项支持以下设置：

     • query：使用 BigQuery API 进行复杂查询。
     • storage：使用 BigQuery Storage API 进行更快的批量读取。
     • auto：自动在模式之间进行选择。这是默认值。

     如需了解详情，请参阅 BigQuery 外部数据封装容器执行模式。

   创建外部表后，您可以按照与查询 AlloyDB 中的任何表相同的方式查询此表。

同步数据

如需将 BigQuery 数据或 BigLake Iceberg 数据同步到 AlloyDB，请按照以下步骤操作：

1. 确定现有数据源，或 创建原生 BigQuery 表或 新的 Iceberg 受管表。

2. 使用 psql 运行以下命令来创建 local_table：

   CREATE TABLE local_table AS (SELECT * from foreign_table);
   

   此命令会创建 BigQuery 表到本地原生 AlloyDB 表的副本。
   根据您的应用工作流，您可以配置 PostgreSQL pg_cron 扩展程序，以定期刷新 AlloyDB 表。

设置将数据同步到 AlloyDB 的时间表

如需设置将 BigQuery 数据或 BigLake Iceberg 数据同步到 AlloyDB 的时间表，请按照以下步骤操作：

1. 配置 bigquery_fdw 扩展程序。
2. 在 AlloyDB 实例上启用 pg_cron 扩展程序。 如需了解详情，请参阅支持的数据库扩展程序。
   1. 将 alloydb.enable_pg_cron 标志设置为 on。 如需了解详情，请参阅 alloydb.enable_pg_cron。
   2. 将 cron.database_name 标志设置为安装了 bigquery_fdw 扩展程序且要执行 SQL 查询以进行同步的数据库的名称。如需了解详情，请参阅 支持的数据库标志。

3. 如需定期刷新外部表的本地副本，请在安装了 bigquery_fdw 扩展程序的数据库中运行以下命令：

   CREATE EXTENSION pg_cron;
   SELECT cron.schedule(JOB_NAME, SCHEDULE, 'CREATE TABLE IF NOT EXISTS local_table_copy AS (SELECT * FROM foreign_table); DROP TABLE IF EXISTS local_table; ALTER TABLE local_table_copy RENAME TO local_table;');
   

   替换以下内容：

   • JOB_NAME：作业的名称。
   • SCHEDULE：作业的时间表。

   如需了解详情，请参阅 什么是 pg_cron？。

后续步骤

• 了解从 AlloyDB 访问 BigQuery 数据的 用例。
• 从 AlloyDB 访问 BigQuery 数据。
• 了解受支持的 BigQuery 数据类型和列映射。