Monitor Data Changes

Overview

In this guide, you can learn how to use a change stream to monitor real-time changes to your database. A change stream is a MongoDB Server feature that allows your application to subscribe to data changes on a collection, database, or deployment.

When using the C++ driver, you can instantiate a mongocxx::change_stream to monitor data changes.

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

Open a Change Stream

To open a change stream, call the watch() method. The instance on which you call the watch() method on determines the scope of events that the change stream listens for. You can call the watch() method on the following classes:

• mongocxx::client: Monitor all changes in the MongoDB deployment

• mongocxx::database: Monitor changes in all collections in the database

• mongocxx::collection: Monitor changes in the collection

The following example opens a change stream on the restaurants collection and outputs changes as they occur:

auto stream = collection.watch();
while (true) {
    for (const auto& event : stream) {
        std::cout << bsoncxx::to_json(event) << std::endl;
    }
}

To begin watching for changes, run the preceding code. Then, in a separate application or shell, modify the restaurants collection. The following example updates a document that has a name field value of Blarney Castle:

auto result = collection.update_one(make_document(kvp("name", "Blarney Castle")), 
                                    make_document(kvp("$set", 
                                    make_document(kvp("cuisine", "Irish")))));

When you update the collection, the change stream application prints the change as it occurs. The printed change event resembles the following output:

{ "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" :
{ "$timestamp" : { ... }, "wallTime" : { "$date" : ... }, "ns" :
{ "db" : "sample_restaurants", "coll" : "restaurants" }, "documentKey" :
{ "_id" : { "$oid" : "..." } }, "updateDescription" : { "updatedFields" :
{ "cuisine" : "Irish" }, "removedFields" : [  ], "truncatedArrays" : [  ] } }

Modify the Change Stream Output

You can pass a mongocxx::pipeline instance as an argument to the watch() method to modify the change stream output. The following list includes some of the mongocxx::pipeline fields you can set by calling their corresponding setter methods:

• add_fields: Adds new fields to documents

• match: Filters the documents

• project: Projects a subset of the document fields

• redact: Restricts the contents of the documents

• group: Groups documents by a specified expression

• merge: Outputs the results to a collection

The following example sets the match field of a mongocxx::pipeline instance, then passes the pipeline to the watch() method. This instructs the watch() method to output only update operations:

mongocxx::pipeline pipeline;
pipeline.match(make_document(kvp("operationType", "update")));
auto stream = collection.watch(pipeline);
while (true) {
    for (const auto& event : stream) {
        std::cout << bsoncxx::to_json(event) << std::endl;
    }
}

Modify watch() Behavior

You can modify the behavior of the watch() method by passing an instance of the mongocxx::options::change_stream class as a parameter. The following table describes the fields you can set in a mongocxx::options::change_stream instance:

mongocxx::options::change_stream opts;
opts.full_document("updateLookup");
auto stream = collection.watch(opts);
while (true) {
    for (const auto& event : stream) {
        std::cout << bsoncxx::to_json(event) << std::endl;
    }
}

{ "_id" : { "_data" : "..." }, "operationType" : "update", "clusterTime" :
{ "$timestamp" : { ... } }, "wallTime" : { "$date" : ... },
"fullDocument" : { "_id" : { "$oid" : "..." }, "address" : { "building" : "202-24",
"coord" : [ -73.925044200000002093, 40.559546199999999772 ], "street" :
"Rockaway Point Boulevard", "zipcode" : "11697" }, "borough" : "Queens", "cuisine" :
"Irish", "grades" : [ ... ], "name" : "Blarney Castle", "restaurant_id" : "40366356" },
"ns" : { "db" : "sample_restaurants", "coll" : "restaurants" }, "documentKey" :
{ "_id" : { "$oid" : "..." } }, "updateDescription" : { "updatedFields" :
{ "cuisine" : "Irish" }, "removedFields" : [  ], "truncatedArrays" : [  ] } }

Additional Information

To learn more about change streams, see Change Streams in the MongoDB Server manual.