Projection, Sorting, Limiting, and Skipping

Filtering with query operators determines which documents come back. Projection, sorting, limiting, and skipping determine how those documents are shaped and ordered. Together, these four cursor modifiers let you retrieve exactly the data you need in exactly the right order — nothing more, nothing less. Sending only the fields a client needs reduces network payload and response time. Returning results in a predictable order prevents UI flickering and makes pagination reliable. Understanding these modifiers is essential for building efficient, professional API endpoints.

Projection — Selecting Fields to Return #

Sort Syntax #

Pagination Modifiers #

Basic Example #

// ── Projection ────────────────────────────────────────────────────────────

// Include projection — return ONLY these fields (+ _id by default)
await Task.find({}, { title: 1, status: 1, priority: 1 });
// Result: [{ _id: ..., title: '...', status: '...', priority: '...' }]

// Exclude projection — return everything EXCEPT these fields
await User.find({}, { password: 0, __v: 0, refreshTokens: 0 });

// Exclude _id from an include projection
await Task.find({}, { _id: 0, title: 1, status: 1 });

// Mongoose .select() — chainable shorthand
await Task.find().select('title status priority');          // include: space-separated
await User.find().select('-password -__v -refreshTokens'); // exclude: dash prefix
await Task.find().select({ title: 1, status: 1 });         // object syntax

// Nested field projection
await Task.find({}, { 'assignee.name': 1, 'assignee.email': 1, title: 1 });

// Array slice — return only first 5 tags
await Task.find({}, { title: 1, tags: { $slice: 5 } });

// ── Sorting ───────────────────────────────────────────────────────────────

// Single field sorts
await Task.find().sort({ createdAt: -1 });       // newest first
await Task.find().sort({ createdAt: 1 });        // oldest first
await Task.find().sort({ title: 1 });             // alphabetical A→Z

// Mongoose string shorthand
await Task.find().sort('-createdAt');              // newest first
await Task.find().sort('title');                   // A→Z

// Multi-field sort — sort by priority desc, then createdAt desc within same priority
await Task.find({ status: 'pending' })
    .sort({ priority: -1, createdAt: -1 });

// Custom sort order with $switch (Mongoose — requires aggregation)
// For enum field sort: high → medium → low
await Task.aggregate([
    { $match: { status: 'pending' } },
    { $addFields: {
        priorityOrder: {
            $switch: {
                branches: [
                    { case: { $eq: ['$priority', 'high'] },   then: 1 },
                    { case: { $eq: ['$priority', 'medium'] }, then: 2 },
                    { case: { $eq: ['$priority', 'low'] },    then: 3 },
                ],
                default: 4,
            },
        },
    }},
    { $sort: { priorityOrder: 1, createdAt: -1 } },
]);

// ── Limit and skip ────────────────────────────────────────────────────────

// First 10 tasks
await Task.find().limit(10);

// Page-based pagination
const page  = 3;
const limit = 10;
await Task.find()
    .sort('-createdAt')
    .skip((page - 1) * limit)   // skip 20 documents
    .limit(limit);               // return 10 documents

// Cursor-based pagination (faster for large collections)
// Instead of skip, query by last seen _id
const lastId = '64a1f2b3c8e4d5f6a7b8c9d0';  // from previous page
await Task.find({
    _id:    { $lt: new ObjectId(lastId) },    // documents before the last seen one
    userId: req.user.id,
}).sort({ _id: -1 }).limit(10);

// ── Combining all four ────────────────────────────────────────────────────
const tasks = await Task
    .find({ userId: req.user.id, status: { $ne: 'deleted' } })  // filter
    .select('title status priority dueDate createdAt')            // projection
    .sort({ priority: -1, createdAt: -1 })                       // sort
    .skip((page - 1) * limit)                                     // skip
    .limit(limit)                                                  // limit
    .lean();                                                       // plain JS objects (faster)

Mongoose .lean() — Returning Plain JavaScript Objects #

// Without .lean() — Mongoose documents (heavy objects with methods and getters)
const tasks = await Task.find({ userId });
tasks[0].save();          // Mongoose document has save(), remove(), toObject(), etc.
tasks[0] instanceof Task; // true

// With .lean() — plain JavaScript objects (much faster, lower memory)
const tasks = await Task.find({ userId }).lean();
tasks[0].save;            // undefined — plain object, no Mongoose methods
tasks[0] instanceof Task; // false

// When to use .lean():
// ✅ Read-only API responses (GET endpoints) — always use lean()
// ✅ Large result sets — significant memory savings
// ❌ When you need to call .save() on the result
// ❌ When you need virtual properties (virtuals are not included in lean())
// ❌ When using getters/setters defined in the schema

// .lean() benchmark impact:
// Without lean: ~2ms per document (creates full Mongoose document)
// With lean:    ~0.1ms per document (plain object assignment)
// For 1000 documents: 2000ms vs 100ms — 20x faster

How It Works #

Step 1 — Projection Is Applied by MongoDB Before Sending Results #

Projection is not a client-side filter — MongoDB applies it at the server level before transmitting data. If a document has 20 fields but you project only 3, MongoDB sends only those 3 fields over the network. This reduces both bandwidth and the time spent deserialising the result in Node.js. For documents with large fields (long descriptions, embedded arrays), projection can dramatically reduce response size.

Step 2 — Sort Order Determines the Cursor’s Result Set #

Sorting is applied before skip and limit. .sort().skip().limit() is the correct order: sort all matching documents by the given criteria, skip the first N, return the next M. If you apply limit before sort, you get an unpredictable subset — MongoDB may return different results on repeated calls if the sort is non-deterministic. Always sort before paginating.

Step 3 — skip() Becomes Slow on Deep Pages #

MongoDB’s skip(n) works by scanning and discarding the first n matching documents. For page 1 (skip 0) and page 2 (skip 10), this is negligible. For page 1000 (skip 9990), MongoDB scans and discards 9,990 documents on every request. This is why deep pagination is slow. Cursor-based pagination avoids skip entirely by filtering to documents after the last seen _id — query complexity stays O(1) regardless of how deep into the result set you paginate.

Step 4 — .lean() Bypasses Mongoose Document Instantiation #

By default, Mongoose wraps every returned document in a full Mongoose Document object — a heavyweight class with change tracking, validation, getters, setters, and all schema methods. For read-only GET endpoints, this overhead is unnecessary. .lean() tells Mongoose to return plain JavaScript objects directly from the MongoDB driver without wrapping. The result is faster, uses less memory, and is safe to serialise with JSON.stringify() without any special handling.

Step 5 — select(‘field -otherField’) Is Mongoose’s Projection Shorthand #

Mongoose’s .select() accepts a space-separated string of field names. Fields prefixed with - are excluded; fields without a prefix are included. You can also pass an object identical to MongoDB’s native projection syntax. The result is identical to passing a projection object to find(filter, projection) — it is simply more readable when chained.

Real-World Example: Optimised Task List Endpoint #

// GET /api/v1/tasks — fully optimised with projection + sort + pagination + lean
exports.getAll = asyncHandler(async (req, res) => {
    const {
        status, priority, q,
        page  = 1, limit  = 10,
        sort  = '-createdAt',
        fields,    // optional: client can request specific fields
    } = req.query;

    // Build filter
    const filter = { userId: req.user.id, deletedAt: { $exists: false } };
    if (status)   filter.status   = status;
    if (priority) filter.priority = priority;
    if (q)        filter.$text    = { $search: q };

    // Sanitise page/limit
    const p = Math.max(1, parseInt(page,  10));
    const l = Math.min(100, parseInt(limit, 10));

    // Build safe projection — client can request subset of default fields
    const DEFAULT_FIELDS = 'title status priority dueDate createdAt updatedAt';
    const ALLOWED_FIELDS = new Set(DEFAULT_FIELDS.split(' '));
    let projection = DEFAULT_FIELDS;

    if (fields) {
        const requested = fields.split(',').filter(f => ALLOWED_FIELDS.has(f));
        if (requested.length) projection = requested.join(' ');
    }

    // Validate sort field
    const SORT_MAP = {
        'createdAt':  '-createdAt', '-createdAt': '-createdAt',
        'title':      'title',      '-title':     '-title',
        'priority':   '-priority',  '-priority':  '-priority',
        'dueDate':    'dueDate',    '-dueDate':   '-dueDate',
    };
    const safeSort = SORT_MAP[sort] ?? '-createdAt';

    // Execute filter + projection + sort + pagination + lean in one go
    const [data, total] = await Promise.all([
        Task.find(filter)
            .select(projection)
            .sort(safeSort)
            .skip((p - 1) * l)
            .limit(l)
            .lean(),
        Task.countDocuments(filter),
    ]);

    res.set('X-Total-Count', total);
    res.json({
        success: true,
        data,
        meta: {
            total,
            page:       p,
            limit:      l,
            totalPages: Math.ceil(total / l),
            hasNextPage: p < Math.ceil(total / l),
            hasPrevPage: p > 1,
        },
    });
});

Common Mistakes #

Mistake 1 — Mixing include and exclude in the same projection #

❌ Wrong — throws MongoServerError:

await Task.find({}, { title: 1, status: 1, password: 0 });
// MongoServerError: Projection cannot have a mix of inclusion and exclusion

✅ Correct — only _id can be excluded in an inclusion projection:

await Task.find({}, { title: 1, status: 1, _id: 0 });          // valid — _id exception
await User.find({}, { password: 0, __v: 0, resetToken: 0 });   // exclusion only

Mistake 2 — Calling .sort() after .limit() — wrong results #

❌ Wrong — limits first, then sorts — returns arbitrary subset sorted:

await Task.find().limit(10).sort('-createdAt');  // sorts 10 random tasks
// Not the 10 most recent tasks!

✅ Correct — sort first, then limit:

await Task.find().sort('-createdAt').limit(10);  // 10 most recent tasks

Mistake 3 — Not using .lean() on read-only GET endpoints #

❌ Wrong — creates heavy Mongoose document objects unnecessarily:

const tasks = await Task.find({ userId }).limit(100);
// 100 full Mongoose document objects created — slow and memory-heavy
res.json({ data: tasks });

✅ Correct — use lean() for GET endpoints that do not modify documents:

const tasks = await Task.find({ userId }).limit(100).lean();
// 100 plain JS objects — 20x faster, lower memory
res.json({ data: tasks });

Quick Reference #