Change Feed

The killer feature you didn’t know you wanted. Change Feed turns Cosmos from a database into a building block for streaming architectures — every change you make becomes a durable event you can subscribe to, with no Kafka, no Event Hub, no dual-writes.

What it is

A persistent, per-partition log of every insert and update. Each entry has the new state of the document, sorted by a logical sequence number. You consume it via the SDK’s Change Feed Processor (push) or the raw pull API.

var processor = container
    .GetChangeFeedProcessorBuilder<Order>("orderProcessor", HandleChanges)
    .WithInstanceName(Environment.MachineName)
    .WithLeaseContainer(leaseContainer)
    .Build();

await processor.StartAsync();

async Task HandleChanges(IReadOnlyCollection<Order> orders, CancellationToken ct) {
  foreach (var order in orders) {
    // do something — update search index, send email, populate cache
  }
}

That’s the whole API. Cosmos handles partitioning, scaling, checkpointing, and retries.

Common patterns

Materialized views

Maintain a denormalized read-optimized view of your data. Orders container → on every change, update a ordersByCustomerSummary container with aggregated totals. The view is eventually-consistent with the source, but a single read instead of many.

Search index sync

Every change flows to Azure AI Search / Elasticsearch. Your transactional source of truth stays in Cosmos; full-text search lives elsewhere. No dual-write problem.

Cache invalidation

Change Feed pushes to Redis — write Cosmos, Redis sees the change within ~500ms, evicts or updates its cache entry. Beats TTL-based eviction for correctness.

Cross-region replication

For workloads where Cosmos’s built-in multi-region (lesson V12) doesn’t fit, run a Change Feed processor that writes to another Cosmos account. Lets you do filtered replication, schema transformations, or replication to non-Cosmos targets (Synapse, ADLS, S3).

Domain events

Treat every Cosmos change as a domain event — OrderPlaced, InventoryAdjusted. A handler triggers downstream workflows. This is a poor man’s event sourcing — it works surprisingly well.

Lease container — what it actually does

Each Change Feed processor instance reads from one or more leases. A lease is a small document in a separate container that tracks “I’m working on partition X, last checkpoint Y.”

When you scale out — add a second host with the same processor name — the leases redistribute (one host gets some, the other gets others). When a host dies, its leases are picked up by surviving hosts within ~30 seconds. This is built-in and zero-config.

You provision a small lease container — 400 RU/s is plenty for most workloads. One lease container can serve many processors if you give each a different name.

Push vs pull

Push (Change Feed Processor) — the SDK manages everything. You provide a callback, it provides scaling, checkpointing, error handling. The right answer 95% of the time.

Pull — raw API. You call GetChangeFeedIterator() and manage your own checkpoint. Useful for one-off backfills, batch jobs, or when integrating with a framework that has its own scaling model (Spark, Flink).

The deletes problem

Change Feed doesn’t emit delete events in the default mode. Two patterns to handle this:

Soft delete + TTL — instead of DELETE, set isDeleted: true + deletedAt: now on the document. Change Feed sees the update; consumers act on it. Set container-level TTL or per-doc TTL to physically purge after a buffer period (say, 7 days).

All-versions-and-deletes mode — if you don’t want soft-delete plumbing, opt into the all-versions feed. It emits delete tombstones. Slightly more expensive in storage and consumer complexity, but you get hard deletes.

Latency

Change Feed is consistent within ~1 second from write to consumer. Some are sub-200ms, some up to 2-3 seconds during partition splits. Don’t use it for sub-100ms real-time push — use SignalR / WebSockets / direct push for that. Use Change Feed for everything else async.