Docs Menu

Docs Home → Develop Applications → MongoDB Drivers → Node.js

Limit the Number of Returned Results

On this page

  • Overview
  • Sample Documents
  • Limit
  • Skip

Overview

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.

Sample Documents

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 },
]

Note

Your query operation may return a reference to a cursor that contains matching documents. To learn how to examine data stored in the cursor, see the Cursor Fundamentals page.

Limit

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 }

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().

Skip

To see the next three books in the results, append the skip() method, passing the number of documents to bypass as shown below:

// define an empty query document
const query = {};
// sort in descending (-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 books in order of longest-to-shortest length:

{ "_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.

←  Skip Returned ResultsSpecify Which Fields to Return →

On this page