Docs Menu
Docs Home
/ / /
C++ Driver
/

Specify Documents to Return

On this page

  • Overview
  • Sample Data
  • Limit
  • Sort
  • Skip
  • Combine Limit, Sort, and Skip
  • Additional Information
  • API Documentation

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

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

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

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

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To access this collection from your C++ application, instantiate a mongocxx::client that connects to an Atlas cluster and assign the following values to your db and collection variables:

auto db = client["sample_restaurants"];
auto collection = db["restaurants"];

To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

To specify the maximum number of documents returned from a read operation, create an instance of the mongocxx::options::find class and set its limit field. Then, pass your mongocxx::options::find instance as an argument to the find() method.

The following example finds all restaurants that have a cuisine field value of "Italian" and limits the results to 5 documents:

mongocxx::options::find opts{};
opts.limit(5);
auto cursor = collection.find(make_document(kvp("cuisine", "Italian")), opts);
for(auto&& doc : cursor) {
std::cout << bsoncxx::to_json(doc) << std::endl;
}
{ "_id" : { "$oid" : "..." }, ..., "name" : "Philadelphia Grille Express", "restaurant_id" : "40364305" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Isle Of Capri Restaurant", "restaurant_id" : "40364373" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Marchis Restaurant", "restaurant_id" : "40364668" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Crystal Room", "restaurant_id" : "40365013" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Forlinis Restaurant", "restaurant_id" : "40365098" }

Tip

The preceding example returns the first five documents matched by the query according to their natural order in the database. The following section describes how to return the documents in a specified order.

To return documents in a specified order, create a document that includes the field to sort the results by and the sort direction. A value of 1 sorts values from lowest to highest, and a value of -1 sorts them from highest to lowest. Then, call the mongocxx::options::find::sort() method on a mongocxx::options::find instance and pass this document as an argument.

The following example returns all documents that have a cuisine value of "Italian", sorted in ascending order of name field values:

mongocxx::options::find opts{};
opts.sort(make_document(kvp("name", 1)));
auto cursor = collection.find(make_document(kvp("cuisine", "Italian")), opts);
for(auto&& doc : cursor) {
std::cout << bsoncxx::to_json(doc) << std::endl;
}
{ "_id" : { "$oid" : "..." }, ..., "name" : "(Lewis Drug Store) Locanda Vini E Olii", "restaurant_id" : "40804423" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "101 Restaurant And Bar", "restaurant_id" : "40560108" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "44 Sw Ristorante & Bar", "restaurant_id" : "40698807" }
...
{ "_id" : { "$oid" : "..." }, ..., "name" : "Zucchero E Pomodori", "restaurant_id" : "41189590" }

To skip a specified number of documents before returning your query results, create an instance of the mongocxx::options::find class and set its skip field. Then, pass your mongocxx::options::find instance as an argument to the find() method.

The following example returns all documents that have a borough field value of "Manhattan" and skips the first 10 documents:

mongocxx::options::find opts{};
opts.skip(10);
auto cursor = collection.find(make_document(kvp("borough", "Manhattan")), opts);
for(auto&& doc : cursor) {
std::cout << bsoncxx::to_json(doc) << std::endl;
}
{ "_id" : { "$oid" : "..." }, ..., "name" : "Cafe Metro", "restaurant_id" : "40363298" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Lexler Deli", "restaurant_id" : "40363426" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Domino'S Pizza", "restaurant_id" : "40363644" }
...

You can set the limit, sort, and skip fields of a single mongocxx::options::find instance. 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 5 documents that have a cuisine value of "Italian". The results are sorted in ascending order by name field value, skipping the first 10 documents:

mongocxx::options::find opts{};
opts.sort(make_document(kvp("name", 1))).limit(5).skip(10);
auto cursor = collection.find(make_document(kvp("cuisine", "Italian")), opts);
for(auto&& doc : cursor) {
std::cout << bsoncxx::to_json(doc) << std::endl;
}
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acqua", "restaurant_id" : "40871070" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acqua Restaurant", "restaurant_id" : "41591488" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acqua Santa", "restaurant_id" : "40735858" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acquista Trattoria", "restaurant_id" : "40813992" }
{ "_id" : { "$oid" : "..." }, ..., "name" : "Acquolina Catering", "restaurant_id" : "41381423" }

Note

The order in which you call these methods doesn't change the documents that are returned. The driver automatically reorders the calls to perform the sort operation first, the skip operation next, and then the limit operation.

For more information about retrieving documents, see the Retrieve Data guide.

For more information about specifying a query, see the Specify a Query guide.

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

Back

Specify a Query