• Оглавление
  • Зачем отказываться от OFFSET/LIMIT
  • Как работает keyset‑пагинация и зачем курсор
  • Индексы и стабильная сортировка (включая уникальный тайбрейкер)
  • Примеры SQL для PostgreSQL (вперёд/назад, с фильтрами)
  • Дизайн API и безопасные курсоры (подпись и TTL)
  • Навигация назад и произвольные страницы
  • Фильтры и сложная сортировка: created_at + id, статус, тип
  • Подсчёт количества и «есть ли следующая страница»
  • Миграция с OFFSET/LIMIT на keyset без боли
  • Частые ошибки и чек‑лист тестов
  • Метрики и бизнес‑результат: быстрее, стабильнее, дешевле

Зачем отказываться от OFFSET/LIMIT

OFFSET/LIMIT привычны: быстро добавил LIMIT 50 OFFSET 5000 — и готова «101‑я страница». Проблемы обнаруживаются под нагрузкой:

• Медленно и дорого. OFFSET заставляет базу «пропустить» N строк. Чем больше оффсет, тем больше лишней работы. Индексы мало помогают: данные часто читаются, а потом выбрасываются.
• Нестабильная выдача. Пока пользователь листает, в таблицу прилетают новые записи, часть удаляется — одни и те же элементы могут повторяться, другие пропадать. Это раздражает и ломает UX.
• Плохая предсказуемость. «Тяжёлые» страницы иногда попадают в горячие часы и подрывают SLA.

Keyset‑пагинация решает все три пункта: скорость почти не зависит от «глубины» страницы, выдача стабильна, а нагрузка на базу предсказуемая.

Как работает keyset‑пагинация и зачем курсор

Идея простая: мы не «перескакиваем» фиксированное число строк, а продолжаем чтение «с места, где остановились». Для этого используем сортировку по столбцу (или двум), а в следующем запросе добавляем условие «больше последнего значения на странице».

• Пример: сортируем по created_at, а чтобы избавиться от «ничьих» (две записи в одну секунду), добавляем тайбрейкер id. В ответе отдаём курсор — компактное закодированное «последнее seen значение».
• На следующем запросе клиент присылает курсор, сервер раскодирует его и делает WHERE (created_at, id) > (
  ,
  ) ORDER BY created_at, id LIMIT
  .

Так база делает быстрый индексный проход, а не пересчитывает тысячи строк.

Индексы и стабильная сортировка (включая уникальный тайбрейкер)

Чтобы keyset был устойчивым и быстрым, нужен:

• Стойкий порядок сортировки. Минимум два поля: само поле сортировки и уникальный тайбрейкер. Часто это (created_at, id) или (price, id).
• Подходящий составной индекс в том же порядке, что и ORDER BY. Без этого PostgreSQL будет вынужден читать много лишнего.

Пример для таблицы публичных постов:

-- Таблица
CREATE TABLE post (
  id           BIGSERIAL PRIMARY KEY,
  author_id    BIGINT       NOT NULL,
  status       TEXT         NOT NULL CHECK (status IN ('draft','published','archived')),
  created_at   TIMESTAMPTZ  NOT NULL DEFAULT now(),
  title        TEXT         NOT NULL,
  body         TEXT         NOT NULL
);

-- Индекс под пагинацию опубликованных по времени: сначала фильтр, затем сортировка+тайбрейкер
CREATE INDEX CONCURRENTLY idx_post_published_created_id
  ON post (status, created_at, id);

С таким индексом запрос WHERE status='published' AND (created_at, id) > (...) ORDER BY created_at, id LIMIT 50 работает как лёгкий скан по индексу.

Примеры SQL для PostgreSQL (вперёд/назад, с фильтрами)

Вперёд по возрастанию (первая страница)

-- Первая страница без курсора
SELECT id, title, created_at
FROM post
WHERE status = 'published'
ORDER BY created_at ASC, id ASC
LIMIT 51; -- берём на один больше, чтобы узнать has_next

Если пришло 51 — значит есть ещё. Последние значения created_at и id упаковываем в курсор next.

Следующая страница

-- last_created_at и last_id мы достали из курсора
SELECT id, title, created_at
FROM post
WHERE status = 'published'
  AND (created_at, id) > ($1::timestamptz, $2::bigint)
ORDER BY created_at ASC, id ASC
LIMIT 51;

Назад (previous): при той же сортировке

Назад делаем зеркально: меняем знак сравнения и переворачиваем результат на приложении.

-- Для «предыдущей» страницы относительно курсора
SELECT id, title, created_at
FROM post
WHERE status = 'published'
  AND (created_at, id) < ($1::timestamptz, $2::bigint)
ORDER BY created_at DESC, id DESC
LIMIT 51; -- берём 51, разворачиваем на клиенте, отдаем 50

С фильтрами

Фильтры должны идти префиксом в индексе. Если часто фильтруем по author_id и статусу, стоит такой индекс:

CREATE INDEX CONCURRENTLY idx_post_author_status_created_id
  ON post (author_id, status, created_at, id);

И запрос:

SELECT id, title, created_at
FROM post
WHERE author_id = $1
  AND status = 'published'
  AND (created_at, id) > ($2::timestamptz, $3::bigint)
ORDER BY created_at ASC, id ASC
LIMIT 51;

Дизайн API и безопасные курсоры (подпись и TTL)

Курсор — это не смещение и не номер страницы. Это компактное описания «где мы остановились». Чтобы клиент не мог подменить фильтры и нагрузить базу тяжёлыми запросами, курсор лучше подписывать.

Требования к курсору:

• Содержит: имя сортировки, направление, последние значения сортировочных полей, выбранные фильтры (или ссылку на сохранённый фильтр на сервере), TTL и сигнатуру.
• Компактен: кодируем в base64, используем короткие ключи. Защищён: HMAC‑подпись по секрету.
• Идемпотентен в разумные сроки: одинаковый курсор в течение TTL должен давать те же границы.

Пример на TypeScript (Node.js) — генерация и проверка курсора с HMAC‑подписью:

import crypto from 'crypto';

const SECRET = process.env.CURSOR_SECRET || 'change-me';

type CursorPayload = {
  v: number;             // версия формата
  s: 'created_asc';      // схема сортировки
  d: 'f' | 'b';          // направление (forward/backward)
  l: [string, number];   // last tuple: [created_at ISO, id]
  f?: Record<string, string | number | boolean>; // фильтры
  exp: number;           // unix timestamp истечения
};

function sign(data: string): string {
  return crypto.createHmac('sha256', SECRET).update(data).digest('base64url');
}

export function encodeCursor(p: CursorPayload): string {
  const json = JSON.stringify(p);
  const b64 = Buffer.from(json).toString('base64url');
  const mac = sign(b64);
  return `${b64}.${mac}`;
}

export function decodeCursor(token: string): CursorPayload {
  const [b64, mac] = token.split('.');
  if (!b64 || !mac) throw new Error('bad cursor');
  const expected = sign(b64);
  if (!crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(expected))) {
    throw new Error('bad signature');
  }
  const json = Buffer.from(b64, 'base64url').toString('utf8');
  const payload = JSON.parse(json) as CursorPayload;
  if (payload.exp < Math.floor(Date.now() / 1000)) {
    throw new Error('cursor expired');
  }
  return payload;
}

Сервер отвечает так:

{
  "items": [ /* ... */ ],
  "next": "eyJ2IjoxLCJzIjoiY3JlYXRlZF9hc2MiLCJkIjoiZiIsImwiOlsiMjAyNi0wMS0yOVQxMDozMDowMFoiLDUxMjM2XSwgImV4cCI6MTcwNjU5OTk5OX0.3bO...",
  "prev": null,
  "has_next": true
}

has_next вычисляем, выбирая на один элемент больше лимита.

Навигация назад и произвольные страницы

• Назад: держим два курсора — next и prev. Чтобы получить prev, делаем запрос «в обратную сторону» (ORDER BY DESC, сравнение <), забираем лимит+1, разворачиваем список. В prev‑курсоре кладём первую запись «обратной» страницы как новую границу.
• «Перейти на 20‑ю страницу» в keyset нетривиально: либо шагаем «по курсорам», либо используем дополнительные стратегии (например, отдельный поиск по дате). Но для лент, каталогов и отчетов «вперёд/назад» почти всегда достаточно и быстрее.

Фильтры и сложная сортировка: created_at + id, статус, тип

• Сортировка только по created_at ненадёжна: совпадения по времени неизбежны. Всегда добавляйте уникальный тайбрейкер — id.
• Фильтры (status, author_id, type) должны идти префиксом индекса. Тогда план будет «индексный скан, затем ограничение по ключсету», без лишних сортировок и bitmap‑сканов.
• Если сортируем по цене и хотим фильтровать по категории, индекс должен быть (category_id, price, id).

Проверка плана:

EXPLAIN (ANALYZE, BUFFERS)
SELECT id, title, created_at
FROM post
WHERE status = 'published'
  AND (created_at, id) > ('2026-01-29T10:30:00Z'::timestamptz, 51236)
ORDER BY created_at ASC, id ASC
LIMIT 51;

Ищем Index Only Scan/Index Scan по нужному индексу и малое количество возвращённых строк.

Подсчёт количества и «есть ли следующая страница»

• has_next: просто запрашиваем LIMIT page_size+1. Если пришло больше, отрезаем лишнее и выставляем true.
• total_count: полный COUNT(*) на больших таблицах дорог. Для «витринных» интерфейсов часто не нужен. Если нужен порядок величины — читайте оценку из статистики: reltuples из pg_class (с поправкой на селективность фильтров) или поддерживайте денормализованные счётчики по популярным разрезам.

Пример приближённой оценки для всей таблицы:

SELECT reltuples::bigint AS approx_count
FROM pg_class
WHERE relname = 'post';

Для фильтров надёжнее либо материализованные представления с обновлением по расписанию, либо отдельные счётчики.

Миграция с OFFSET/LIMIT на keyset без боли

• Этап 1. Добавьте составные индексы и фичефлаг. Сервисы продолжают работать на OFFSET/LIMIT.
• Этап 2. Для новых клиентов начните отдавать курсоры и принимать их. Старые продолжают слать page/offset — сервер на них отвечает по‑старому.
• Этап 3. Отслеживайте метрики: медиана/95‑й перцентиль задержек, количество чтений/записей на базу, доля ошибок. Переключайте по фичефлагу всё больше трафика.
• Этап 4. Когда доля старых клиентов мала — удаляйте поддержку OFFSET, оставляйте только keyset.

Частые ошибки и чек‑лист тестов

Ошибки:

• Нет уникального тайбрейкера в сортировке — дубли и пропуски при вставках.
• Индекс не соответствует WHERE/ORDER BY — получаете сортировку на стороне БД и медленный план.
• Неподписанные курсоры — можно подделать фильтры и устроить «дорогой» запрос.
• Большой TTL курсора — пользователи получают «дырки» после массовых изменений.
• Неправильная обратная пагинация — забыли инвертировать сортировку и условие сравнения.

Чек‑лист тестов:

• Вставки/удаления между запросами не вызывают дубликатов/пропусков.
• Маршруты вперёд/назад работают, prev/next согласованы.
• На любом шаге ответ детерминирован при фиксированном снапшоте данных.
• has_next корректно отражает наличие данных.
• Декодирование курсора валидирует подпись и TTL, некорректные токены отклоняются.

Метрики и бизнес‑результат: быстрее, стабильнее, дешевле

Что увидит бизнес:

• Больше конверсии в каталоге/ленте: страницы открываются быстрее, пользователи листают глубже.
• Предсказуемые ресурсы: больше нет «тяжёлых» OFFSET‑страниц на 500‑й или 1000‑й итерации, база дышит ровнее.
• Меньше денег на инфраструктуру: убираем лишнюю работу с диском и памятью, выигрываем на CPU и кэше.
• Проще SLO: хвосты задержек короче, «шпили» в пике меньше.

Мини‑пример API‑хендлера (TypeScript + pg)

import { Pool } from 'pg';
import { encodeCursor, decodeCursor } from './cursor';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function listPosts(params: {
  limit?: number;
  cursor?: string | null;
  status?: 'published' | 'draft' | 'archived';
}) {
  const client = await pool.connect();
  try {
    const limit = Math.min(Math.max(params.limit ?? 50, 1), 200);
    const status = params.status ?? 'published';

    let rows;
    let nextCursor: string | null = null;
    let prevCursor: string | null = null;

    if (!params.cursor) {
      const q = `
        SELECT id, title, created_at
        FROM post
        WHERE status = $1
        ORDER BY created_at ASC, id ASC
        LIMIT $2
      `;
      const res = await client.query(q, [status, limit + 1]);
      rows = res.rows;
    } else {
      const cur = decodeCursor(params.cursor);
      if (cur.s !== 'created_asc') throw new Error('unsupported sort');
      const [lastCreated, lastId] = cur.l;
      const q = `
        SELECT id, title, created_at
        FROM post
        WHERE status = $1 AND (created_at, id) > ($2::timestamptz, $3::bigint)
        ORDER BY created_at ASC, id ASC
        LIMIT $4
      `;
      const res = await client.query(q, [status, lastCreated, lastId, limit + 1]);
      rows = res.rows;
    }

    const hasNext = rows.length > limit;
    if (hasNext) rows = rows.slice(0, limit);

    if (rows.length > 0) {
      const last = rows[rows.length - 1];
      nextCursor = encodeCursor({
        v: 1,
        s: 'created_asc',
        d: 'f',
        l: [last.created_at.toISOString(), Number(last.id)],
        f: { status },
        exp: Math.floor(Date.now() / 1000) + 3600
      });

      const first = rows[0];
      prevCursor = encodeCursor({
        v: 1,
        s: 'created_asc',
        d: 'b',
        l: [first.created_at.toISOString(), Number(first.id)],
        f: { status },
        exp: Math.floor(Date.now() / 1000) + 3600
      });
    }

    return { items: rows, next: nextCursor, prev: prevCursor, has_next: hasNext };
  } finally {
    client.release();
  }
}

Этот пример отражает базовую схему: берём limit+1, строим next/prev курсоры, подписываем, соблюдаем TTL.

Итоги

Keyset‑пагинация — простой в реализации (пара индексов и логика курсора) и мощный по эффекту инструмент. Выдача не «скачет», база не делает лишних проходов, пользователи и бизнес получают стабильную скорость и меньшие расходы. Внедрять лучше постепенно: начать с самого горячего списка, замерить выигрыш, затем распространить на другие эндпоинты.