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

Retrieve Data

On this page

  • Overview
  • Sample Data
  • Find Documents
  • Find One Document
  • Find Multiple Documents
  • Modify Find Behavior
  • Additional Information
  • API Documentation

In this guide, you can learn how to use the C++ driver to retrieve data from a MongoDB collection by using read operations. You can call the find() or find_one() method on a collection to retrieve documents that match a set of criteria.

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.

The C++ driver includes two methods for retrieving documents from a collection: find_one() and find(). These methods take a query filter and return one or more matching documents. A query filter is an object that specifies the documents you want to retrieve in your query.

Tip

To learn more about query filters, see Specify a Query.

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.

Tip

The find_one() method is useful when you know there's only one matching document or if you're only interested in the first match.

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

Tip

Sort Order

The find_one() method returns the first document in natural order on disk if no sort criteria is specified.

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

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 for-in 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",
...

Note

Find All Documents

To find all documents in a collection, pass an empty filter to the find() method:

auto cursor = collection.find({})

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:

Field
Description
batch_size
The number of documents to return per batch.
Type: std::int32_t
collation
The collation to use for the operation.
Type: bsoncxx::document::view_or_value
comment
The comment to attach to the operation.
Type: bsoncxx::string::view_or_value
cursor_type
The type of cursor to use for the operation.
Type: cursor::type
limit
The maximum number of documents the operation can return.
Type: std::int64_t
skip
The number of documents to skip before returning results.
Type: std::int64_t
sort
The order in which the operation returns matching documents.
Type: bsoncxx::document::view_or_value

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.

To learn more about query filters, see Specify a Query.

For runnable code examples of retrieving documents with the C++ driver, see Read Data from MongoDB.

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

  • find()

  • find_one()

  • limit()

Back

Read Data