Navigation

Limit the Number of Returned Results

Use limit to cap the number of documents that can be returned from a read operation. limit functions as a cap on the maximum number of documents that the operation can return, but the operation can return a smaller number of documents if there are not enough documents present to reach the limit. If limit is used with the skip method, the skip applies first and the limit only applies to the documents left over after the skip.

Follow the instructions in the examples below to insert data into a collection and return only certain results from a query using a sort, a skip, and a limit. Consider the following collection of documents that describe books:

[
{ "_id": 1, "name": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 },
{ "_id": 2, "name": "Les Misérables", "author": "Hugo", "length": 1462 },
{ "_id": 3, "name": "Atlas Shrugged", "author": "Rand", "length": 1088 },
{ "_id": 4, "name": "Infinite Jest", "author": "Wallace", "length": 1104 },
{ "_id": 5, "name": "Cryptonomicon", "author": "Stephenson", "length": 918 },
{ "_id": 6, "name": "A Dance With Dragons", "author": "Tolkein", "length": 1104 },
]

The following example queries the collection to return the top three longest books. It matches all the documents with the query, applies a sort on the length field to return books with longer lengths before books, and applies a limit to return only 3 results:

// define an empty query document
const query = {};
// sort in descending (-1) order by length
const sort = { length: -1 };
const limit = 3;
const cursor = collection.find(query).sort(sort).limit(limit);
await cursor.forEach(console.dir);

The code example above outputs the following three documents, sorted by length:

{ "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 }
{ "_id": 6, "title": "A Dance With Dragons", "author": "Martin", "length": 1104 }
{ "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 }
Info With Circle IconCreated with Sketch.Note

The order in which you call limit and sort does not matter because the driver reorders the calls to apply the sort first and the limit after it. The following two calls are equivalent:

collection.find(query).sort({ length: -1 }).limit(3);
collection.find(query).limit(3).sort({ length: -1 });

You can also apply sort and limit by specifying them in an options object in your call to the find() method. The following two calls are equivalent:

collection.find(query).sort({ length: -1 }).limit(3);
collection.find(query, { sort: { length: -1 }, limit: 3 });

For more information on the options settings for the find() method, see the API documentation on find().

To see the next three longest books, append the skip() method, passing the number of documents to skim over to the previous code snippet's call to find():

// define an empty query document
const query = {};
// sort in ascending (1) order by length
const sort = { length: 1 };
const limit = 3;
const skip = 3;
const cursor = collection.find(query).sort(sort).limit(limit).skip(skip);
await cursor.forEach(console.dir);

This operation returns the documents that describe the fourth through sixth longest books:

{ "_id": 3, "title": "Atlas Shrugged", "author": "Rand", "length": 1088 }
{ "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 }
{ "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }

You can combine skip and limit in this way to implement paging for your collection, returning only small "slices" of the collection at once.

Give Feedback