BigQuery 目的地

将 Postgres 表复制到 BigQuery 进行分析。先 准备 Google Cloud 资源，然后 配置目标，最后 查询复制的数据。

🌐 Replicate Postgres tables to BigQuery for analytics. Prepare Google Cloud resources, configure the destination, then query replicated data.

源表要求 #

🌐 Source table requirements

每个源表最多需要16列的主键，并且都包含在发布中。管道会将其声明为 BigQuery 的 NOT ENFORCED 主键，以便 CDC 可以匹配更新和删除。保持源键唯一且非空。

🌐 Each source table needs a primary key of at most 16 columns, all included in the publication. Pipelines declares it as a BigQuery NOT ENFORCED primary key so CDC can match upserts and deletes. Keep source keys unique and non-null.

检查副本标识和完整更新行，尤其是包含大文本或 JSON 值的表。

🌐 Check replica identity and complete update rows, especially for tables with large text or JSON values.

准备 GCP 资源 #

🌐 Prepare GCP resources

准备这些 Google Cloud Platform (GCP) 资源：

🌐 Prepare these Google Cloud Platform (GCP) resources:

1. GCP 账号：如果你还没有，去 注册 GCP。在目标项目中，确保已启用 BigQuery API 和 BigQuery Storage API。

2. BigQuery 数据集：在你的 GCP 项目中创建一个 BigQuery 数据集

   • 使用像 supabase_replication 这样的数据集 ID
   • 选择一个靠近管道区域的数据集位置。创建后无法更改，它独立于你的Supabase项目区域。

3. GCP 服务账号密钥：创建一个具有适当权限的服务账号

   • 在目标数据集上授予 BigQuery 数据编辑者 权限
   • 在 GCP 项目上授予 BigQuery 作业用户 权限
   • 创建并下载 JSON 密钥文件

   把下载的 JSON 当作秘密。不要提交或分享它，如果暴露了，删除密钥。

如果你使用自定义 IAM 角色，请查看所需权限。

🌐 If you use a custom IAM role, see the required permissions.

将 BigQuery 配置为目标 #

🌐 Configure BigQuery as a destination

按照 设置管道 来启用管道，选择 BigQuery，并配置发布和初始同步。然后输入：

🌐 Follow Set up Pipelines to enable Pipelines, select BigQuery, and configure the publication and initial sync. Then enter:

在创建之前，可以选择调整目标设置和表分区与聚类。

🌐 Optionally adjust destination settings and table partitioning and clustering before creation.

点击 Start pipeline 验证目标。查看费用估算，然后点击 Create and start pipeline。

🌐 Click Start pipeline to validate the destination. Review the cost estimate, then click Create and start pipeline.

Supabase Pipelines 的费用和 Google Cloud 的费用是分开的。BigQuery 可能会对 Storage Write API 的摄取、存储以及用于应用 CDC 变更的计算资源收费。详见 BigQuery CDC 定价。

🌐 Supabase Pipelines charges and Google Cloud charges are separate. BigQuery can charge for Storage Write API ingestion, storage, and the compute used to apply CDC changes. See BigQuery CDC pricing.

它是怎么运作的 #

🌐 How it works

Pipelines 使用与目标兼容的名称和类型创建当前状态的 BigQuery 表，然后应用已发布的插入、更新、删除和清空操作。这些表不会保留可查询的行版本历史。清空表和重启表会替换目标数据。

🌐 Pipelines creates current-state BigQuery tables using destination-compatible names and types, then applies published inserts, updates, deletes, and truncates. These tables do not retain a history of row versions to query. Truncates and table restarts replace destination data.

查询复制的数据 #

🌐 Query replicated data

查询每个源表生成的视图。它的名字是将源模式和表名用下划线连接，如果原本有下划线就加倍：public.orders 变成 public_orders，my_schema.orders 变成 my__schema_orders。Pipelines 会在视图后面管理有版本的物理表，并在截断后更新它的目标。直接连接到某个物理表版本的查询，当该版本被移除时可能会过时或失败。

🌐 Query the generated view for each source table. Its name combines the source schema and table with an underscore, doubling any existing underscores: public.orders becomes public_orders, and my_schema.orders becomes my__schema_orders. Pipelines manages versioned physical tables behind the view and updates its target after a truncate. Queries tied directly to a physical table version can become stale or fail when that version is removed.

目的地设置 #

🌐 Destination settings

展开 高级设置 查看 BigQuery 特定选项：

🌐 Expand Advanced settings for BigQuery-specific options:

表分区和聚类 #

🌐 Table partitioning and clustering

你可以在 高级设置 > 表布局 下为单个复制的表配置 BigQuery 分区和聚类，以控制它们的物理布局，并提升查询性能和降低成本。

🌐 You can configure BigQuery partitioning and clustering for individual replicated tables under Advanced settings > Table layout to control their physical layout and improve query performance and cost.

该发布决定了哪些源分区会成为目标表。BigQuery 布局是单独配置的；Pipelines 不会复制 Postgres 的分区键或边界。

🌐 The publication determines which source partitions become destination tables. BigQuery layout is configured separately; Pipelines does not copy Postgres partition keys or bounds.

布局设置仅在创建或重新创建目标表时应用，包括表重启或源截断之后。恢复表已保存进度的管道重启不会应用新的布局设置。重新启动表的复制以应用它们，这会替换表中的数据。

🌐 Layout settings apply only when a destination table is created or recreated, including after a table restart or source truncate. A pipeline restart that resumes a table's saved progress does not apply new layout settings. Restart replication for the table to apply them, which replaces its data.

设置任一选项、两者都设置，或都不设置：

🌐 Set either option, both, or neither:

• 分区：可以按 date、timestamp 或 timestamptz 列进行分区，分区粒度可以是 hour、day、month 或 year，也可以按整数范围或导入时间分区。日期列不能使用按小时的粒度；整数范围则需要指定起始、结束和间隔。
• 聚类：按一个到四个有序、不同的重复列进行聚类。BigQuery 会验证聚类列的类型是否受支持。

请查看 BigQuery 文档，了解分区表达式和聚类列要求。

🌐 See the BigQuery documentation for partition expressions and clustering column requirements.

复制身份 #

🌐 Replica identity

选择一个支持的 Postgres 副本标识:

🌐 Choose a supported Postgres replica identity:

完成更新行和 TOAST #

🌐 Complete update rows and TOAST

BigQuery 的 upsert 操作需要完整的新行。Postgres 可以省略未改变的外部 TOAST 值；REPLICA IDENTITY FULL 提供旧行，这样 Pipelines 就能重新构建它们。

🌐 BigQuery upserts require complete new rows. Postgres can omit unchanged out-of-line TOAST values; REPLICA IDENTITY FULL supplies the old row so Pipelines can reconstruct them.

如果在部分更新行上复制失败，设置完整副本标识并重启管道。这个更改只影响新的 WAL：不兼容的保留更新仍然可能需要表重启。

🌐 If replication fails on a partial update row, set full replica identity and restart the pipeline. The change affects only new WAL: incompatible retained updates can still require a table restart.

查看表的当前副本标识：

🌐 Check a table's current replica identity:

1
select
2
  n.nspname as schema_name,
3
  c.relname as table_name,
4
  c.relreplident as replica_identity
5
from
6
  pg_class as c
7
  join pg_namespace as n on n.oid = c.relnamespace
8
where n.nspname = 'public' and c.relname = 'your_table';

replica_identity 的默认值是 d，完整时是 f，索引时是 i，什么都不选时是 n。

🌐 The replica_identity value is d for default, f for full, i for index, and n for nothing.

当表有 TOAST 列并且更新复制必须可靠时，设置完整副本标识：

🌐 Set full replica identity when a table has toasted columns and update replication must be reliable:

1
alter table public.your_table replica identity full;

REPLICA IDENTITY FULL 通过记录更新和删除的完整旧行来增加 WAL 的体积。

列名 #

🌐 Column names

流水线会把 ASCII 大写字母转换成小写，并保留其他支持的字符。例如，Name 和 name 会冲突；Ä 和 ä 则保持不同。尽量避免仅有大小写差异的 ASCII 字符。

🌐 Pipelines converts ASCII uppercase letters to lowercase and preserves other supported characters. For example, Name and name conflict; Ä and ä remain distinct. Avoid ASCII case-only differences.

BigQuery 支持灵活的列名，包括空格、Unicode 字母以及特定的标点符号。不过，它的保留前缀和不支持字符的限制仍然适用。

🌐 BigQuery supports flexible column names, including spaces, Unicode letters, and selected punctuation. Its reserved prefixes and unsupported-character restrictions still apply.

支持模式更改 #

🌐 Schema change support

管道支持：

🌐 Pipelines supports:

• 添加列：标量列可以为空，数组是重复字段
• 删除或重命名列，只要主键保持不变
• 从现有的标量列中删除 NOT NULL
• 添加、替换或移除支持的字面默认值
• 在跟踪的表上添加或移除已发布的列，只要主键保持不变，并且没有现有的数组列被新加入

新的标量列会让历史的 BigQuery 行 NULL 保持不变；新的数组列会显示为空数组。后续行的更改会提供原始值。添加列时，管道不会回填已有的行。

🌐 New scalar columns leave historical BigQuery rows NULL; new array columns expose an empty array. Later row changes supply the source value. Pipelines does not backfill existing rows when adding a column.

从发布中删除某列也会移除其目标值。再次添加它并不会恢复这些值。要包含之前排除的数组列，请选择表进行初始同步并重新启动其复制。

🌐 Removing a column from the publication also removes its destination values. Adding it again does not restore those values. To include a previously excluded array column, select the table for initial sync and restart its replication.

添加 NOT NULL 可以保持现有目标列可为空。对于类型更改、不支持的更改以及中断的架构更改，请参阅共享的 架构更改行为和恢复。

🌐 Adding NOT NULL keeps an existing destination column nullable. For type changes, unsupported changes, and interrupted schema changes, see the shared schema-change behavior and recovery.

列默认值 #

🌐 Column defaults

管道支持字面上的默认值，比如字符串、数字、日期、时间戳、JSON 值和 UUID。它会跳过那些依赖运行时间或运行位置的默认值，包括 now()、序列、random() 和生成的 UUID 函数。

🌐 Pipelines supports literal defaults such as strings, numbers, dates, timestamps, JSON values, and UUIDs. It skips defaults that depend on when or where they run, including now(), sequences, random(), and generated UUID functions.

跳过 BigQuery 的默认值不会导致 Postgres 的值丢失。Postgres 会计算默认值，而 Pipelines 会随着未来行的变化复制生成的值。Pipelines 在设置默认值之前会先添加列，所以默认值不会填充现有的 BigQuery 行 。

🌐 Skipping a BigQuery default doesn't lose values from Postgres. Postgres evaluates the default, and Pipelines replicates the resulting value with future row changes. Pipelines adds a column before setting its default, so defaults don't fill existing BigQuery rows.

发布变动 #

🌐 Publication changes

已跟踪表的列列表更改请遵循模式规则。请按照表成员资格或其他发布更改的指南操作，包括行过滤和分区行为。

🌐 Column-list changes for tracked tables follow the schema rules. Follow the guidance for table membership or other publication changes, including row filters and partition behavior.

限制 #

🌐 Limitations

• 行大小：每一行序列化后的数据必须适应存储写入 API 的20 MB 附加请求限制，包括请求元数据和编码开销。
• 列：BigQuery CDC 最多支持 2,000 个顶层列
• 架构和表名：在复制到 BigQuery 时，源架构和表名不能以 _ 开头或结尾，也不能包含 " 或 ;
• 数组：数组不能包含 NULL 元素。
• 数值和 JSON 值：BigQuery 会应用其目标数据类型限制。当数值超出支持的精度或范围时，可能会被四舍五入或拒绝；Postgres 的值不能保证保持其精确表示。
• BigQuery CDC 表：在 CDC 活跃期间，BigQuery 不支持对目标表进行诸如 UPDATE、DELETE 或 MERGE 的变更 DML，也不支持通配符表查询或搜索索引。完整列表请参见 BigQuery CDC 限制。
• 已管理对象：在删除目标表或视图之前，请先按照删除流程操作。

自定义 IAM 权限 #

🌐 Custom IAM permissions

管道需要权限来检查和管理目标表，通过存储写入 API 写入数据，并运行 BigQuery 作业。自定义 IAM 角色必须提供以下权限：

🌐 Pipelines needs permission to inspect and manage destination tables, write data through the Storage Write API, and run BigQuery jobs. A custom IAM role must provide:

• bigquery.datasets.get
• bigquery.jobs.create
• bigquery.tables.create
• bigquery.tables.delete
• bigquery.tables.get
• bigquery.tables.getData
• bigquery.tables.list
• bigquery.tables.update
• bigquery.tables.updateData

故障排除 #

🌐 Troubleshooting

使用 流水线监控 检查错误。对于更新失败，请检查 副本标识和 TOAST。对于模式失败，请查看 模式更改行为和恢复。

🌐 Use pipeline monitoring to inspect errors. For update failures, check replica identity and TOAST. For schema failures, review schema-change behavior and recovery.

额外资源 #

🌐 Additional resources

• BigQuery 文档
• BigQuery 数据变更捕获