incremental-fetch

増分取得

進捗を失わず、既存のデータを再取得しないデータパイプラインを構築します。

2つのウォーターマークパターン

前方と後方の両方の取得に対応できるよう、2つのカーソルを追跡します。

ウォーターマーク	目的	API パラメーター
newest_id	前回の実行以降の新しいデータを取得する	since_id
oldest_id	古いデータをバックフィルする	until_id

ウォーターマークが1つだけの場合、前方への取得しかできません。2つのウォーターマークを使うと、次のことが可能になります。

• 定期実行：新しいデータを取得する（newest_id 以降）
• バックフィル実行：古いデータを取得する（oldest_id まで）
• 重複も欠落も発生しません

重要：データとウォーターマークの保存

これらは、タイミングの異なる別々の操作です。

対象	保存するタイミング	理由
データレコード	各ページの取得後	耐障害性：47ページ目で中断しても、46ページ分を保持できます
ウォーターマーク	実行終了時に1回	正確性：全処理の成功後にのみ進捗を確定します

fetch page 1 → save records → fetch page 2 → save records → ... → update watermarks

ワークフローの判断ツリー

First run (no watermarks)?
├── YES → Full fetch (no since_id, no until_id)
└── NO → Backfill flag set?
    ├── YES → Backfill mode (until_id = oldest_id)
    └── NO → Update mode (since_id = newest_id)

実装チェックリスト

1. データベース：ingestion_state テーブルを作成します（patterns.md を参照）
2. 取得ループ：API の各ページを取得した直後にレコードを挿入します
3. ウォーターマークの追跡：この実行で確認した最新 ID と最古 ID を追跡します
4. ウォーターマークの更新：実行が正常に終了したときにのみ、ウォーターマークを1回保存します
5. 再試行：ジッターを加えた指数バックオフを使用します
6. レート制限：リセットまで待機するか、次回実行用に記録してスキップします

ページネーションの種類

このパターンは、ID ベースのページネーション（比較可能な数値 ID）で最も効果的です。ほかのページネーション方式では、次のように調整します。

種類	調整方法
カーソル／トークン	ID の代わりにカーソル文字列を保存します。数値としては比較できません
タイムスタンプ	last_timestamp 列を使用し、日付として比較します
オフセット／件数	ページ番号を保存し、最後に保存したページから再開します

スキーマとコード例については、references/patterns.md を参照してください。

注意点

• ウォーターマークは、全処理が正常に終了した後にのみ保存してください。 実行途中でプロセスがクラッシュした場合、未保存のウォーターマークにより、次回の実行では最初から再取得して重複排除することになります。データが失われることはありませんが、時間がかかる可能性があります。実行途中でウォーターマークを保存すると、回復できない欠落が発生します。
• 最新 ID が最大の数値 ID と一致するとは限りません。 API によっては、単調増加しない ID（時計のずれを含むスノーフレーク ID など）が返されます。数値の大小ではなく、必ず API が保証する順序で比較してください。
• バックフィルモードで newest_id を上書きしてはいけません。 バックフィル実行は履歴を過去に向かって拡張するため、更新するのは oldest_id のみにします。バックフィル中に newest_id を上書きすると、次回の前方更新実行でデータが重複して取得されます。
• レート制限のヘッダーは API によって異なります。 Twitter は x-rate-limit-reset を使用し、ほかの API は Retry-After を使用します。待機処理を実装する前に、対象 API のレスポンスヘッダーを確認してください。