Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท CRUD and Queries

Pagination, Lean Queries and Cursors in Mongoose

Paginate Mongoose results with skip and limit, switch to efficient cursor-based (keyset) paging, count totals, and speed up reads with lean and projections.

No user wants a page with ten thousand rows, and no server wants to build it. Pagination returns data in slices. This lesson shows the two main strategies, offset pagination (skip and limit) and cursor pagination (also called keyset pagination), explains the trade-offs, and then covers lean() and cursors, which make large reads cheaper.

Offset pagination: skip and limit

The classic approach takes a page number and a page size:

JavaScript
async function listProducts({ page = 1, pageSize = 20 }) {
  const skip = (page - 1) * pageSize;

  const [items, total] = await Promise.all([
    Product.find().sort({ createdAt: -1, _id: -1 }).skip(skip).limit(pageSize).lean(),
    Product.countDocuments(),
  ]);

  return {
    items,
    page,
    pageSize,
    total,
    totalPages: Math.ceil(total / pageSize),
  };
}

Three rules make this correct:

  1. Always sort, and make the sort deterministic by adding _id as a tiebreaker. Without a stable order, rows can repeat or vanish between pages.
  2. Validate page numbers and cap the page size (Math.min(pageSize, 100)), because clients control them.
  3. Run the count in parallel with the page query when you need totals. The count can be expensive on huge collections; if you do not need exact totals, skip it or use estimatedDocumentCount().

The weakness: skip(n) makes MongoDB walk past n documents, so page 5,000 is much slower than page 1. Also, if rows are inserted or deleted while a user pages, items may be skipped or repeated.

Node.js Offset pagination math (stand-in, not Mongoose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Cursor (keyset) pagination

Instead of "skip n rows", say "give me rows after the last one I saw". The client sends the sort key of the last row, and the query filters on it:

JavaScript
async function listAfter({ cursor, limit = 20 }) {
  const filter = cursor ? { _id: { $lt: cursor } } : {};
  const items = await Product.find(filter).sort({ _id: -1 }).limit(limit + 1).lean();

  const hasMore = items.length > limit;
  if (hasMore) items.pop();

  return { items, nextCursor: hasMore ? items[items.length - 1]._id : null };
}

Fetching limit + 1 rows is a trick to learn whether another page exists without a count query. Because the filter uses an indexed field (_id, or a compound index on your sort fields), every page is equally fast, and rows inserted while paging do not cause skips or repeats. The costs: no jumping to "page 37", and the sort key must be unique or combined with _id (for a non-unique key like createdAt, filter with $or on createdAt and _id).

ObjectIds increase over time, so sorting by _id is roughly newest-first or oldest-first, an easy cursor for feeds.

Node.js Keyset pagination (stand-in, not Mongoose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Offset (skip) Cursor (keyset)
Jump to page N yes no
Cost grows with page number yes no
Stable while data changes no yes
Total count easy yes extra query
Best for admin tables, small data feeds, infinite scroll, APIs

lean(): plain objects, much lighter

A normal query turns each result into a full Mongoose document with change tracking, getters, virtuals and methods. If you only need to read the data and send it as JSON, add .lean():

JavaScript
const items = await Product.find({ inStock: true }).select('name price').lean();

Lean results are plain JavaScript objects. They are typically a few times faster to produce and use far less memory, which matters for large lists. What you give up:

  • no save(), deleteOne() or other document methods,
  • no virtuals, no getters (unless a plugin adds them), no id virtual (use _id),
  • no change tracking, and no casting of defaults on missing fields.

Rule of thumb: use lean() for read-only endpoints and reports; use normal documents when you will modify and save.

Combine lean() with select() so you also move less data over the network. The stand-in below measures the idea with a plain object versus a class instance carrying extra state, which is roughly what hydration does.

Node.js Why lean is lighter (rough stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The exact times depend on the machine, so the program prints only the comparison. The real hydration in Mongoose does more work than this sketch, so the difference is usually bigger.

Cursors for large result sets

find() loads every result into memory first. To process millions of documents (exports, migrations), stream them with a cursor:

JavaScript
const cursor = Product.find({ inStock: true }).lean().cursor();

for await (const product of cursor) {
  await sendToWarehouse(product);
}

Only one batch is in memory at a time. Use .batchSize(500) to tune how many documents the driver fetches per round trip. Remember that a cursor can time out if you process very slowly; for long jobs, page by _id with keyset pagination in chunks.

Putting it together in an API

JavaScript
app.get('/products', async (req, res) => {
  const limit = Math.min(Number(req.query.limit) || 20, 100);
  const cursor = req.query.cursor;

  if (cursor && !mongoose.isValidObjectId(cursor)) {
    return res.status(400).json({ message: 'Invalid cursor' });
  }

  const filter = cursor ? { _id: { $lt: cursor } } : {};
  const items = await Product.find(filter).sort({ _id: -1 }).limit(limit + 1).select('name price').lean();

  const hasMore = items.length > limit;
  if (hasMore) items.pop();
  res.json({ items, nextCursor: hasMore ? items.at(-1)._id : null });
});

Common mistakes

  • Paginating without a sort, so results change order between requests.
  • Sorting by a non-unique field with no _id tiebreaker.
  • Accepting any pageSize from the client.
  • Using huge skip values for deep pages.
  • Calling .lean() and then expecting virtuals or save().
  • Loading a whole collection with find() when a cursor would do.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should paginated queries always include a sort?

    Natural order is not guaranteed, so a deterministic sort (with _id as tiebreaker) keeps pages consistent.
  2. 2. What is the main advantage of cursor (keyset) pagination?

    Filtering on the last seen key uses an index, so every page is equally cheap and inserts do not shift pages.
  3. 3. What do you lose when you use lean()?

    Lean returns plain objects, so there is no save(), no virtuals and no tracking.
  4. 4. Why fetch limit + 1 rows in cursor pagination?

    If you get more than limit rows there is a next page; the extra row is discarded.

Summary

  • Offset pagination uses sort, skip and limit plus a count; it allows page jumps but slows down on deep pages.
  • Cursor pagination filters on the last seen key (_id), stays fast and stable, and suits feeds and APIs.
  • Always sort deterministically, cap page size and validate inputs.
  • lean() returns plain objects for faster, lighter read-only queries; cursors stream big result sets.

Next: Built-in validation