Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

将 BigQuery 数据导入 AlloyDB

您可以将数据从 BigQuery 内置表、具体化视图和 BigQuery 视图，以及 BigLake 外部表（例如 Apache Iceberg 托管表）和标准外部表导入到 AlloyDB for PostgreSQL。Iceberg 是一种用于管理和交换数据的开放表格式。

通过导入数据，您无需构建和维护复杂且容易出错的数据流水线，这些流水线会将数据从 BigQuery 手动移回 AlloyDB。如需了解详情，请参阅数据同步概览。

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

准备工作

配置 bigquery_fdw.enabled 标志在 AlloyDB 实例上。
查看数据类型映射，了解在使用bigquery_fdw时 BigQuery 类型在 PostgreSQL 中的表示方式。
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 serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Enable the APIs

如需创建和连接到 AlloyDB，请启用所需的 Cloud API。

启用 API
在确认项目步骤中，点击下一步以确认您要更改的项目的名称。
在启用 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 集群上配置 bigquery_fdw 扩展程序后，为 AlloyDB 集群服务账号授予对 BigQuery 数据集的访问权限。

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

打开 gcloud CLI。如果您未安装 gcloud CLI，请安装并初始化 gcloud CLI，或使用 Cloud Shell。
运行 gcloud beta alloydb clusters describe 命令：
```
gcloud beta alloydb clusters describe CLUSTER --region=REGION
```
替换以下内容：
- CLUSTER：AlloyDB 集群 ID。
- REGION：AlloyDB 集群的位置，例如 asia-east1、us-east1。如需查看完整的区域列表，请参阅 AlloyDB 位置。
输出包含 serviceAccountEmail 字段，该字段是此集群的服务账号。您还可以在集群详细信息 页面上找到服务帐号。
授予所需权限。如需了解详情，请参阅使用 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. 按照将 psql 客户端连接到实例中的说明，使用 psql 客户端连接到 AlloyDB 实例。或者，您也可以使用 AlloyDB Studio。如需了解详情，请参阅使用 Google Cloud 控制台管理您的数据
2. 运行以下命令：
```
CREATE EXTENSION bigquery_fdw;
```
  注意：您必须在需要访问 BigQuery 数据集的所有数据库中创建此扩展程序。
创建外部服务器，以定义远程 BigQuery 数据集的连接参数。
```
CREATE SERVER BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
```
替换以下内容：
- BIGQUERY_SERVER_NAME：外部服务器的唯一标识符。在给定数据库中定义一次。您可以将 BIGQUERY_SERVER_NAME 替换为您的服务器名称。
运行 CREATE USER MAPPING 命令创建用户映射，该命令用于指定连接到外部服务器时要使用的凭证。
```
CREATE USER MAPPING FOR USERNAME SERVER BIGQUERY_SERVER_NAME ;
```
替换以下内容：
- USERNAME：数据库用户名或访问外部表的 IAM 用户。对于 IAM 用户，名称必须全部为小写并使用英文引号，因为名称包含特殊字符（例如 @ 和 .)）。
- BIGQUERY_SERVER_NAME：您创建的外部服务器的唯一标识符。
使用 CREATE FOREIGN TABLE 命令定义与您要在 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');
```
替换以下内容：
- 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 表的名称。
创建外部表后，您可以按照与查询 AlloyDB 中的任何表相同的方式查询此表。

导入数据

如需将 BigQuery 中存储的 BigQuery 数据或 BigLake Iceberg 数据导入 AlloyDB，请按照以下步骤操作：

确定现有数据源，或创建内置 BigQuery 表或新的 Iceberg 托管表。
使用 psql 运行以下命令来创建 local_table：
```
CREATE TABLE local_table AS (SELECT * from foreign_table);
```
此命令会创建 BigQuery 表到本地标准 AlloyDB 表的副本。根据您的应用工作流，您可以配置 PostgreSQL pg_cron 扩展程序，以定期刷新 AlloyDB 表。

设置定期导入数据的时间表

导入 BigQuery 数据时，bigquery_fdw 会将远程表作为外部表进行连接，以便您可以使用 CREATE TABLE ... AS (SELECT * FROM foreign_table) 将数据复制到本地 AlloyDB 存储空间。

如需让导入的表保持最新状态，您可以使用 pg_cron 扩展程序定期重新运行此查询，并按时间表刷新本地数据。

注意：此方法通过对 bigquery_fdw 执行 SQL 查询来定期重建 BigQuery 表的本地副本。如果您需要自动托管的后台数据同步，而无需手动维护定期 SQL 脚本或表替换，请改用 alloydb_sync 扩展程序。如需了解详情，请参阅将 BigQuery 数据同步到 AlloyDB。

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

配置 bigquery_fdw 扩展程序。
在 AlloyDB 实例上启用 pg_cron 扩展程序。如需了解详情，请参阅支持的数据库扩展程序。
1. 将 alloydb.enable_pg_cron 标志设置为 on。如需了解详情，请参阅 alloydb.enable_pg_cron。
2. 将 cron.database_name 标志设置为安装了 bigquery_fdw 扩展程序的数据库的名称，以及您要执行 SQL 查询以刷新数据的数据库的名称。如需了解详情，请参阅支持的数据库标志。
如需定期刷新外部表的本地副本，请在安装了 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？。

数据类型映射

使用 bigquery_fdw 定义外部表时，您需要将 BigQuery 数据类型映射到相应的 PostgreSQL 类型。

下表列出了 BigQuery 和 AlloyDB 之间的数据类型映射。

BigQuery 表数据类型	推荐的 PostgreSQL 外部表数据类型
`BOOLEAN`	`BOOLEAN`
`INTEGER (INT64)`	`BIGINT`
`FLOAT (FLOAT64)`	`DOUBLE PRECISION`
`STRING`	`VARCHAR`
`NUMERIC`	`NUMERIC(38, 9)`
`NUMERIC(P[, S])`	`NUMERIC(P, S)`
`BIGNUMERIC`	`NUMERIC(77, 38)`
`BIGNUMERIC(P[, S])`	`NUMERIC(P, S)`
`DATE`	`DATE`
`TIMESTAMP`	`TIMESTAMPTZ`
`TIME`	`TIME`
`JSON`	`JSONB`
`BYTES`	`BYTEA`
`GEOGRAPHY`	`GEOGRAPHY(POINT), ...` 如需了解详情，请参阅 PostGIS_Geography。
`DATETIME`	`TIMESTAMP`
`ARRAY`	`VECTOR(N)` `N` 是向量的维度。您必须在会话中设置 `bigquery_fdw.enable_vector_downcasting` 标志。由于 AlloyDB 中的 `VECTOR` 类型使用 `float4` 类型，因此您可能会在此转换中遇到精度损失。如需了解详情，请参阅 `pgvector` 扩展程序。