オフセット方式とカーソル方式のページネーション

オフセットとカーソルが実際に識別しているもの

オフセットページネーションは、コレクションに対して先頭から位置ベースで一定数の要素をスキップし、その次のスライスを返すよう要求します。カーソルページネーションは、以前返された境界を基準に処理を続行するようサービスに要求します。オフセット方式とカーソル方式のページネーションの違いで重要なのは、リクエスト間でクライアントが何を記憶しているかです。一方は「どこまで数えたか」を記憶し、もう一方は「サービスがどこから続けるよう指示したか」を記憶します。

カーソルは API の抽象化であり、キーセットページネーションはクエリの手法です。トークンにはソート値がエンコードされていたり、サーバー側の状態を参照していたり、オフセットをラップしている場合さえあります。不透明な文字列だからといって効率的なデータベースシークを意味すると決めつける前に、ドキュメント化された動作を確認してください。 不透明なページトークン契約 有用なモデルを提供します。クライアントは、その内容を解釈することなくトークンを返します。

ページサイズよりも先に順序指定が来る理由

予測可能な走査には、すべてのレコードを区別できる順序付けが必要です。非一意な値だけでソートすると、境界における同順位の問題が解決されないまま残ります。たとえば、記事のコレクションには、同じ作成タイムスタンプを持つ複数の項目が含まれる場合があります。一意の識別子は、その並び順と比較ルールがリクエスト間で一貫している限り、その同順位を解消することができます。

次のテキストを英語から日本語に翻訳してください。 ルール: 1. 翻訳されたテキストのみを出力してください — 説明や余分なコードフェンスは書かないでください。 2. Markdown/HTML の構造（見出し・リスト・リンク・表など）はそのまま正確に保ってください。 3. @@CODEBLOCK_0@@ や @@INLINECODE_0@@ のようなプレースホルダートークンは絶対に変更せず、そのままの形で翻訳しないでください（順番を変えたり、結合したり、再整形しないこと）。 4. ``` のコードフェンスを追加・削除しないでください。また、通常のテキストをコードブロックで囲まないでください。 SQL の並び替えルール 明示的な順序指定がないことに意味を持たせます。データベースは有用なデフォルトの並び順を約束しません。コレクション実行時には、完全なソート指定を記録してください。昇順から降順への変更、フィルターの変更、あるいはロケールに依存する比較の変更は、保存された継続ポイントの意味を無効にする可能性があります。

書き込み時におけるオフセットページネーションの挙動

オフセット境界は、前のレコードが挿入または削除されたときに変化する可能性があります。最初のページがアイテム D で終わる仮想的なリストを考えてみましょう。A の前に新しいアイテムが挿入されると、それ以降のレコードの位置が変わります。古いページ長をスキップするように要求すると、D が次のスライスに戻ってきてしまう可能性があります。前のアイテムを削除すると、まだ見えていないレコードがスキップされた先頭部分に移動してしまうことがあります。

これらの例は、特定の API における欠陥ではなく、位置の変化を説明しています。オフセットページネーションは、ユーザーが番号付きナビゲーションを重視する、小規模で比較的安定した管理用リストにおいては依然として有用です。 LIMIT と OFFSET のセマンティクス また、オフセットが深くなると高コストになる理由も説明してください。スキップされた行であってもサーバー側の処理が必要になるためです。ナビゲーション用の上限を設定する前に、実際のフィルター済みクエリを計測してください。

キーセットカーソルが役立つ場面と限界がある場面

キーセットページネーションは、以前の位置を数え直す代わりに、最後に観測されたソートタプルの直後から続行できます。適切なインデックスとクエリプランがあれば、これは深いオフセットと同種の「スキップ作業」を回避できます。また、境界以前への挿入によって引き起こされる位置のずれの一部も回避します。この利点はトークン形式ではなく、実装側に属するものです。

変更可能なソートキーは依然として問題となります。あるアイテムが、もともとの位置を通過した後にランキングスコアを変更した場合、未訪問領域の中へ、あるいは外へ移動してしまうことがあります。削除によって境界レコードが消えてしまう可能性もあります。正しく動作するサービスは、そのような場合に自分のトークンがどのように振る舞うかを定義しなければなりません。正確な履歴メンバーシップ集合が必要なエクスポートでは、スナップショットまたは別の明示的な一貫性境界を要求してください。

コンティニュエーション契約を消費者として読む

レスポンス契約は、コンシューマーがいつ処理を停止するかを決定します。サービスは、専用の next トークン、next リンク、または構造化されたページ情報を返す場合があります。API が明示的にその挙動を定義していない限り、短いページだけを根拠に完了したと推測してはいけません。トークンはバイト単位で、そのエンコーディングも含めて厳密に保持し、見えているレコード ID から next トークンを生成してはなりません。

The GraphQL 接続モデル レコードの境界、カーソル、ページ情報を分離します。その forward 引数と backward 引数は、カーソルナビゲーションが両方向をサポートできることを示しています。ただし、そのサポートは任意のページ番号へのジャンプが可能であることを意味しません。実際のサービスが提供する操作（トークンの有効期限やフィルター変更に関する制限を含む）に合わせてインターフェースを設計してください。

チェックポイントを進める前にレコードを永続化する

チェックポイントは、それが永続的な出力に対応している場合にのみ有用です。次のカーソルをコミット済みとマークする前に、現在のページとその出典情報を保存してください。そうしないと、その操作の途中でプロセスが停止したとき、実際には保存されていない記録を飛び越えて再開してしまう可能性があります。チェックポイントと出力の境界を、アプリケーションレベルの単一の一貫性問題として扱ってください。

実用的なレコードエンベロープには、元のクエリ、コレクションの識別子、要求されたソート順、取得時刻、レコードの識別子、および継続状態が含まれます。認証情報はそのエンベロープの外側に保持してください。トークンが期限切れになった場合は、完了済みの出力を保持し、文書化されている再開手順に従ってください。安定したレコード識別子による重複排除は、宛先を同一の観測結果が繰り返し送られることから保護できますが、一度も観測されなかったアイテムを復元することはできません。

モデルをブラウザのページネーションに適用する

ブラウザーのページネーションでは、インターフェースの裏にある実際の継続メカニズムを見つける必要があります。番号付きコントロールは、URL を変更したり、フォームを送信したり、JSON リクエストを更新したり、DOM にレコードを追加したりすることがあります。見た目が同じ「次へ」ボタンでも、別のサイトでは異なるメカニズムを表す場合があります。ページを自動化する前に、どの操作が基盤となるレコードセットを変更しているのかを特定してください。

スクレイプレスエージェントブラウザー ナビゲーションにレンダリングされたコントロールが必要な場合に、ブラウザー層を提供します。これは、オフセットベースのウェブサイトをスナップショット API に変換するものではありません。 ページネーションの獲得パターン ページ番号付きのページ、次へのリンク、スクロールをカバーします。特にブラウザがすでに収集済みのレコードを表示している場合は、元のナビゲーション状態と、移動先のチェックポイントを明確に区別して保持してください。

ページ完了とコレクション完了を分離する

完成されたページは1つのレスポンスに関する証拠であり、完成されたコレクションはトラバーサル契約に関する主張です。空のDOM領域は、読み込みが未完了であること、フィルターが変更されたこと、またはソースに実際にレコードが存在しないことを意味する場合があります。不在を終端とみなす前に、想定しているページの同一性とコレクションコンテナを検証してください。

ブラウザーでの実行では、最終的に確認されたレコード ID とともに、アクティブなフィルターとソート条件を取得します。API 実行では、記録されている終端の継続状態を保持します。ソースが合計件数を提供している場合、それが同一のスナップショットおよびフィルターに属するかどうかを判断します。変動するヘッドライン件数は有用なコンテキストですが、信頼できる継続シグナルを上書きしてはなりません。

ナビゲーションと一貫性の要件によって選択する

ユーザーが直接番号付きでアクセスする必要があり、かつコレクションがそれをサポートできる程度に有限である場合は、オフセットページネーションを選択してください。大きく変化し続けるコレクションに対して順次走査が主なワークロードである場合は、ドキュメント化されたキーセットカーソル設計を選択してください。既存のサービスを利用する場合は、好みのアーキテクチャに合わせるためにそのメカニズムに別名を付けるのではなく、その契約に適応してください。

新しい API について、レコードがソート順の位置を変更し得るかどうか、カーソルが有効期限切れになるかどうか、読み取り側に履歴的一貫性が必要かどうかを書き出してください。ブラウジング用インターフェースと会計用エクスポートでは、異なるエンドポイントが必要になる場合があります。したがって、オフセット方式とカーソル方式のページネーションは、クエリ上の判断であると同時にプロダクト上の判断でもあります。正しい答えは、あなたが約束するユーザー操作に依存します。

スケーリングする前にトラバーサルを検証する

走査テストでは、成功したレスポンスだけでなく、メンバーシップと境界も検証する必要があります。重複するソート値、省略されたオプションフィールド、リクエスト間の編集を含む制御されたデータセットを使用してください。収集された識別子を、意図されたセットと比較します。出力書き込み後に再起動を含めて、チェックポイント動作が単に説明されるだけでなく、実際に行使されるようにします。

異なる深さにおけるページレイテンシ、出力の重複、欠落しているアイデンティティ、およびチェックポイントのストレージコストを測定してください。仮想的な例と本番環境での測定は分けて扱ってください。ブラウザ取得が設計の一部である場合は、相談してください。 エージェント ブラウザー機能モデル および関連する使用状況を比較します スクレイプレスの料金より多くの作業員を投入しても、あいまいな指示や壊れた完了ルールは修正されない。

結論

オフセットページネーションは位置への直接アクセスに適しており、カーソルページネーションはコレクションを継続して辿る用途に適しています。まず並び順を固定し、一貫性要件を定義してください。そのうえで、挿入・削除・トークン失効・中断された書き込みが収集されたレコード集合にどう影響するかをテストします。堅牢なチェックポイントと、完了を示す明確なシグナルは、ページネーションUIの見た目よりも重要です。

参考文献

• Scrapeless Agent Browser: 機能とスコープ
• Scrapeless Agent Browser 製品概要
• Webデータ取得のためのページネーションパターン