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 への切り替え時、または CDC からの切り替え時のみ）
external-data-sources-webhook-info-retrieve	現在の Webhook の状態を取得します（sync_type=webhook への切り替え時、または 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 では必須です。incremental ではアップサート時の重複排除に使用されます
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_field を変えずに incremental と full_refresh を切り替える — 次回の同期で新たに実行し直すだけです。
• sync_type: "webhook" への切り替え、またはそこからの切り替え — 同期済みデータは引き続き有効で、取り込み経路のみが変わります。sync_type の変更に合わせて、Webhook を登録または登録解除してください（以下のセクションを参照）。

既存データが無効になる「可能性があり」、再同期が必要な変更：

• incremental_field を別の列に変更する — ハイウォーターマークは古い列に基づいているため、新しい列とは一致しません。再同期しないと、2 つの列の履歴の間に更新された行が取り込まれません。
• primary_key_columns を変更する — 新しい主キー定義と照合した際に、既存の行が誤って重複排除される可能性があります。
• full_refresh から append に切り替える — 既存の行には、append が想定するバージョン履歴の形式がありません。
• append から full_refresh に切り替える — 逆の問題が発生し、過去のバージョンが重複することになります。
• cdc へ、または 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}) を呼び出し、status = 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 のトゥームストーンとアップサートキーが新しい主キー定義と一致しなくなり、行の重複または更新の取りこぼしが発生します。
3. resync を実行し、ユーザーに警告します。

sync_frequency の変更

1. partial-update：{sync_frequency: "1hour"}。
2. 再読み込みは不要です。次回のスケジュール済み同期から新しい頻度が適用されます。問題が起きていないことを確認したい場合は、手動で再読み込みすることもできます。

スキーマを 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-info-retrieve で確認）、external-data-sources-create-webhook-create({source_id}) を呼び出して登録します。
4. 再同期は不要です。スキーマの既存の一括同期済みデータはそのまま残り、次回の照合が完了すると、ウェブフックが主要な取り込み経路になります。
5. sync_frequency は設定したままにします（例：24hour）。これは、ウェブフックの配信が失敗した場合の安全策となる照合として機能します。

sync_type: "webhook" からの切り替え

1. 必須の incremental_field と incremental_field_type を指定して、partial-update：{sync_type: "incremental"}（または適切な一括同期タイプ）を実行します。
2. ソース上で sync_type: "webhook" を使用しているスキーマがほかにない場合は、external-data-sources-delete-webhook-create({source_id}) を呼び出して登録を解除します。ソース側に不要なウェブフック登録を残しても、イベントが受信後に破棄されるだけで害はありませんが、整理されていない状態になります。
3. ソース上でウェブフックを使用しているスキーマがほかにもある場合は、ウェブフックの登録を維持します。ソース上のすべてのウェブフックタイプのスキーマで共有されているためです。

ウェブフックの署名シークレットのローテーション

ソースの署名シークレット（例：Stripe の whsec_...）がローテーションされ、ペイロードの署名検証に失敗するようになりました。

1. ソースのダッシュボードから新しいシークレットを取得します。
2. external-data-sources-update-webhook-inputs-create({source_id}, {inputs: {signing_secret: "whsec_..."}})。
3. 再読み込みは不要です。次に受信するウェブフックのペイロードから、新しいシークレットで検証されます。

スキーマの一時停止

1. partial-update：{should_sync: false}。スキーマは同期を停止しますが、設定は維持されます。
2. 後で再開するには、partial-update：{should_sync: true} を実行し、すぐに同期を実行するには reload します。

重要な注意事項

• 書き込む前に読み取ってください。 必ず最初に現在の設定を取得してください。partial-update は、すでに設定されている値を指定しても警告しません。すでに設定されていると気づいていない値を変更しようとしている可能性があります。
• すべてのスキーマで利用できる sync_type が同じとは限りません。 incremental-fields-create の応答から、その時点で利用可能なものがわかります。作成時に利用可能だったものとは異なる場合があります（例：その後、チームで CDC が有効になった場合）。
• 構成が変わる場合はデータを消去してください。 同期方式を切り替えると、物理テーブルが変わることがよくあります。再同期しないと、異なる行の構造が混在し、クエリから不正な結果が返されます。
• CDC には前提条件があります。 最初に check-cdc-prerequisites-create を実行せずに、sync_type: "cdc" に切り替えないでください。同期はすぐに失敗します。
• 実行中のスキーマには手を加えないでください。 スキーマが現在実行中の場合は、完了するまで待つか、変更を適用する前に external-data-schemas-cancel を実行してください。同期中に設定を更新すると、増分同期の高水位マークに不整合が生じる可能性があります。
• 同期頻度は簡単に変更できます。 ぜひ試してみてください。一方、sync_type と incremental_field の変更にはコストがかかるため、慎重に行うよう案内してください。
• ウェブフックはスキーマ単位ではなく、ソース単位で登録されます。 同じソース上の複数のウェブフックタイプのスキーマで、1つのウェブフック登録を共有します。ほかのスキーマへのプッシュが停止しないよう、そのソースで最後に残ったウェブフックタイプのスキーマを切り替える場合にのみ、ウェブフックを削除してください。