Specify Documents to Return

Overview

In this guide, you can learn how to specify which documents to return from a read operation by using the following methods:

• sort(): Specifies the sort order for the returned documents.

• limit(): Specifies the maximum number of documents to return from a query.

• skip(): Specifies the number of documents to skip before returning query results.

You can use these methods either by chaining them to your read operation or by specifying them in an options object in your call to your read operation.

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

Sort

Use the sort() method to change the order in which read operations return documents. This method tells MongoDB to order returned documents by the values of one or more fields in a certain direction. To sort returned documents by a field in ascending (lowest first) order, use a value of 1. To sort in descending (greatest first) order instead, use -1. If you do not specify a sort, MongoDB does not guarantee the order of query results.

The following example passes the sort document to a read operation to ensure that the operation returns books with longer lengths before books with shorter lengths:

// define an empty query document
const query = {};
// sort in descending (-1) order by length
const sort = { length: -1 };
const cursor = myColl.find(query).sort(sort);
for await (const doc of cursor) {
  console.dir(doc);
}

In this case, the number -1 tells the read operation to sort the books in descending order by length. find() returns the following documents when this sort is used with an empty query:

{ "_id": 2, "title": "Les Misérables", "author": "Hugo", "length": 1462 }
{ "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 }
{ "_id": 6, "title": "A Dance with Dragons", "author": "Martin", "length": 1104 }
{ "_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 }

Sometimes, the order of two or more documents is ambiguous using a specified sort. In the preceding example, the documents that have title values of "A Dance with Dragons" and "Infinite Jest" both have a length of 1104, so the order in which they are returned is not guaranteed. To resolve ties in your sorted results in a repeatable way, add more fields to the sort document:

// define an empty query document
const query = {};
// sort in ascending (1) order by length
const sort = { length: 1, author: 1 };
const cursor = myColl.find(query).sort(sort);
for await (const doc of cursor) {
  console.dir(doc);
}

With the addition of the author field to the sort document, the read operation sorts matching documents first by length then, if there is a tie, by author. Matched document fields are compared in the same order as fields are specified in the sort document. find() returns the following ordering of documents when this sort is used on the documents matching the query:

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

Limit

Use the limit() method to cap the number of documents that can be returned from a read operation. This method specifies 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.

This example performs the following actions:

• Uses an empty query filter to match all documents in the collection

• Calls the sort() method to apply a descending sort on the length field to the results

• Calls the limit() method to return only the first 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 = myColl.find(query).sort(sort).limit(limit);
for await (const doc of cursor) {
  console.dir(doc);
}

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

Use the skip() method to omit documents from the beginning of the read operation results. You can combine skip() with sort() to omit the top (for descending order) or bottom (for ascending order) results for a given query. Since the order of documents returned is not guaranteed in the absence of a sort, using skip() without using sort() omits arbitrary documents.

If the value of skip() exceeds the number of matched documents for a query, then that query returns no documents.

This example queries the collection for the books with the fifth and sixth highest lengths by performing the following actions:

• Uses an empty query filter to match all documents in the collection

• Calls the sort() method to apply a descending sort to the length field, which returns longer books before shorter books

• Calls the skip() method to omit the first four matching documents from the result

// define an empty query document
const query = {};
const sort = { length: -1 };
const skip = 4;
const cursor = myColl.find(query).sort(sort).skip(skip);
for await (const doc of cursor) {
  console.dir(doc);
}

Since the query skips the first four matching documents, the preceding code snippet prints the fifth and sixth highest length documents:

{ "_id": 5, "title": "Cryptonomicon", "author": "Stephenson", "length": 918 }
{ "_id": 1, "title": "The Brothers Karamazov", "author": "Dostoyevsky", "length": 824 }

You can also apply skip() and sort() 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 }).skip(4);
myColl.find(query, { sort: { length: -1 }, skip: 4});

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

Combine Limit, Sort, and Skip

You can combine the limit, sort, and skip options in a single operation. This allows you to set a maximum number of sorted documents to return, skipping a specified number of documents before returning.

The following example returns documents with the length value of "1104". The results are sorted in alphabetical order, skipping the first document and includes only the first result:

// define a query to look for length value of 1104
const query = {length: "1104"};
const options = {
   // sort in alphabetical (1) order by title
   sort : { title: 1 },
   // omit the first document
   skip : 1,
   // returns only the first result
   limit: 1,
}
const cursor = myColl.find(query, options);
for await (const doc of cursor) {
  console.dir(doc);
}

{ "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 }

You can also limit, sort, and skip results by chaining each method to the find method. The following example specifies the same query as the preceding example:

myColl.find(query).sort({ title: 1 }).skip(1).limit(1);

{ "_id": 4, "title": "Infinite Jest", "author": "Wallace", "length": 1104 }

Additional Information

For more information about specifying a query, see Query Operations.

For more information about retrieving documents, see Find Documents.