将 BigQuery 和 Iceberg 数据导入 AlloyDB for PostgreSQL

本页面介绍了如何使用 AlloyDB 的 BigQuery 视图从 BigQuery 导入数据，包括原生表、BigLake 外部表和 BigQuery 中适用于 Apache Iceberg 的 BigLake 表。 Iceberg 是一种用于管理和交换数据的开放表格式。

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

准备工作

  1. 为集群请求 BigQueryViews 功能的访问权限，并等到收到启用确认后再按照本页面上的说明操作。
  2. 熟悉受支持的 BigQuery 数据类型和列映射。
  3. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  4. 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.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. 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.

    Go to project selector

  7. Verify that billing is enabled for your Google Cloud project.

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

    启用 API

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

  10. 在启用 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。

    11. 所需的角色

    如需向 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 视图功能后，为 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

    配置扩展程序

    1. 创建 扩展程序：

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

      2. 运行以下命令：

        CREATE EXTENSION bigquery_fdw;

    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 中源表的所有列或部分列。

      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：列名称必须与 BigQuery 来源中的列名称一致。
      • DATA_TYPE：列的数据类型。
      • BIGQUERY_SERVER_NAME：您创建的外部服务器的唯一标识符。
      • BIGQUERY_PROJECT_ID：BigQuery 数据集所在项目的 ID。
      • BIGQUERY_DATASET_NAME：表的 BigQuery 数据集的名称。
      • BIGQUERY_TABLE_NAME：BigQuery 表的名称。

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

    导入数据

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

    1. 确定现有数据源，或创建原生 BigQuery 表或新的 BigLake Iceberg 表（在 BigQuery 中）。

    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？。

    后续步骤