Cosmos DB Change Feed

Azure Cosmos DB Change Feed is a persistent, append-only log of all document-level changes (inserts, updates, and deletes) within a container. It captures changes in the order they occur (by modification timestamp) and exposes them via a sorted, paginated feed. The Change Feed is not a separate store—it is a logical representation of the container's write-ahead log, and it is automatically available for any container that is configured with a partition key.

Traditional databases require polling or triggers to detect changes, which is inefficient and introduces latency. The Change Feed provides a push-based mechanism that enables event-driven architectures without custom change-tracking code. It is the foundation for patterns like:

When a document is inserted, updated, or deleted in a container, Cosmos DB assigns a logical sequence number (_lsn) and a timestamp (_ts) to the change. The Change Feed is a sorted list of these changes, ordered by _ts ascending. The feed is partitioned by physical partitions—each physical partition maintains its own change feed segment. The Change Feed Processor (or Azure Functions binding) coordinates reading across partitions.

To read the Change Feed programmatically (using .NET SDK):

string connectionString = "AccountEndpoint=https://myaccount.documents.azure.com:443/;AccountKey=mykey==";
CosmosClient client = new CosmosClient(connectionString);
Container feedContainer = client.GetContainer("mydb", "mycontainer");
Container leaseContainer = client.GetContainer("mydb", "leases");

ChangeFeedProcessor processor = feedContainer
    .GetChangeFeedProcessorBuilder("myprocessor", HandleChangesAsync)
    .WithInstanceName("myhost")
    .WithLeaseContainer(leaseContainer)
    .WithStartTime(DateTime.MinValue.ToUniversalTime()) // from beginning
    .Build();

await processor.StartAsync();

To verify: Check the lease container—each partition should have a lease document with LeaseToken, ContinuationToken (the last processed change's LSN), and Owner (the host name).

Many candidates confuse Change Feed with Azure SQL Database's Change Tracking or Change Data Capture. Change Feed is specific to Cosmos DB and does not require schema changes or triggers. Also, note that Change Feed does not support filtering by document content—you must filter in your consumer code.

[FunctionName("ProcessChanges")]
public static void Run([CosmosDBTrigger(
    databaseName: "mydb",
    collectionName: "mycontainer",
    ConnectionStringSetting = "CosmosDBConnection",
    LeaseCollectionName = "leases",
    CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
    ILogger log)
{
    if (documents != null && documents.Count > 0)
    {
        log.LogInformation($"Documents modified: {documents.Count}");
        // Process each document
    }
}

The Change Feed is a sorted, per-partition log of document changes. The Change Feed Processor uses a lease container to coordinate multiple consumers. Each consumer owns a set of partitions and advances its lease after successfully processing a batch. If a consumer fails, its leases expire and are reassigned. This provides fault-tolerant, at-least-once processing with ordering guarantees within a partition.

A large e-commerce platform uses Cosmos DB as its primary product catalog. To provide fast full-text search, they maintain an Azure Cognitive Search index. They deploy an Azure Function with a CosmosDBTrigger that reads the Change Feed and pushes updates to the search index. The function is scaled out to 10 instances. The lease container is configured with 1000 RU/s to handle the checkpoint write load. Initially, they forgot to set CreateLeaseCollectionIfNotExists = true, causing deployment failures. After fixing, they noticed that deletes were not reflected in search because the default Change Feed mode ignores deletes. They implemented a soft-delete pattern (setting an isDeleted flag) to capture deletions. Performance tip: they set MaxItemsPerInvocation to 500 to reduce function invocations.

A financial services company aggregates transaction data from multiple regions into a central analytics store. Each region has its own Cosmos DB container. They use Change Feed Processor instances in each region to stream changes to an Azure Event Hub, which then feeds into Azure Synapse. The challenge was ordering: since changes across regions are not globally ordered, they added a timestamp field and used a session window in Synapse. They also discovered that the Change Feed Processor's default polling interval of 100ms was too aggressive for their low-throughput containers, causing unnecessary RU consumption on the lease container. They increased the polling interval to 1 second via WithPollInterval(TimeSpan.FromSeconds(1)).

A SaaS company needs real-time dashboards that aggregate data from multiple containers. They use Change Feed to maintain a materialized view container that denormalizes data. They deploy a .NET Core microservice that hosts the Change Feed Processor. Initially, they used a single instance, which became a bottleneck. They scaled out to 4 instances, but experienced duplicate processing because lease distribution was uneven. They fixed it by ensuring all instances used the same processor name and lease container prefix. They also configured WithMaxItems(100) to control batch size. Common mistake: they forgot to set WithStartTime for new deployments, causing the processor to start from the current time and miss historical data. They now always set WithStartTime(DateTime.MinValue.ToUniversalTime()) for backfill scenarios.

When misconfigured, common issues include: lease container running out of RU/s (throttling), lease expiration causing frequent rebalancing, and missing deletes. Always monitor the lease container's request units and set appropriate throughput.