Monitor Data Changes
On this page
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.
Sample Data
The examples in this guide use the restaurants
collection in the sample_restaurants
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_restaurants"]; auto collection = db["restaurants"];
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.
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 deploymentmongocxx::database
: Monitor changes in all collections in the databasemongocxx::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 documentsmatch
: Filters the documentsproject
: Projects a subset of the document fieldsredact
: Restricts the contents of the documentsgroup
: Groups documents by a specified expressionmerge
: Outputs the results to a collection
Tip
For a full list of mongocxx::pipeline
fields, see the mongocxx::pipeline API documentation.
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::find
instance:
Field | Description |
---|---|
full_document | Specifies whether to show the full document after the change, rather
than showing only the changes made to the document. To learn more about
this option, see Include Pre-Images and Post-Images. |
full_document_before_change | Specifies whether to show the full document as it was before the change, rather
than showing only the changes made to the document. To learn more about
this option, see Include Pre-Images and Post-Images. |
resume_after | Instructs watch() to resume returning changes after the
operation specified in the resume token.Each change stream event document includes a resume token as the _id
field. Pass the entire _id field of the change event document that
represents the operation you want to resume after.resume_after is mutually exclusive with start_after and start_at_operation_time . |
start_after | Instructs watch() to start a new change stream after the
operation specified in the resume token. This field allows notifications to
resume after an invalidate event.Each change stream event document includes a resume token as the _id
field. Pass the entire _id field of the change event document that
represents the operation you want to resume after.start_after is mutually exclusive with resume_after and start_at_operation_time . |
start_at_operation_time | Instructs watch() to return only events that occur after the
specified timestamp.start_at_operation_time is mutually exclusive with resume_after and start_after . |
max_await_time_ms | Sets the maximum amount of time, in milliseconds, the server waits for new
data changes to report to the change stream cursor before returning an
empty batch. Defaults to 1000 milliseconds. |
batch_size | Sets the maximum number of change events to return in each batch of the
response from the MongoDB cluster. |
collation | Sets the collation to use for the change stream cursor. |
comment | Attaches a comment to the operation. |
Include Pre-Images and Post-Images
Important
You can enable pre-images and post-images on collections only if your deployment uses MongoDB v6.0 or later.
By default, when you perform an operation on a collection, the
corresponding change event includes only the delta of the fields
modified by that operation. To see the full document before or after a
change, specify the full_document_before_change
or the full_document
fields of a mongocxx::options::change_stream
instance.
The pre-image is the full version of a document before a change. To include the
pre-image in the change stream event, set the full_document_before_change
field to one of the following strings:
"whenAvailable"
: The change event includes a pre-image of the modified document for change events only if the pre-image is available."required"
: The change event includes a pre-image of the modified document for change events. If the pre-image is not available, the driver raises an error.
The post-image is the full version of a document after a change. To include the
post-image in the change stream event, set the full_document
field to
one of the following strings:
"updateLookup"
: The change event includes a copy of the entire changed document from some time after the change."whenAvailable"
: The change event includes a post-image of the modified document for change events only if the post-image is available."required"
: The change event includes a post-image of the modified document for change events. If the post-image is not available, the driver raises an error.
The following example calls the watch()
method on a collection and includes the post-image
of updated documents by setting the full_document
field of 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; } }
With the change stream application running, updating a document in the
restaurants
collection by using the preceding update example prints a change event resembling the following
code:
{ "_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" : [ ] } }
Tip
To learn more about pre-images and post-images, see Change Streams with Document Pre- and Post-Images in the MongoDB Server manual.
Additional Information
To learn more about change streams, see Change Streams in the MongoDB Server manual.
API Documentation
To learn more about any of the methods or types discussed in this guide, see the following API documentation: