Retrieve Data

Sample Data

The examples in this guide use the companies collection in the sample_training 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_training"];
auto collection = db["companies"];

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

Find One Document

To find a single document in a collection, call the find_one() method and pass a query filter that specifies the criteria of the document you want to find.

The find_one() method returns an instance of std::optional< bsoncxx::document::value >. If the query filter matches a document, the optional object contains a value of type bsoncxx::document::value. If the query filter does not match any documents, the optional object contains no value.

If the query filter matches more than one document, the find_one() method returns the first matching document from the retrieved results.

The following example uses the find_one() method to find the first document in which the name field has the value "LinkedIn":

auto result = collection.find_one(make_document(kvp("name", "LinkedIn")));
std::cout << bsoncxx::to_json(*result) << std::endl;

{ "_id" : { "$oid" : "52cdef7c4bab8bd675297e0c" }, "name" : "LinkedIn", "permalink" : "linkedin",
"crunchbase_url" : "http://www.crunchbase.com/company/linkedin", "homepage_url" : "http://linkedin.com",
...

To learn more about sorting, see the Sort section of the Specify Documents to Return guide.

Find Multiple Documents

To find multiple documents in a collection, pass a query filter to the find() method that specifies the criteria of the documents you want to retrieve.

The following example uses the find() method to find all documents in which the founded_year field has the value 1970:

auto cursor = collection.find(make_document(kvp("founded_year", 1970)));

The find() method returns an instance of mongocxx::cursor, which you can iterate over to see the matching documents. A cursor is a mechanism that allows an application to iterate over database results while holding only a subset of them in memory at a given time. Cursors are useful when your find() method returns a large amount of documents.

You can iterate over the documents in a cursor by using a range-based for loop, as shown in the following example:

auto cursor = collection.find(make_document(kvp("founded_year", 1970)));
for(auto&& doc : cursor) {
    std::cout << bsoncxx::to_json(doc) << std::endl;
}

{ "_id" : { "$oid" : "52cdef7d4bab8bd675298be4" }, "name" : "Mitsubishi Motors",
"permalink" : "mitsubishi-motors", "crunchbase_url" : "http://www.crunchbase.com/company/mitsubishi-motors",
...
{ "_id" : { "$oid" : "52cdef7e4bab8bd67529b996" }, "name" : "Western Digital",
"permalink" : "western-digital", "crunchbase_url" : "http://www.crunchbase.com/company/western-digital",
...
{ "_id" : { "$oid" : "52cdef7e4bab8bd67529b9f1" }, "name" : "Celarayn", "permalink" : "celarayn",
"crunchbase_url" : "http://www.crunchbase.com/company/celarayn",
...

auto cursor = collection.find({})

Modify Find Behavior

You can modify the behavior of the find() and find_one() methods by passing an instance of the mongocxx::options::find class as a parameter. The following table describes some of the fields you can set in a mongocxx::options::find instance:

The following example uses the find() method to find all documents in which the number_of_employees field has the value 1000 and instructs the operation to return a maximum of 5 results:

mongocxx::options::find opts;
opts.limit(5);
auto cursor = collection.find(make_document(kvp("number_of_employees", 1000)), opts);

For a full list of mongocxx::options::find object fields, see the API documentation.

API Documentation

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

• find()

• find_one()

• limit()