How does Query.prototype.lean() Work in Mongoose ?

Mongoose is a powerful Object Data Modeling (ODM) library for MongoDB and Node.js, offering an easy way to interact with your MongoDB database. One of the key functions provided by Mongoose to optimize query performance is Query.prototype.lean().

In this article, we will explain what the .lean() function is, how it works, and when to use it to optimize your Mongoose queries for better performance. We'll also walk through practical examples to help you understand how to use the lean option effectively.

What is Query.prototype.lean() in Mongoose?

In Mongoose, queries return instances of Mongoose Document objects by default. These documents are fully featured objects that provide methods like .save(), .validate(), and .remove() for interacting with the database. However, there are situations where these additional features are not necessary for your use case, and all you need is plain JavaScript data.

This is where the lean() function comes in. The lean() method tells Mongoose to return plain JavaScript objects instead of full Mongoose Document objects. By returning plain objects, the performance of your query improves significantly since Mongoose skips the overhead of instantiating Document objects and their associated methods.

Syntax:  

Query.prototype.lean()

The lean() function can be used on any query in Mongoose. By default, .lean() is called with true, meaning the result will be returned as a plain JavaScript object.

Parameters:

• lean (boolean): If true, Mongoose will return plain JavaScript objects instead of Mongoose Documents. If set to false, Mongoose will return full Document objects (this is the default behavior).

Return Value

• The function returns the query object itself, allowing for method chaining

Why Use Query.prototype.lean()?

Using .lean() in Mongoose can offer several advantages, particularly when performance is a concern:

• Faster Queries: Lean queries skip the overhead of Mongoose Document methods, making them faster and more efficient.
• Lower Memory Usage: Since the result is a plain JavaScript object, it consumes less memory.
• Read-Only Data: Lean queries return objects that are read-only. You cannot call .save() or other Document methods on the result, which can be useful if you only need to read data without the need to modify it.

How to Install Mongoose?

Before diving into the examples, ensure you have the Mongoose library installed in your project

1. Install Mongoose: Open your terminal and run the following command

npm install mongoose

2. Check Mongoose Version: After installing the mongoose module, you can check your mongoose version in command prompt using the command. 

npm mongoose --version

After that, you can just create a folder and add a file for example, index.js as shown below.

Database: The sample database used here is shown below: 
 

Example 1: Basic Usage of lean()

In this example, we demonstrate how to use the .lean() function to optimize a query by returning a plain JavaScript object.

const mongoose = require('mongoose');

// Database connection
mongoose.connect('mongodb://127.0.0.1:27017/geeksforgeeks', {
    useNewUrlParser: true,
    useCreateIndex: true,
    useUnifiedTopology: true
});

// User model
const User = mongoose.model('User', { 
    name: { type: String },
    age: { type: Number }
});

const query = User.find().lean(true)
console.log("Lean Value:", query._mongooseOptions);

The project structure will look like this: 
 

Run index.js file using below command: 

node index.js

Output: 

Lean Value: { lean: true }

Explanation:

• We connect to the geeksforgeeks database and define a User model.
• The query User.find().lean(true) is executed, meaning Mongoose will return plain JavaScript objects instead of full Document instances.
• query._mongooseOptions will contain { lean: true } to confirm that lean mode is enabled.

Example 2: Using lean() with Express.js

In this example, we show how to use the .lean() function in a real-world application with Express.js.

const express = require('express');
const mongoose = require('mongoose');
const app = express()

// Database connection
mongoose.connect('mongodb://127.0.0.1:27017/geeksforgeeks', {
    useNewUrlParser: true,
    useCreateIndex: true,
    useUnifiedTopology: true
});

// User model
const User = mongoose.model('User', { 
    name: { type: String },
    age: { type: Number }
});

const query = User.find().lean(false)
console.log("Lean Value:", query._mongooseOptions);

app.listen(3000, function(error ) {
    if(error) console.log(error)
    console.log("Server listening on PORT 3000")
});

The project structure will look like this: 
 

Run index.js file using below command: 

node index.js

Output: 

Server listening on PORT 3000
Lean Value: { lean: false }

Explanation:

• We connect to the geeksforgeeks database and define a User model in an Express app.
• The query User.find().lean(false) returns Mongoose Document instances, confirming that lean mode is disabled (lean: false).
• The Express app listens on port 3000, and when the query runs, the lean value is logged.

When Should You Use Query.prototype.lean()?

• For Performance Optimization: Use .lean() when you do not need the full Mongoose Document methods, such as when you are only retrieving data without the need to modify it. This will make your queries faster and use less memory.
• When Working with Large Data: If you are dealing with large datasets and just need to retrieve raw data without needing any of Mongoose’s functionality like .save(), .remove(), or custom methods, .lean() can significantly improve performance.
• When You Only Need Read-Only Data: Since documents returned by .lean() are plain JavaScript objects, they cannot be modified and have no built-in methods like .save(). This is ideal for read-only data scenarios.

Conclusion

Mongoose's Query.prototype.lean() is a powerful tool for improving query performance in your application. By returning plain JavaScript objects instead of full Mongoose Document instances, .lean() minimizes memory usage, boosts speed, and provides an efficient way to handle read-only data. However, it's essential to understand when not to use it, if you need to modify documents or call Mongoose-specific methods like .save(), .lean() would not be suitable.