When you run queries In MongoDB, you have the option of limiting the documents returned. This is where you specify a maximum number of documents to be returned by the operation.

For example, if an operation would normally return 2,000 documents, but you specify a limit of 1,000, then only 1,000 documents are returned. However, if the operation would only return say, 500 documents, then all 500 are returned (because they don’t breach the 1,000 document limit).

This is a bit like using the TOP clause in SQL Server, or the LIMIT clause in MySQL, MariaDB, PostgreSQL, and SQLite.

Limiting the documents returned can help improve performance by preventing more documents from being returned and processed than is necessary.

In MongoDB, we can use the cursor.limit() method or the $limit aggregation operator to limit the documents returned.

The cursor.limit() Method

Suppose we have a collection called pets with the following documents:

{ "_id" : 1, "name" : "Wag", "type" : "Dog", "weight" : 20 }
{ "_id" : 2, "name" : "Bark", "type" : "Dog", "weight" : 10 }
{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 7 }
{ "_id" : 4, "name" : "Scratch", "type" : "Cat", "weight" : 8 }
{ "_id" : 5, "name" : "Bruce", "type" : "Bat", "weight" : 3 }
{ "_id" : 6, "name" : "Fetch", "type" : "Dog", "weight" : 17 }
{ "_id" : 7, "name" : "Jake", "type" : "Dog", "weight" : 30 }

We can use the limit() method to limit the number of documents returned when querying this collection.

Example:

db.pets.find().limit(3)

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Dog", "weight" : 20 }
{ "_id" : 2, "name" : "Bark", "type" : "Dog", "weight" : 10 }
{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 7 }

The $limit Aggregation Operator

When using the aggregation pipeline, you can use the $limit aggregation operator to limit the results passed to the next stage in the pipeline.

Example:

db.pets.aggregate([
    {
      $match: { }
    },
     { 
      $limit : 3
    }
])

Example:

{ "_id" : 1, "name" : "Wag", "type" : "Dog", "weight" : 20 }
{ "_id" : 2, "name" : "Bark", "type" : "Dog", "weight" : 10 }
{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 7 }

Typically, the $match operator wouldn’t consist of an empty document like we’ve got here. It would normally include a query with which to filter the results at that part of the pipeline. But in this case I used an empty document in order to make the example easier to follow.

Given I passed an empty document in the first stage, I could have just done this:

db.pets.aggregate([
     { 
      $limit : 3
    }
])

Either way, the result was limited to just 3 documents.

When used in the aggregation pipeline, the $limit operator could be somewhere in the middle of the pipeline. If so, it passes the limited documents to the next stage.

Here’s an example to illustrate what I mean.

db.pets.aggregate([
    {
      $match: { }
    },
     { 
      $limit : 3
    },
    {
      $match: { "type": "Cat" }
    }
])

Result:

{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 7 }

Only one cat was in the limited results (even though there are two cats in the original document) so only that cat was matched at the third stage.

This is different to doing the following.

db.pets.aggregate([
    {
      $match: { "type": "Cat" }
    },
     { 
      $limit : 3
    }
])

Result:

{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 7 }
{ "_id" : 4, "name" : "Scratch", "type" : "Cat", "weight" : 8 }

In this case, we searched for cats in the original document, then limited the results to just 3. Given there are only 2 cats, the $limit had no impact on the result.

Limiting Sorted Documents

If you limit the results after sorting the documents, then the limit will take the sorting into account.

Example:

db.pets.aggregate([
    {
      $sort: { "_id": -1 }
    },
     { 
      $limit : 3
    }
])

Result:

{ "_id" : 7, "name" : "Jake", "type" : "Dog", "weight" : 30 }
{ "_id" : 6, "name" : "Fetch", "type" : "Dog", "weight" : 17 }
{ "_id" : 5, "name" : "Bruce", "type" : "Bat", "weight" : 3 }

In this case, I sorted all documents by their _id field in descending order (the -1 specifies descending order).

Here it is again in ascending order (a value of 1 specifies ascending order):

db.pets.aggregate([
    {
      $sort: { "_id": 1 }
    },
     { 
      $limit : 3
    }
])

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Dog", "weight" : 20 }
{ "_id" : 2, "name" : "Bark", "type" : "Dog", "weight" : 10 }
{ "_id" : 3, "name" : "Meow", "type" : "Cat", "weight" : 7 }

When limiting results after they’ve been explicitly sorted, be sure that the sort operation used a stable sort.

A stable sort is one that returns the same sort order each time it is performed. An unstable sort on the other hand, is one that may return a different sort order when performed multiple times.

To ensure that you’re performing a stable sort, include at least one field in your sort that contains exclusively unique values (for example, the _id field).

More Information

For more information, see the MongoDB documentation for:

• cursor.limit()
• $limit (aggregation)