Access Data From a Cursor

Overview

In this guide, you can learn how to access data from a cursor by using the C++ driver.

A cursor is a mechanism that returns the results of a read operation in iterable batches. Cursors reduce both memory consumption and network bandwidth usage by holding only a subset of documents at any given time rather than returning all documents at once.

Whenever the C++ driver performs a read operation by using the find() method, it returns the matching documents in a mongocxx::cursor instance.

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

Retrieve All Cursor Documents

To iterate over the contents of a mongocxx::cursor instance, use a for loop.

The following example uses the find() method to retrieve all documents that have a name value of "Dunkin' Donuts". It then prints each document from the cursor returned by the find() method:

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

{ "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40379573" }
{ "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40363098" }
{ "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40395071" }
...

Retrieve Documents Individually

To retrieve an individual document from a cursor, call the begin() method on a mongocxx::cursor instance. This method returns an instance of mongocxx::cursor::iterator that points to the first document in the cursor.

The following example finds all documents in a collection that have a name value of "Dunkin' Donuts". It then prints the first document from the cursor by calling the begin() method:

auto cursor = collection.find(make_document(kvp("name", "Dunkin' Donuts")));
auto doc = cursor.begin();
std::cout << bsoncxx::to_json(*doc) << std::endl;

{ "_id" : { "$oid" : "..." }, ... "name" : "Dunkin' Donuts", "restaurant_id" : "40379573" }

Tailable Cursors

When querying on a capped collection, you can use a tailable cursor that remains open after the client exhausts the results in a cursor. To create a tailable cursor, instantiate a mongocxx::options::find object and set its cursor_type field to mongocxx::cursor::type::k_tailable. Then, pass your mongocxx::options::find instance as an argument to the find() method.

For example, you can create a capped collection called vegetables that stores documents representing vegetables, as shown in the following code:

auto db = client["db"];
auto collection = db.create_collection("vegetables", make_document(kvp("capped", true), kvp("size", 1024 * 1024)));
std::vector<bsoncxx::document::value> vegetables;
vegetables.push_back(make_document(kvp("name", "cauliflower")));
vegetables.push_back(make_document(kvp("name", "zucchini")));
auto result = collection.insert_many(vegetables);

The following code uses a tailable cursor to retrieve all documents in the vegetables collection. After the cursor is exhausted, it remains open until retrieving three documents:

mongocxx::options::find opts{};
opts.cursor_type(mongocxx::cursor::type::k_tailable);
auto cursor = collection.find({}, opts);
int docs_found = 0;
while (docs_found < 3) {
    for (auto&& doc : cursor) {
        std::cout << bsoncxx::to_json(doc) << std::endl;
        docs_found++;
    }
    // Sleeps for 100 milliseconds before trying to access more documents
    std::this_thread::sleep_for(std::chrono::milliseconds(100));
}

{ "_id" : { "$oid" : "..." }, "name" : "cauliflower" }
{ "_id" : { "$oid" : "..." }, "name" : "zucchini" }

If you insert another document into the vegetables collection, the preceding code prints the new document and closes the while loop.

To learn more about tailable cursors, see the Tailable Cursors guide in the MongoDB Server manual.

Additional Information

To learn more about read operations, see the Retrieve Data guide.