Пагинация в MongoDB на 100k+ документов: keyset-курсор вместо skip
Почему лента тормозит на дальних страницах
Классическая пагинация выглядит безобидно:
db.posts.find({ status: "published" })
.sort({ createdAt: -1 })
.skip((page - 1) * 20)
.limit(20);На первой странице она быстрая. На странице 3000 серверу нужно пройти по индексу 60 000 записей, отбросить их и только потом вернуть 20. Стоимость растёт линейно с номером страницы. В aggregation-конвейере $skip работает так же: замена find на aggregate проблему не решает, и сравнение «aggregation против курсора» на самом деле сводится к сравнению offset-пагинации с keyset-пагинацией.
Есть и второй дефект: если между запросами страниц появились новые посты, записи сдвигаются, и пользователь видит дубли или пропускает элементы.
Keyset-пагинация
Идея: вместо номера страницы клиент передаёт значение сортировочного ключа последнего элемента, а запрос продолжает с этого места по индексу.
Ключ сортировки должен быть уникальным. createdAt сам по себе не уникален — у двух постов может совпасть время с точностью до миллисекунды. Поэтому сортируем по паре (createdAt, _id).
db.posts.createIndex({ status: 1, createdAt: -1, _id: -1 });Порядок полей в индексе следует правилу «равенство, сортировка, диапазон» (ESR), которое описано в документации MongoDB: сначала поля с точным совпадением (status), затем поля сортировки, затем диапазонные условия.
Реализация на Node.js
import { ObjectId, type Collection } from "mongodb";
type Cursor = { c: string; id: string }; // createdAt ISO + _id hex
const encode = (doc: { createdAt: Date; _id: ObjectId }) =>
Buffer.from(JSON.stringify({ c: doc.createdAt.toISOString(), id: doc._id.toHexString() })).toString("base64url");
const decode = (s: string): Cursor => JSON.parse(Buffer.from(s, "base64url").toString());
export async function listPosts(posts: Collection, after?: string, limit = 20) {
const filter: Record<string, unknown> = { status: "published" };
if (after) {
const { c, id } = decode(after);
const createdAt = new Date(c);
const _id = new ObjectId(id);
filter.$or = [
{ createdAt: { $lt: createdAt } },
{ createdAt, _id: { $lt: _id } },
];
}
const docs = await posts
.find(filter, { projection: { title: 1, slug: 1, createdAt: 1 } })
.sort({ createdAt: -1, _id: -1 })
.limit(limit + 1) // на один больше, чтобы узнать, есть ли следующая страница
.toArray();
const hasMore = docs.length > limit;
const page = hasMore ? docs.slice(0, limit) : docs;
return {
items: page,
nextCursor: hasMore ? encode(page[page.length - 1] as any) : null,
};
}Курсор непрозрачен для клиента: он передаёт строку обратно как есть. Обязательно валидируйте декодированное значение (корректная дата, 24-символьный hex для ObjectId), иначе мусорный курсор приведёт к исключению и ответу 500.
Проверка через explain
db.posts.find({
status: "published",
$or: [
{ createdAt: { $lt: ISODate("2026-10-01T00:00:00Z") } },
{ createdAt: ISODate("2026-10-01T00:00:00Z"), _id: { $lt: ObjectId("6710f0c2a1b2c3d4e5f60718") } }
]
}).sort({ createdAt: -1, _id: -1 }).limit(21).explain("executionStats")Смотрите на три значения в executionStats:
totalKeysExaminedиtotalDocsExaminedдолжны быть близки кnReturned, а не к десяткам тысяч;- в плане не должно быть стадии
SORT— сортировка обязана идти по индексу; winningPlanиспользует ваш составной индекс, а не только{ createdAt: -1 }.
Если с $or планировщик выбирает плохой план, можно разбить условие на два запроса или подсказать индекс через hint.
Общее количество
Интерфейсы любят «страница 5 из 4312». Точный countDocuments по фильтру на большой коллекции проходит по всем подходящим ключам индекса при каждом запросе. Варианты:
- не показывать общее число в бесконечной ленте вообще;
estimatedDocumentCount()— быстрый, но только для всей коллекции без фильтра;- кешировать счётчик и обновлять его по расписанию или при публикации.
Связка $facet с данными и счётчиком в одном aggregation выглядит элегантно, но выполняет оба тяжёлых прохода на каждом запросе.
Типовые ошибки
- Сортировка только по
createdAt: при одинаковых значениях элементы теряются на границах страниц. - Индекс
{ createdAt: -1 }безstatusв начале: фильтр по статусу делается после чтения документов. - Курсор в виде номера страницы, который всё равно превращается в
skipна сервере. - Направление сравнения не совпадает с сортировкой: при
-1нужно$lt, при1—$gt.
Когда keyset не подходит
Если пользователю нужен прыжок на произвольную страницу (таблица в админке с номерами страниц), keyset его не даёт. Для небольших коллекций, где глубина пагинации ограничена десятками страниц, skip проще и работает приемлемо. Компромисс — ограничить максимальный номер страницы и предлагать фильтры и поиск вместо глубокого листания.