Change Stream on vCore-based Azure Cosmos DB for MongoDB (Preview)

Change streams are a real-time stream of database changes that flows from your database to your application. This feature enables you to build reactive applications by subscribing to database changes, eliminating the need for continuous polling to detect changes.

Enable change streams

You can enable or disable this feature using the Azure CLI or an ARM template. Portal support will be added soon.

Steps to enable change streams on vCore cluster via CLI

  1. Log in to Azure CLI
az login
  1. Retrieve the current settings for the feature flags on your cluster. This ensures you retain any existing flags while adding the new feature.
az resource show --ids "/subscriptions/<sub id>/resourceGroups/<resource group name>/providers/Microsoft.DocumentDB/mongoClusters/<resource name of your Cosmos DB for MongoDB vCore cluster>" --api-version 2024-10-01-preview
  1. Send PATCH request to enable the feature.
az resource patch --ids "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.DocumentDB/mongoClusters/<vCore_cluster_name>" --api-version 2024-10-01-preview --properties "{\"previewFeatures\": [ \"ChangeStreams\"]}"
  1. Verify result:
    • Ensure the response payload includes "previewFeatures": ["ChangeStreams"].
    • If you encounter the error "change streams isn't supported on this cluster," please create a support request.

Configuring change streams

This example code initiates a change stream on the exampleCollection collection, continuously monitoring for any changes. When a change is detected, it retrieves the change event and prints it in JSON format.

// Open a change stream
const changeStream = db.exampleCollection.watch();

// Listen for changes
while (changeStream.hasNext()) 
    {
        const change = changeStream.next();
        printjson(change);
    }

Important

Change streams are resumable by specifying a resume token to resumeAfter when opening the cursor. Though, it's expected that there's enough history to locate the operation associated with the token. The document observed in change stream in _id field represents the resumable token.

cursor = db.exampleCollection.watch(resume_after=resume_token)

Monitoring database changes with Change Stream

Let's understand the change stream output through the example.

In this change stream event, we see that a new record was inserted into the exampleCollection collection within the cs database, and the event details include the full content of the newly added document.

{
  "_id": { "_data": "AeARBpQ/AAAA" }, // "resume_token"
  "operationType": "insert",
  "fullDocument": {
    "_id": { "$oid": "66e6f63e6f49ecaabf794958" },
    "employee_id": "17986",
    "name": "John",
    "position": "Software Engineer",
    "department": "IT",
    "rating": 4
  },
  "ns": { "db": "cs", "coll": "exampleCollection" },
  "documentKey": { "_id": { "$oid": "66e6f63e6f49ecaabf794958" } }
}

Personalize data in Change Stream

Customize your change stream output by specifying an array of one or more pipeline stages during configuration. Supported operators include the following.

  • $addFields
  • $match
  • $project
  • $set
  • $unset

Limitations

  • Historical change stream events from past timeline are yet not supported.
  • Change stream events on multi-shard cluster are yet not supported.
  • Change stream cursors need to be reinitialized after a fail-over event at current state.
  • Update event yet doesn't support Update description.
  • pre-image is an unsupported option.
  • $changestream as a nested pipeline of another stage is yet not supported.