tuning-incremental-sync-config

调整增量同步配置

同步配置位于 ExternalDataSchema 上，可随时通过 external-data-schemas-partial-update 更改。大多数更改都不会造成破坏（会在下次同步时生效），但有些更改 （切换 sync_type、更改主键）需要谨慎处理，以免损坏已同步的数据。

何时使用此技能

• 用户想要更改已连接表的同步方式
• 诊断结果指出增量字段或主键有误
• 表的同步频率过高或过低
• 将增量同步表切换为 CDC（或反向切换）
• 另一端的源表已更改（新增列、删除列），同步配置需要跟进更新

如果用户正在设置全新的数据源，请改用 setting-up-a-data-warehouse-source——配置会在创建时确定。

可用工具

工具	用途
external-data-schemas-retrieve	查看当前的 sync_type、incremental_field、主键和 sync_frequency
external-data-schemas-incremental-fields-create	从实时源刷新候选增量字段
external-data-schemas-partial-update	应用配置更改
external-data-schemas-reload	使用新配置触发同步
external-data-schemas-resync	当更改使现有数据失效时，清除数据并从头重新导入
external-data-schemas-delete-data	删除已同步的表，同时保留架构条目
external-data-sources-check-cdc-prerequisites-create	预检 Postgres CDC（仅在切换到或切换出 CDC 时使用）
external-data-sources-webhook-info-retrieve	查看当前 webhook 状态（切换到或切换出 sync_type=webhook 时）
external-data-sources-create-webhook-create	将架构切换为 sync_type=webhook 后注册 webhook
external-data-sources-update-webhook-inputs-create	轮换 webhook 签名密钥
external-data-sources-delete-webhook-create	将架构切换出 sync_type=webhook 时注销 webhook

可调整的字段

通过部分更新端点：

字段	值	说明
sync_type	full_refresh、incremental、append、cdc、webhook	数据源必须支持目标类型 — 通过 incremental-fields 检查
incremental_field	数据源中的列名	必须出现在架构的 incremental_fields 列表中
incremental_field_type	datetime、date、timestamp、integer、numeric、objectid	必须与列的实际类型匹配
primary_key_columns	列名数组	CDC 必填。增量同步时用于 upsert 去重
cdc_table_mode	consolidated、cdc_only、both	仅在 sync_type=cdc 时有意义
sync_frequency	5min、15min、30min、1hour、6hour、12hour、24hour、7day、30day、never	表的同步频率。CDC：变更加载频率，最长为 7day
sync_time_of_day	HH:MM:SS	当 sync_frequency 为每日/每周频率时的同步时间
should_sync	true / false	暂停架构，而不将其删除

工作流

步骤 1 — 读取当前配置

始终先调用 external-data-schemas-retrieve({id})。了解当前状态可避免诸如“修复”实际上正确的 incremental_field 之类的错误。

注意：

• 当前的 sync_type、incremental_field、incremental_field_type、primary_key_columns
• 当前的 status（不要调整状态为 Running 的架构 — 先等待或取消）
• last_synced_at（以便判断下一次同步是否成功）
• 如果存在 latest_error，请留意（错误通常会明确告诉你需要更改什么）

步骤 2 — 如果要更改 sync_type 或 incremental_field，请刷新候选项

调用 external-data-schemas-incremental-fields-create({id})。尽管操作名称中有“create”，它会重新读取数据源并返回当前候选字段 — 用它确认你要设置的字段确实存在于数据源上，以及当前此表可用的同步类型。

响应：

{
  "incremental_fields": [{"field": "updated_at", "type": "datetime", ...}, ...],
  "incremental_available": true,
  "append_available": true,
  "cdc_available": true,
  "full_refresh_available": true,
  "detected_primary_keys": ["id"],
  "available_columns": [...]
}

如果目标 incremental_field 不在列表中，请告知用户 — 他们需要选择其他字段，或更改源表以添加一个字段。

步骤 3 — 应用更改

调用 external-data-schemas-partial-update({id}, {...changed fields})。

仅发送实际发生更改的字段。 部分更新意味着未指定的字段保持不变。

示例：

// Switch from full_refresh to incremental
{
  "sync_type": "incremental",
  "incremental_field": "updated_at",
  "incremental_field_type": "datetime"
}

// Change sync frequency to hourly
{"sync_frequency": "1hour"}

// Fix wrong PK on a CDC table
{"primary_key_columns": ["tenant_id", "order_id"]}

// Pause a schema
{"should_sync": false}

步骤 4 — 判断现有数据是否仍然有效

这一步很容易出错。某些配置更改会使已同步的数据失效，另一些则不会。

不会使现有数据失效的更改：

• sync_frequency、sync_time_of_day — 仅影响调度
• should_sync — 开启或关闭
• 大多数情况下的 cdc_table_mode — 下次同步会开始写入新的数据形态，但历史汇总行仍然有效
• 在 incremental 和 full_refresh 之间切换，且 incremental_field 保持不变 — 下次同步只会重新执行一次
• 切换为或切换出 sync_type: "webhook" — 已同步的数据仍然有效；只有数据摄取路径会改变。请记得在更改 sync_type 的同时注册或取消注册 webhook（见下文各节）。

可能使现有数据失效、需要重新同步的更改：

• 将 incremental_field 改为其他列 — 高水位标记来自旧列，无法匹配。若不重新同步，就会漏掉两个字段历史记录之间更新的行。
• 更改 primary_key_columns — 根据新的主键定义对现有行进行去重时，结果可能不正确。
• 从 full_refresh 切换到 append — 现有行不具备 append 所需的版本历史结构。
• 从 append 切换到 full_refresh — 问题正好相反；最终会产生重复的历史版本。
• 切换为或切换出 cdc — 表结构会发生根本变化。

当更改会使数据失效时，推荐按以下流程操作：

1. 使用新配置调用 external-data-schemas-partial-update
2. 告知用户此操作具有破坏性
3. 调用 external-data-schemas-resync，清除数据并按新配置重新导入

也可以依次执行 external-data-schemas-delete-data → 使用 should_sync: true 调用 external-data-schemas-partial-update → external-data-schemas-reload。delete-data 会关闭同步，因此更新时必须重新开启，否则重新加载后调度仍会暂停。

步骤 5 — 触发并确认

对于非破坏性更改，调用 external-data-schemas-reload({id})，立即应用新配置，而不是等待调度执行。

稍等片刻，然后调用 external-data-schemas-retrieve({id})，确认状态从 Running 变为 Completed。报告 last_synced_at 和任何新的 latest_error。

常见的特定更改

从 full_refresh 切换到 incremental

1. 调用 incremental-fields-create，确认所需字段存在且 incremental_available: true。
2. 使用 partial-update：{sync_type: "incremental", incremental_field, incremental_field_type}。
3. 无需清除数据 — 下次同步会直接切换策略。如果数据源增长很快，下次增量同步成本较低。

从 incremental 切换到 cdc（仅限 Postgres）

1. 对父级数据源运行 external-data-sources-check-cdc-prerequisites-create。仅当 valid: true 时继续。
2. 调用 incremental-fields-create，确认 cdc_available: true 并查看 detected_primary_keys。
3. 使用 partial-update：{sync_type: "cdc", primary_key_columns: [...], cdc_table_mode: "consolidated"}。
4. 需要重新同步 — CDC 表的结构不同。更新后触发 external-data-schemas-resync。告知用户此操作会清除现有数据。

架构漂移后修复已失效的增量字段

数据源移除了 updated_at 列。同步因“column does not exist”而失败。

1. 调用 incremental-fields-create，查看剩余字段。
2. 选择替代字段（若没有合适的字段，则切换到 full_refresh）。
3. 使用新字段和类型（或新的 sync_type）调用 partial-update。
4. 调用 reload 重试。

更改 CDC 表的主键

1. 使用 partial-update：{primary_key_columns: [...]}。
2. 需要重新同步 — 现有 CDC 软删除标记和 upsert 键将无法匹配新的主键定义，导致行重复或更新遗漏。
3. 调用 resync，并告知用户。

更改 sync_frequency

1. partial-update：{sync_frequency: "1hour"}。
2. 无需重新加载——下一次计划同步会采用新的频率。或者，如果用户想确认一切正常，也可以手动重新加载。

将 schema 切换为 sync_type: "webhook"

仅适用于实现了 WebhookSource 的数据源（目前为 Stripe），以及在 incremental-fields-create 中显示 supports_webhooks: true 的表。

1. 调用 incremental-fields-create，确认该表的 supports_webhooks: true。
2. partial-update：{sync_type: "webhook"}。
3. 如果该数据源尚未注册 webhook（通过 webhook-info-retrieve 检查），调用 external-data-sources-create-webhook-create({source_id}) 进行注册。
4. 无需重新同步——schema 中现有的批量同步数据会保留，下一次协调完成后，webhook 将成为主要的数据接入途径。
5. 保留已设置的 sync_frequency（例如 24hour）——它会作为安全网，在 webhook 投递遗漏时进行协调。

将 sync_type: "webhook" 切换为其他类型

1. partial-update：{sync_type: "incremental"}（或其他合适的批量同步类型），并设置必需的 incremental_field + incremental_field_type。
2. 如果该数据源上没有其他 schema仍在使用 sync_type: "webhook"，调用 external-data-sources-delete-webhook-create({source_id}) 取消注册。若在数据源端留下孤立的 webhook 注册，只会导致事件被接收后丢弃——没有危害，但会显得杂乱。
3. 如果该数据源上还有其他 schema 使用 webhook，请保留 webhook 注册——该数据源上的所有 webhook 类型 schema 共用同一个 webhook。

轮换 webhook 签名密钥

数据源的签名密钥（例如 Stripe 的 whsec_...）已轮换，因此载荷现在无法通过签名验证。

1. 从数据源的控制面板获取新密钥。
2. external-data-sources-update-webhook-inputs-create({source_id}, {inputs: {signing_secret: "whsec_..."}})。
3. 无需重新加载——下一个传入的 webhook 载荷会使用新密钥进行验证。

暂停 schema

1. partial-update：{should_sync: false}。schema 将停止同步，但仍保留配置。
2. 之后恢复时：partial-update：{should_sync: true}，然后调用 reload 立即运行。

重要说明

• 先读取，再写入。 始终先获取当前配置。即使 partial-update 设置的值与原值相同，也不会报错；但你可能即将更改一个自己没意识到已经设置的值。
• 并非每种 sync_type 都适用于每个 schema。 incremental-fields-create 的响应会告知你当前可用的选项，这些选项可能与创建时不同（例如，团队可能在此期间启用了 CDC）。
• 结构发生变化时要清空数据。 切换同步策略通常会改变物理表结构。如果不重新同步，就会混合不同结构的行，导致查询结果毫无意义。
• CDC 有前置条件。 未先运行 check-cdc-prerequisites-create，切勿切换到 sync_type: "cdc"。否则同步会立即失败。
• 不要操作正在运行的 schema。 如果 schema 当前正在运行，请等待其完成，或先调用 external-data-schemas-cancel，再应用更改。在同步过程中更新配置可能导致增量高水位标记不一致。
• 更改同步频率的成本很低。 鼓励用户在这方面进行尝试。更改 Sync_type 和 incremental_field 的成本较高，应谨慎操作。
• Webhook 在数据源层级注册，而非 schema 层级。 同一数据源上的多个 webhook 类型 schema 共用一个 webhook 注册。只有在该数据源上最后一个 webhook 类型 schema 切换到其他类型时，才删除 webhook；否则其他 schema 将无法再收到推送。