Open Change Streams

Example

The following code example shows how to open a change stream and print change stream events whenever the data in the collection changes:

// The collection variable references a MongoCollection instance
ChangeStreamIterable<Document> changeStream = collection.watch();
changeStream.forEach(event ->
        System.out.println("Received a change: " + event));

An insert operation on the collection should produce output similar to the following text:

Received a change: ChangeStreamDocument{
   operationType='insert',
   resumeToken={"_data": "825EC..."},
   namespace=myDb.myChangeStreamCollection,
   ...
}

For a runnable example, see the Watch for Changes usage example page.

To learn more about the watch() method, see the following API documentation:

• MongoCollection.watch()

• MongoDatabase.watch()

• MongoClient.watch()

Example

The following code example shows how you can apply an aggregation pipeline to configure your change stream to receive change events for only insert and update operations:

List<Bson> pipeline = Arrays.asList(
        Aggregates.match(Filters.in("operationType", Arrays.asList("insert", "update"))));
// collection references a MongoCollection instance
ChangeStreamIterable<Document> changeStream = collection.watch(pipeline);
changeStream.forEach(event ->
        System.out.println("Received a change to the collection: " + event));

When the change stream receives an update change event, the preceding code example outputs the following text:

Received a change to the collection: ChangeStreamDocument{
operationType=update, resumeToken={...},
...

Create a Collection with Pre-Image and Post-Images Enabled

To create a collection with the pre-image and post-image option using the driver, specify an instance of ChangeStreamPreAndPostImagesOptions and call the createCollection() method as shown in the following example:

CreateCollectionOptions collectionOptions = new CreateCollectionOptions();
collectionOptions.changeStreamPreAndPostImagesOptions(new ChangeStreamPreAndPostImagesOptions(true));
database.createCollection("myChangeStreamCollection", collectionOptions);

You can change the pre-image and post-image option in an existing collection by running the collMod command from the MongoDB Shell. To learn how to perform this operation, see the collMod server manual documentation.

Pre-image Configuration Example

The following code example shows how you can configure a change stream to include the pre-image and output the results:

ChangeStreamIterable<Document> changeStream = collection.watch()
        .fullDocumentBeforeChange(FullDocumentBeforeChange.REQUIRED);
changeStream.forEach(event ->
        System.out.println("Received a change: " + event));

The preceding example configures the change stream to use the FullDocumentBeforeChange.REQUIRED option. This configures the change stream to return pre-images for replace, update, and delete change events and for the server to raise an error if the pre-image is unavailable.

Suppose an application updated the latestVersion field of a document in a collection of software library dependencies from the value of 2.0.0 to 2.1.0. The corresponding change event output by the preceding code example should resemble the following text:

Received a change: ChangeStreamDocument{ operationType=update, resumeToken={...}
namespace=software.libraries, destinationNamespace=null, fullDocument=null,
fullDocumentBeforeChange=Document{{_id=6388..., latestVersion=2.0.0, ...}},
...

For a list of options, see the FullDocumentBeforeChange API documentation.

Post-image Configuration Example

The following code example shows how you can configure a change stream to include the post-image and output the results:

ChangeStreamIterable<Document> changeStream = collection.watch()
        .fullDocument(FullDocument.UPDATE_LOOKUP);
changeStream.forEach(event ->
        System.out.println("Received a change: " + event));

The preceding example configures the change stream to use the FullDocument.UPDATE_LOOKUP option. This configures the change stream to return both the deltas between the original and changed document and a copy of the document at some point in time after the change occurred.

Suppose an application updated the population field of a document from the value of 800 to 950 in a collection of city census data. The corresponding change event output by the preceding code example should resemble the following text:

Received a change: ChangeStreamDocument{ operationType=update, resumeToken={...},
namespace=censusData.cities, destinationNamespace=null,
fullDocument=Document{{_id=6388..., city=Springfield, population=950, ...}},
updatedFields={"population": 950}, ...
...

For a list of options, see the FullDocument API documentation.