Limit the Number of Returned Results

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.

const myDB = client.db("myDB");
const myColl = myDB.collection("books");
await myColl.insertMany([
  { "_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": "Martin", "length": 1104 },
]);

Limit

The following example queries the collection to return the top three longest books. It matches all documents because the query filter is empty. Then, it applies a descending sort on the length field to return longer books before shorter books and a limit to return only the 3 first results:

// define an empty query document
const query = {};
// sort in descending (-1) order by length
const sort = { length: -1 };
const limit = 3;
const cursor = myColl.find(query).sort(sort).limit(limit);
for await (const doc of cursor) {
    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 }

myColl.find(query).sort({ length: -1 }).limit(3);
myColl.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:

myColl.find(query).sort({ length: -1 }).limit(3);
myColl.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 = myColl.find(query).sort(sort).limit(limit).skip(skip);
for await (const doc of cursor) {
    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.