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.
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.
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" : [ ] } }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
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; }}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:
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.
ImportantYou 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" : [ ] } }To learn more about change streams, see Change Streams in the MongoDB Server manual.
To learn more about any of the methods or types discussed in this guide, see the following API documentation:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4