Faster Mongoose Queries With Lean

    By default, Mongoose queries return an instance of the . Documents are much heavier than vanilla JavaScript objects, because they have a lot of internal state for change tracking. Enabling the lean option tells Mongoose to skip instantiating a full Mongoose document and just give you the POJO.

    How much smaller are lean documents? Here’s a comparison.

    1. const schema = new mongoose.Schema({ name: String });
    2. const MyModel = mongoose.model('Test', schema);
    4. await MyModel.create({ name: 'test' });
    6. // Module that estimates the size of an object in memory
    7. const sizeof = require('object-sizeof');
    9. const normalDoc = await MyModel.findOne();
    10. // To enable the `lean` option for a query, use the `lean()` function.
    11. const leanDoc = await MyModel.findOne().lean();
    13. sizeof(normalDoc); // approximately 600
    14. sizeof(leanDoc); // 36, more than 10x smaller!
    16. // In case you were wondering, the JSON form of a Mongoose doc is the same
    17. // as the POJO. This additional memory only affects how much memory your
    18. // Node.js process uses, not how much data is sent over the network.
    19. JSON.stringify(normalDoc).length === JSON.stringify(leanDoc.length); // true

    Under the hood, after executing a query, Mongoose converts the query results from POJOs to Mongoose documents. If you turn on the lean option, Mongoose skips this step.

    1. const normalDoc = await MyModel.findOne();
    2. const leanDoc = await MyModel.findOne().lean();
    4. normalDoc instanceof mongoose.Document; // true
    5. normalDoc.constructor.name; // 'model'
    7. leanDoc instanceof mongoose.Document; // false
    8. leanDoc.constructor.name; // 'Object'
    • Change tracking
    • Casting and validation
    • Getters and setters
    • Virtuals
    • save()

    For example, the following code sample shows that the Person model’s getters and virtuals don’t run if you enable lean.

    Populate works with lean(). If you use both populate() and lean(), the lean option propagates to the populated documents as well. In the below example, both the top-level ‘Group’ documents and the populated ‘Person’ documents will be lean.

    1. const Group = mongoose.model('Group', new mongoose.Schema({
    2.   name: String,
    3.   members: [{ type: mongoose.ObjectId, ref: 'Person' }]
    4. }));
    6.   name: String
    7. }));
    9. // Initialize data
    10. const people = await Person.create([
    11.   { name: 'Benjamin Sisko' },
    12.   { name: 'Kira Nerys' }
    13. ]);
    14. await Group.create({
    15.   name: 'Star Trek: Deep Space Nine Characters',
    16.   members: people.map(p => p._id)
    17. });
    19. // Execute a lean query
    20. const group = await Group.findOne().lean().populate('members');
    21. group.members[0].name; // 'Benjamin Sisko'
    22. group.members[1].name; // 'Kira Nerys'
    24. // Both the `group` and the populated `members` are lean.
    25. group instanceof mongoose.Document; // false
    26. group.members[0] instanceof mongoose.Document; // false
    27. group.members[1] instanceof mongoose.Document; // false

    also works with lean.

    1. // Create models
    2. const groupSchema = new mongoose.Schema({ name: String });
    3. groupSchema.virtual('members', {
    4.   ref: 'Person',
    5.   localField: '_id',
    6.   foreignField: 'groupId'
    7. });
    8. const Group = mongoose.model('Group', groupSchema);
    9. const Person = mongoose.model('Person', new mongoose.Schema({
    10.   name: String,
    11.   groupId: mongoose.ObjectId
    12. }));
    14. const g = await Group.create({ name: 'DS9 Characters' });
    15. const people = await Person.create([
    16.   { name: 'Benjamin Sisko', groupId: g._id },
    17.   { name: 'Kira Nerys', groupId: g._id }
    18. ]);
    20. // Execute a lean query
    22.   path: 'members',
    23.   options: { sort: { name: 1 } }
    24. });
    25. group.members[0].name; // 'Benjamin Sisko'
    26. group.members[1].name; // 'Kira Nerys'
    28. // Both the `group` and the populated `members` are lean.
    29. group instanceof mongoose.Document; // false
    30. group.members[0] instanceof mongoose.Document; // false
    31. group.members[1] instanceof mongoose.Document; // false

    Below is an example of an Express route that is a good candidate for lean(). This route does not modify the person doc and doesn’t rely on any Mongoose-specific functionality.

    Below is an example of an Express route that should not use lean(). As a general rule of thumb, GET routes are good candidates for lean() in a . On the other hand, PUT, POST, etc. routes generally should not use lean().

    1. // This route should **not** use `lean()`, because lean means no `save()`.
    2. app.put('/person/:id', function(req, res) {
    3.   Person.findOne({ _id: req.params.id }).
    4.     then(person => {
    5.       assert.ok(person);
    6.       Object.assign(person, req.body);
    7.       return person.save();
    8.     }).
    9.     then(person => res.json({ person })).
    10.     catch(error => res.json({ error: error.message }));
    11. });

    Remember that virtuals do not end up in lean() query results. Use the mongoose-lean-virtuals plugin to add virtuals to your lean query results.

    However, you need to keep in mind that Mongoose does not hydrate lean documents, so this will be a POJO in virtuals, getters, and default functions.

    1. const schema = new Schema({ name: String });
    2. schema.plugin(require('mongoose-lean-virtuals'));
    4. schema.virtual('lowercase', function() {
    5.   this instanceof mongoose.Document; // false
    7.   this.name; // Works
    8.   this.get('name'); // Crashes because `this` is not a Mongoose document.