ページネーション — 数えて飛ばすか、続きから取るか

What — offset が何をしているのか

?offset=10000&limit=20 は「10001件目から20件」という意味です。データベースがこれをどう処理するかを見てください。

この「数える」性質から、2つの別々の問題が生まれます。遅さとずれです。

GET /logs?offset=10000&limit=20

オフセット

先頭から数えた位置。10000 件目から、のような指定。

カーソル

最後に読んだ行を指す値。次はここより後ろ、という起点になる。

キーセットページング

並び替えに使う列の値で範囲を絞る方式。カーソル方式の実体。

タイブレーカー

並び替えの値が同じ行を一意に決めるために添える列。id を使うことが多い。

ずれは「並び順」で形が変わる

冒頭の事故は「抜ける」形でしたが、同じ仕組みから「重複」も起きます。

どちらが起きるかは、増減の向きと並びの組み合わせで決まります。 「重複するだけなら害がない」と考えるのは危険で、同じ設計が条件次第で抜ける側に回ります。

Why — なぜ offset が主流だったのか

offset は、データの都合ではなく画面の都合から来ています。

紙の本にページ番号があるように、一覧にも「1 2 3 … 42」を出したい。任意のページへ飛びたい。全部で何ページあるか知りたい。この3つを満たすには、位置を通し番号で表す必要があります。offset はそのための素直な表現でした。

問題は、データベース側に「10001件目」を直接指す手段が無いことです。数えるしかない。 SQL の OFFSET は、読み飛ばす行を1件ずつ読んでから捨てます（data/execution-plan で見た LIMIT が効かない話と同じ構造です）。

カーソルは何を変えたのか

カーソル方式は、位置を通し番号ではなく順序の値で表します。

-- offset: 先頭から数える
SELECT * FROM logs ORDER BY created_at DESC, id DESC LIMIT 20 OFFSET 10000;

-- カーソル: 最後に見た行より後ろ
SELECT * FROM logs
WHERE (created_at, id) < ('2026-09-17 10:00:00', '01H9...')
ORDER BY created_at DESC, id DESC LIMIT 20;

下の形は、索引の上でその位置に直接到達できます。数え捨てが無いので、1ページ目も1000ページ目も同じ速さです。

そして、位置が「順序の値」で表されているので、途中で行が増減しても位置の意味が変わりません。「この時刻のこの行より後ろ」は、何件追加されても同じ行を指します。ずれが消えるのは副産物ではなく、表現を変えたことの当然の帰結です。

捨てたもの

カーソル方式は万能ではありません。任意のページへ飛べません。 「42ページ目」を出すには、そこまでの順序の値が要るからです。総件数も、別に数えないと出せません。

並び順を変えたときにカーソルが無効になるのも、同じ理由です。カーソルは並び順に紐づいた値なので、並びが変われば意味を失います。

演習 — まず自分で判断する

解説を読む前に、まず自分で判断してみてください。ここで一度詰まっておくと、 次の節の判断軸が「なるほど」ではなく「そう来たか」に変わります。