GraphQL タイムスタンプフィルタの排他比較が変更

10月 25, 2026

API UPDATE

GraphQL タイムスタンプフィルタ
排他比較（>）の挙動が変わる

API 2026-10から、秒以下の精度でレコードが正確に除外されるようになりました

この変更は GraphQL Admin APIを使いタイムスタンプの「>」フィルタで同期処理を行うアプリ開発者に影響します。2026-10 リリース以降、小数秒を含まない「>」フィルタは秒末尾（.999999）以降からの比較に変わり、同秒内のレコードが取得できなくなる可能性があります。

1何が変わったのか：Before / After 図解

2業務に活かせる具体ユースケース

課題: 注文の差分同期ジョブで、最後に取得した注文の createdAt を「>」に渡して次回取得を行っているが、同じ秒内に複数注文が作成された場合に一部がスキップされる恐れがある。
打ち手: 「>」を「>=」に変更し、同じ id のレコードはアプリ側で重複排除する。クエリ例: created_at:>='2026-09-15T12:00:02Z' + sortKey: CREATED_AT + 取得済みIDのスキップ処理。
効果: 秒内に複数レコードが生成される高頻度ショップでも注文の取りこぼしが発生しなくなる。
技術メモ: 2026-10 以降のバージョンを使用するアプリのみ対象。2026-07 以前はコード変更不要。

課題: 在庫イベントや顧客作成ログをリアルタイムに近い間隔でポーリングしている場合、旧挙動では「>」が同秒内レコードを返してしまいイベントの二重処理が起きていた。
打ち手: 2026-10 へ移行することで「>」の意味が厳密になり、正しく「次の秒以降」のみを取得できるようになる。既存コードの「>」フィルタを見直し、漏れなく取得すべきケースでは「>=」＋重複除去パターンに統一する。
効果: 冪等処理（idempotency）を担保しつつ、二重処理ロジックの複雑さを軽減できる。
技術メモ: 小数秒を明示した値（例: 12:00:02.250Z）や >= / < / <= フィルタ、日付のみ（2026-09-15）の値は今回の変更対象外。

課題: 複数ストアのデータをマルチテナントで集計するアプリが、ページネーションのカーソル代わりにタイムスタンプ「>」を使っており、境界付近のレコードが集計からこぼれる懸念がある。
打ち手: ページネーションにはカーソルベース（after: 引数）を使用し、タイムスタンプフィルタは補助的な絞り込みにのみ使う設計に変更する。
効果: タイムスタンプの精度問題に依存しない堅牢なページング処理を実現できる。
技術メモ: 公式の orders クエリなど GraphQL Admin API コネクションの query 引数が対象。REST APIへの影響は元記事に記載なし。

3技術者目線のポイント

🔖 対象APIバージョン

変更が適用されるのは 2026-10 以降。2026-07 以前のバージョンを使い続けるアプリは動作変更なし。

⚠️ 影響を受けるケース

GraphQL Admin API の query 引数で、小数秒なしのタイムスタンプを「>」フィルタに渡しているコード。例: created_at:>'2026-09-15T12:00:02Z'

✅ 変更されないフィルタ

>= / < / <= の挙動は変わらない。日付のみ（2026-09-15）や小数秒付きタイムスタンプ（12:00:02.250Z）も変更対象外。

🛠️ 推奨マイグレーション手順

① クエリ内の「>」タイムスタンプフィルタを全検索 → ② 前回レスポンスの値を渡している箇所を特定 → ③ 「>=」に変更しアプリ側で id による重複排除を追加

📋 内部精度の非公開問題

GraphQL APIが返す createdAt は秒単位だが、内部では小数秒で保持されているリソースが存在する。この非対称性が今回の修正の背景。

フィルタ	小数秒なし	小数秒あり	2026-10で変更
`>`	秒末尾(.999999)以降から比較	指定値そのままで比較	変更あり
`>=`	変更なし	変更なし	変更なし
`<`	変更なし	変更なし	変更なし
`<=`	変更なし	変更なし	変更なし
日付のみ	変更なし（そもそも対象外）	—	変更なし