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:

• 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.

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

Limit

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" }

Sort

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" }

Skip

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" }
...

Combine Limit, Sort, and Skip

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" }

Additional Information

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

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