API
Pagination: чтение SQL и кода
Суть Читайте реальный SQL, строку EXPLAIN и cursor-обработчик, предсказывайте поведение pagination и выбирайте исправление с наибольшим рычагом.
Высота — путь к senior
НольJuniorMiddleSenior
Ты на senior-высоте — в орбитеБаги пагинации живут в плане запроса и cursor-обработчике, а не в спецификации. Читайте каждый сниппет, предсказывайте, что произойдёт на глубине и при конкурентных записях, и выбирайте исправление, которое senior-инженер делает первым.
Цель
Отработайте цикл, который вы запускаете на каждом медленном или нестабильном list-эндпоинте: читаете SQL и план, предсказываете, откуда берётся стоимость или дрейф, и тянетесь к изменению, исправляющему корневую причину.
Сниппет 1 — план глубокого offset
EXPLAIN ANALYZE
SELECT id, title, created_at
FROM articles
ORDER BY created_at DESC, id DESC
LIMIT 20 OFFSET 200000;
-- Limit (rows=20) (actual rows=20 loops=1)
-- -> Index Scan ... on articles (actual rows=200020 loops=1) Викторина
Completed
План использует индекс, но всё равно занимает секунды. Что говорит 'actual rows=200020' на Index Scan и каково исправление?
Heads-up План уже показывает Index Scan. Индекс делает упорядочивание дешёвым, но не убирает чтение и отбрасывание 200000 строк, которые offset всё равно вынуждает прочитать. Keyset убирает сам пропуск.
Heads-up actual rows это измеренное число для этого прогона, а не оценка. Скан действительно выдал 200020 строк, чтобы Limit выбросил все, кроме последних 20.
Heads-up Здесь нет дорогой сортировки — порядок даёт индекс. Стоимость это чтение и отбрасывание offset-строк, на что work_mem не влияет. Исправление это keyset.
Сниппет 2 — cursor-обработчик
// GET /articles?after=<cursor>&limit=20
async function listArticles({ after, limit = 20 }) {
const { createdAt, id } = decodeCursor(after); // Base64 JSON -> {createdAt, id}
const rows = await db.query(`
SELECT id, title, created_at
FROM articles
WHERE (created_at, id) < ($1, $2)
ORDER BY created_at DESC, id DESC
LIMIT $3
`, [createdAt, id, limit]);
const last = rows[rows.length - 1];
return {
items: rows,
nextCursor: encodeCursor({ createdAt: last.created_at, id: last.id }),
hasNextPage: true,
};
} Викторина
Completed
Seek и ordering корректны, но hasNextPage неверен. В чём баг и каково стандартное исправление?
Heads-up Cursor нужен только ключ сортировки (created_at, id) для seek. title это полезная нагрузка, не часть keyset, и его добавление ничего не меняет в hasNextPage.
Heads-up Сравнение кортежа ровно верно для keyset; переход на OFFSET возвращает скан глубоких страниц и дрейф. Дефект это жёсткий hasNextPage, а не seek.
Heads-up Порядок DESC со сравнением '<' согласован для движения вперёд. Реальный баг в том, что hasNextPage всегда true вместо вывода из n+1 зонда.
Сниппет 3 — рассогласование ORDER BY
CREATE INDEX idx_articles_feed ON articles (created_at DESC, id DESC);
-- обработчик выполняет:
SELECT id, title, created_at
FROM articles
WHERE (created_at, id) < ('2026-05-01 09:00:00', 918273)
ORDER BY created_at ASC, id ASC -- внимание: ASC
LIMIT 20; Викторина
Completed
Составной индекс есть, сравнение кортежа выглядит верным, но лента показывает не те строки и задержка не плоская. Что не так?
Heads-up Литерал лишь заменяет декодированный cursor. Настоящий дефект в том, что ORDER BY ASC противоречит сравнению '<' и DESC-индексу, ломая и корректность, и плоский seek.
Heads-up Postgres поддерживает сравнение строковых значений (a, b) < (x, y) напрямую, и это идиоматичная keyset-форма. Баг в рассогласованном направлении ORDER BY.
Heads-up Порядок колонок индекса должен совпадать с ORDER BY (сначала created_at, потом id), а не с первичным ключом. Перестановка на (id, created_at) сама бы сломала seek.
Сниппет 4 — подвал с подсчётом
const [{ total }] = await db.query(`SELECT COUNT(*) AS total FROM articles`);
const items = await listArticles({ after, limit: 20 });
return { items, total }; // рендерит "Показано 1–20 из {total}" Викторина
Completed
Keyset-страница ~10 мс, но p99 запроса в секундах. Виновник это COUNT(*). Какое изменение с наибольшим рычагом?
Heads-up Кэш может смягчить, но senior-ход это спросить, нужен ли точный итог вообще. Оценка или зонд hasNextPage убирают скан целиком без кэша, который устаревает.
Heads-up Под MVCC движок всё равно обходит строки ради видимости для вашей транзакции; индекс не даёт точный счёт даром. Оценивайте или убирайте итог.
Heads-up Оконный подсчёт по всему набору это тот же полный скан, лишь вложенный в запрос страницы — стоимость он не убирает. Уберите или оцените итог.
Итог
Пагинация диагностируется в плане и обработчике: ‘actual rows’ сильно выше размера страницы это сигнатура offset scan-and-discard, и keyset заменяет пропуск seek по кортежу; cursor-обработчик обязан брать n+1, чтобы вывести hasNextPage, а не жёстко его задавать; направление ORDER BY, оператор сравнения и составной индекс должны совпадать, иначе теряются и корректность, и плоская задержка; а точный COUNT(*) на каждый запрос это полный скан под MVCC, затмевающий быструю страницу — оценивайте его или убирайте. Читайте план, чините корневую причину, затем перепроверяйте план.