Domain 1 of 3 · Chapter 4 of 5

Implement change feed

What the change feed records

Suppose an order service writes {"id": "o-1001", "customerId": "c-42", "status": "paid"} into an orders container, and three other parts of the system must react: a shipping worker, a cache refresher, and an audit job. Instead of each one re-querying the container on a timer, all three read the container's change feed, a persistent record of changes to a container in the order the changes occur[1] whose persisted changes can be processed asynchronously and incrementally[1]; Azure Cosmos DB for NoSQL keeps it for every container and enables it by default for all accounts[1].

This topic covers reading those changes (the two change feed modes, the push and pull ways to consume them, and the lease containers the push model needs) plus container copy jobs, which are built on the change feed. The Microsoft DP-420 study guide skills measured[2] lists 'Implement create, replace, update, patch and delete operations' under Implement database operations and 'Design and select partition keys based on cardinality, access patterns, and write distribution requirements' under Design and implement data models and partitioning strategies (Design and develop database solutions); see Implement database operations and Design and implement data models and partitioning strategies.

A record, not a queue

Reading the change feed removes nothing. Applications can request multiple change feeds using any mode on the same container simultaneously[1], and consuming the change feed in one mode doesn't prohibit you from consuming it in another mode in a different application[3]. So the shipping worker, the cache refresher, and the audit job each see the o-1001 change, and adding a fourth reader takes nothing away from the first three, unlike a queue where competing consumers remove the messages they take. Each reader keeps its own position in the feed (its checkpoint, informally a bookmark), which is why most of this topic is about where that position is stored.

Reading costs throughput: you use your provisioned throughput to read from the change feed, just like any other Azure Cosmos DB operation[1], in any region of the account. The Microsoft DP-420 study guide skills measured[2] also lists 'Evaluate Request Unit (RU) consumption requirements' under Evaluate resource models and SDK solutions; see Evaluate resource models and SDK solutions.

Order is guaranteed per partition key value only

Change feed items come in the order of their modification time. This sort order is guaranteed per partition key, and there's no guaranteed order across the partition key values.[1]

The feed is also split for parallel reading: it is available for partition key ranges of a container[1]. Those ranges map to physical partitions (the server-side partitions that each hold a range of partition key values) when you read with the change feed processor, a library that reads the feed for you, and to FeedRange values when you read with the pull model, where your code requests each page.

Two timestamps in multi-region write accounts

In a multi-region account, changes in one region are available in all regions[1], and the feed stays contiguous across a manual failover of the write region. An account with multiple write regions records two timestamps per item: _ts, the time the write landed in its local region, and crts, the time the hub region (the region that confirms or resolves conflicts) confirmed there was no conflict or resolved one. Change feed items come in the order recorded by crts[1], so never rebuild the feed sequence from _ts. The Microsoft DP-420 study guide skills measured[2] lists 'Implement multi-region read and write configurations' under Implement availability and recovery solutions (Secure, optimize, and deploy database solutions); see Implement availability and recovery solutions.

The takeaway: the change feed is a shared, persistent record with per-partition-key ordering, and every consumer keeps its own checkpoint in it.

Two change feed modes, one feed

This section introduces the two modes a consumer can read the change feed in, because the mode decides what a consumer can see. Each mode offers the same core functionality; the differences are the operations captured in the feed, the metadata available for each change, and the retention period of changes[3]. Think of the mode as the lens a consumer reads through, not a second feed you create (the lens is an analogy, not Microsoft terminology): each individual change feed application can only be configured to read change feed in one mode[3], while another application reads the same container through the other lens.

Property Latest version mode All versions and deletes mode
Operations captured Creates and updates, as the newest version of each item Every create, replace, and delete, including deletes caused by TTL expiry
Updates made between two reads Can collapse into the latest version Each one appears
Deletes Not captured; a deleted item disappears from the feed Captured, with metadata saying whether TTL caused them
How far back you can read Back to the container's creation; no fixed retention period Only inside the account's continuous backup retention window
Start positions Beginning, a point in time, now, or a saved checkpoint Now, or a saved checkpoint inside retention
Setup None; enabled by default Continuous backup plus an account feature
Account types All Azure Cosmos DB APIs except Table and PostgreSQL Azure Cosmos DB for NoSQL only

Every row comes from Microsoft's change feed modes[3] page. TTL (time to live) is the expiry setting that lets the service delete items automatically once their lifetime ends. Continuous backup is the account backup policy that supports point-in-time restore within a retention period[4]. Its alternative policy is periodic backup, in which backup is taken at a periodic interval[5], and accounts use periodic backup by default unless you configure continuous backup[5]; backup policies are covered in Implement availability and recovery solutions. All versions and deletes mode is in preview[6].

If a consumer needs only the current state of each item, latest version mode is enough and needs no setup. If it must see every intermediate change, react to deletes, or tell creates from replaces from deletes, it needs all versions and deletes mode and its prerequisites. Microsoft's scenario lists match: latest version mode suits migrations of an entire container, reprocessing changes from the beginning of the container, and workloads that don't need to capture deletes or intermediate changes[3]; all versions and deletes mode suits triggering alerts on delete operations, as in auditing, and processing creates, updates, and deletes differently based on operation type[3].

Working with latest version mode

Latest version mode is the default, so this section covers what its consumers can and cannot see. It needs no setup: latest version change feed mode is enabled by default[3], and continuous backup is a prerequisite only of all versions and deletes mode.

You see the newest state, not every step

If an item is created and then updated before you read the change feed, only the updated version appears in the change feed[3]. There is also no indication whether a given change is from an insert or an update operation, and deletes aren't captured[1]; once an item is deleted, it is no longer available in the feed. That makes latest version mode the right tool for keeping a copy of current state up to date, and the wrong tool for an audit trail of every mutation.

Patch, the partial update operation, does not change this. When you process items from the change feed, the full document is returned even if the update was the result of a patch operation[7]. If a writer sent an Increment of 5 on /stock, the consumer receives the whole item with its new stock value and must not apply the increment a second time.

In a multi-region write account there is one more gap: an incoming change to a document might be dropped in latest-version mode if there was a more recent change in another region[1], while all versions and deletes mode captures all changes.

Observing deletes with a soft-delete marker

Because hard deletes leave no trace, Microsoft documents a soft-delete marker: add an attribute in the item called deleted with the value true, and then set a TTL on the item; the change feed captures it as an update and the item is deleted when the TTL expires[3]. The catch is timing: you have to process the changes within a shorter time interval than the TTL expiration period[3], because once the item expires it disappears from the latest version feed and the marker with it.

The same marker idea answers a second limitation: you can't filter the change feed for a specific type of operation[3]. Add a marker property to items and filter on it while processing, or switch to all versions and deletes mode, whose metadata names the operation type.

Where a reader can start

The starting point can be the beginning of the container, a point in time, "now," or a specific checkpoint, and the precision of the start time is approximately five seconds[3]. There is no fixed data retention period[3], but because only the most recent change for a specific item is included and deleted items are no longer available[3], reading from the beginning returns the surviving items at their latest versions. It is not a replay of every original version.

What each change looks like

In latest version mode the response is an array of the items that changed, each with the standard metadata _etag and _ts plus a property added for the change feed only, _lsn[3]:

Property What it is Use it for
_ts Modification or creation time stamp Chronological comparison
_lsn A batch ID that represents the transaction; many items can share one Grouping changes from the same transaction
_etag (on each item) Internal identifier of this item version, used for concurrency control; its format can change Optimistic concurrency, never as a checkpoint
ETag (on the feed response) Sequences the feed Checkpointing a Python pull reader (read as the etag header)

The last two rows are the trap: the ETag on FeedResponse is different from the _etag you see on the item; _etag represents the version of the item, whereas ETag is used to sequence the feed[3]. Never store the last item's _etag as a checkpoint: in the pull model you save the position of your FeedIterator by obtaining the continuation token[8] (FeedIterator is the .NET pull-model reader object; see Reading pages with the pull model), which Microsoft's .NET sample reads from response.ContinuationToken and its Python sample from the feed's etag response header (see What the pull model leaves to your code).

The takeaway: latest version mode gives you the latest surviving item states, even when reading from an earlier start point, but no deletes, no guaranteed intermediate versions, and no operation type.

Enabling all versions and deletes mode

All versions and deletes mode needs account-level setup before any consumer can use it, so this section covers that setup and the limits that decide whether an account qualifies. The mode is in preview[6] and is only compatible with Azure Cosmos DB for NoSQL accounts[3].

Two prerequisites, in order

  1. Continuous backup. You must have continuous backups configured for your account before enabling the feature[3]; turning on continuous backups is what creates the all versions and deletes change feed.
  2. The account feature. In the Azure portal, open the account's Features page and enable All versions and deletes change feed mode. Alternatively, set "enableAllVersionsAndDeletesChangeFeed": true in the account properties through the REST API, with preview API version 2024-12-01-preview or later. Enabling this feature during account creation isn't supported, and the enablement process can take up to 30 minutes, during which no other changes can be made to the account[3].

Limits that decide eligibility and behavior

Minimum client versions

The mode also needs a client that understands its event shape. From Microsoft's support table[3]:

Consumer Minimum version for all versions and deletes mode
Pull model .NET SDK 3.60.0, Java SDK 4.81.0, Python SDK 4.9.1b1, JavaScript (Node.js) SDK 4.1.0 (and the Spark connector 4.40.0); note that the pull model guide's Node.js section[8] still says only latest version mode is supported there
Change feed processor .NET SDK 3.60.0, Java SDK 4.81.0; not available for Python or Node.js
Azure Functions trigger .NET isolated worker with Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.16.1; no other language

The Functions row decides many scenarios. The trigger supports latest version mode across all Azure Functions programming models and languages, but all versions and deletes mode only for the .NET isolated worker model with extension 4.16.1 or later[11], so a Python function cannot consume all versions and deletes events.

The takeaway: all versions and deletes mode is both an account decision (continuous backup, the feature, no merge history) and a client decision (a supporting SDK or extension version), and both come before any consumer code.

Reading all versions and deletes events

Once the account is enabled, consumers receive a different data model, so this section covers the event shape and the start rules a consumer must code for. The response object is an array of items that represent each change, and different properties are populated depending on the change type[3]: create and replace events carry the full item under current plus a metadata object, and delete events carry only metadata.

Shape of a delete event in all versions and deletes mode (field names from Microsoft's schema; values illustrative)

{
  "metadata": {
    "operationType": "delete",
    "lsn": 2193,
    "crts": 1761650000,
    "previousImageLSN": 2150,
    "timeToLiveExpired": true,
    "id": "o-1001",
    "partitionKey": { "customerId": "c-42" }
  }
}

Reading the listing field by field:

Typed events in .NET

In .NET this mode yields ChangeFeedItem<T>, not T. A pull reader is typed as FeedIterator<ChangeFeedItem<User>> and opened with ChangeFeedMode.AllVersionsAndDeletes[8], and a processor's delegate (the handler method you write; the processor itself is explained in How the change feed processor works) receives IReadOnlyCollection<ChangeFeedItem<ToDoItem>> and checks item.Metadata.OperationType before using item.Current[6]. The listing below is the core of that delegate.

Branching on operation type in a .NET all versions and deletes handler (adapted from Microsoft's processor sample)

foreach (ChangeFeedItem<Order> change in changes)
{
    if (change.Metadata.OperationType == ChangeFeedOperationType.Delete)
    {
        // A delete has no Current item: only Metadata identifies what was removed.
        // ...
    }
    else
    {
        // Create or Replace: Current holds the full item as it is now.
        await UpsertIntoCacheAsync(change.Current);
    }
}

Deserializing every event as a plain Order fails this contract: a delete event has no current item to deserialize, so the delete branch must read change.Metadata.

Start positions

You can either start from "now" or from a previous lease or continuation token[3]: starting from the beginning of the container or from a past timestamp isn't supported. (A lease is the change feed processor's saved checkpoint and a continuation token is the pull model's; both are explained later.) ChangeFeedStartFrom.Beginning() is therefore invalid in this mode, and loading existing data has to be designed separately from consuming retained changes, for example as a latest version mode read from the beginning.

The takeaway: write all versions and deletes consumers against the event shape (current plus metadata, deletes without a body) and plan their first start from now.

Choosing push or pull consumption

With the mode settled, the next decision is how your code receives changes. Microsoft frames this as a push model or a pull model[12]. In the push model, the change feed processor pushes work to your code and handles checking for work and storing state for the last processed change. In the pull model, your client requests the work and also owns storing that state, load balancing across clients, and handling errors. The push model has two hosting options, so there are three practical choices:

  1. Azure Functions trigger for Azure Cosmos DB. Your function runs for each batch of changes. Azure Functions uses the change feed processor behind the scenes; think of it as a hosting platform for the change feed processor, not an entirely different way of reading the change feed[12]. You get the change feed processor's scaling and reliable event detection without the need to maintain any worker infrastructure[11].
  2. Change feed processor library. You host the processor yourself in a long-running process. It is part of the Azure Cosmos DB .NET V3 and Java V4 SDKs[6].
  3. Pull model (also written "pull mode"; a consumption model, not a third change feed mode). Your code reads pages through an iterator at its own pace, in the .NET, Java, Python, or Node.js SDK[8].

How to choose

In most cases, when you need to read from the change feed, the simplest option is to use the change feed processor[8], and Azure Functions is the recommended option for most change feed use cases[12]. Both are the push model, since the trigger hosts the processor: Functions spares you running workers, and the library runs on your own hosts. Choose the pull model for one of its documented reasons: to read changes from a specific partition key, to control the pace at which your client receives changes, or to perform a one-time read of the existing data (for example, a data migration)[8].

Language narrows the choice further. For Python and Node.js, use the change feed pull model, because the change feed processor library is only available for .NET and Java[6]. A .NET sample built on GetChangeFeedProcessorBuilder has no Python equivalent to port to; a Python team writes a pull-model reader or hosts its logic in an Azure Functions trigger.

Same goal, different failure behavior

The options differ when your handler throws:

Consumer Unhandled exception in your code
Change feed processor The batch is retried from the last checkpoint until it succeeds (at least once)
Azure Functions trigger The change that generated the exception isn't automatically retried; the function moves on to the next change[12]
Pull model No built-in at-least-once delivery guarantee[12]; your code decides

The Functions trigger hosts the processor, yet the Azure Function doesn't retry the same failed change[12]. For both push options Microsoft recommends the same safeguard: in your handler, write the documents that failed to a durable error store for changes you could not process (Microsoft calls it a dead-letter queue or an errored-message queue). How the processor handles failures explains the processor row.

The takeaway: default to the push model (an Azure Functions trigger or the change feed processor) and pick the pull model for single-partition-key reads, self-paced or one-time reads, or SDKs without the processor.

How the change feed processor works

This section covers how the change feed processor is built and the loop it runs, which explains every processor setting in the sections after it. The change feed processor has four main components[6]:

Building and starting a latest version mode processor in .NET (adapted from Microsoft's sample)

Container leaseContainer = cosmosClient.GetContainer(databaseName, "leases");
ChangeFeedProcessor processor = cosmosClient
    .GetContainer(databaseName, "orders")              // the monitored container
    .GetChangeFeedProcessorBuilder<Order>(
        processorName: "orderSync",                    // names this workload
        onChangesDelegate: HandleChangesAsync)          // your delegate
    .WithInstanceName("host-1")                         // unique per compute instance
    .WithLeaseContainer(leaseContainer)                 // where leases are stored
    .Build();
await processor.StartAsync();
// ...

Three details in this listing are easy to get wrong:

The processing life cycle

The normal life cycle of a host instance[6] is a four-step loop, which the figure below traces:

  1. Read the change feed.
  2. If there are no changes, sleep for the poll interval set with WithPollInterval, then go back to step 1.
  3. If there are changes, send them to the delegate.
  4. When the delegate finishes processing the changes successfully, update the lease with the latest processed point in time, then go back to step 1.

WithPollInterval therefore controls only the idle wait in step 2; the builder reference describes it as the delay in between polling the change feed for new changes, after all current changes are drained[13]. It does not control how often leases are acquired or renewed; those separate settings are covered in Tuning leases against their RU cost.

Step 4 is why the delegate must finish its work before it returns. Microsoft warns that the change feed processor may checkpoint the lease before all asynchronous operations started in the delegate complete, which can lead to missed events[6]. Await every operation the delegate starts and never return while fire-and-forget tasks are still running, or the checkpoint can move past changes whose effects never became durable.

The takeaway: the processor reads, hands each batch to your delegate, and checkpoints only after the delegate returns successfully, so the checkpoint is only as trustworthy as the delegate's awaits.

1. Read the change feedAny changes?NoYes2. SleepWithPollInterval3. Send batchto the delegate4. On success,update the lease
Change feed processor life cycle per host: read, sleep for WithPollInterval when idle, run the delegate, and update the lease only after success.

How the processor handles failures

This section covers what happens when the delegate fails, which is where the processor's reliability promise comes from. If the delegate throws an unhandled exception, the thread processing that batch stops and a new thread is created; the new thread restarts from the latest point in time the lease store saved for that range, effectively sending the same batch to the delegate again, until the delegate processes it correctly[6]. That retry loop is the processor's at-least-once guarantee.

Reconciling "exactly once" and "at least once"

Microsoft's overview says each change appears exactly once in the change feed[1], while the processor promises at-least-once delivery[6]. Both are true because they describe different things: the feed records each change once, but your delegate can receive the same batch more than once after a failure and retry. Any side effect outside Azure Cosmos DB, such as sending an email, adding to a running total, or calling an API, must therefore be safe to apply twice (idempotent) or deduplicated with an identity your application controls. Checkpointing does not make an external effect exactly-once.

The first batch might not be retried

If the failure happens on the first-ever delegate execution, the lease store has no previous saved state to use on the retry, so the retry uses the initial starting configuration, which might or might not include the last batch[6]. It is the documented exception to the retry rule.

Poison batches: record them, neither swallow nor rethrow forever

A change that can never be processed (malformed data, a downstream call that always rejects it) makes the processor retry the same batch endlessly and stalls that range. Microsoft's pattern for this error store (see Choosing push or pull consumption) is to add logic in your delegate to write documents, upon exception, to an errored-message queue, which might be another Azure Cosmos DB container; the exact data store doesn't matter, you simply want the unprocessed changes to be persisted[6]. Catching and discarding the failure instead lets the checkpoint advance but leaves nothing to repair later.

You can also use life cycle notifications to detect underlying failures[6]; at minimum, register the error notification described in Processor life cycle notifications.

The takeaway: design the delegate for redelivery with idempotent effects, persist unprocessable changes to a durable error store, and register the error notification.

Processor life cycle notifications

The processor builder can connect the change feed processor to any relevant event in its life cycle[6], and the recommendation is to at least register the error notification[6]:

Builder method Called when Use it to
WithLeaseAcquireNotification The current host acquires a lease and starts processing it Track which host started work on which lease
WithLeaseReleaseNotification The current host releases a lease and stops processing it Track which host stopped work on which lease
WithErrorNotification The current host encounters an exception during processing Tell an unhandled delegate exception (a ChangeFeedProcessorUserException) from an error reaching the monitored container, such as a network issue

None of these reports how many changes are waiting; that is the change feed estimator's job, covered in Monitoring lag with the change feed estimator.

Where a new processor starts reading

This section covers the start position, a setting that matters only once in a processor's life. By default, when a change feed processor starts for the first time, it initializes the lease container and starts its processing life cycle; any changes that happened before it was initialized for the first time aren't detected[6].

In latest version mode you can choose an earlier start on the builder:

  • .WithStartTime(particularPointInTime) starts reading changes after a specific DateTime.
  • .WithStartTime(DateTime.MinValue.ToUniversalTime()) starts from the beginning of the container's lifetime[6], for data migrations or analysis of the available latest-version changes, not every historical version or deleted item.

These customization options work only to set up the starting point; after the lease container is initialized for the first time, changing these options has no effect[6]. Redeploying an existing processor with a new WithStartTime to force a replay therefore does nothing: it resumes from its saved leases. A replay needs new lease state. A processor with a different processorName gets its own, because each deployment unit maintains an independent state on a shared lease container[6] (the instances sharing one processorName and lease container; see Scaling out with deployment units), and that new processor can then start from the beginning.

In all versions and deletes mode there is no choice: you must start reading from the time the processor is started, or resume from a prior lease state that's within the continuous backup retention period of your account[6] (the start rule from Reading all versions and deletes events).

The takeaway: the start position is read once, when leases are created; to reprocess history, create new lease state rather than changing the start option.

Configuring the lease container

The lease container is the one extra resource the processor needs, so this section covers what it holds and how to create it. A range's progress is maintained separately from other ranges in the lease container through a lease document, and the combination of the leases represents the current state of the change feed processor[6]. Each lease records how far processing has got for one range and which instance owns it. The lease container holds this coordination state, never copies of your business documents, so do not reuse it as the output of a materialized view (a separate container your delegate keeps filled with derived copies of the data, such as orders grouped by customer).

Creating it

Permissions with Microsoft Entra ID

When the processor authenticates with Microsoft Entra ID rather than account keys, the identity needs these data-plane actions[6]. Each action name starts with Microsoft.DocumentDB/databaseAccounts/:

Container Required actions
Monitored container readMetadata, sqlDatabases/containers/readChangeFeed
Lease container sqlDatabases/containers/items/read, .../items/create, .../items/replace, .../items/delete, .../items/executeQuery

The asymmetry is the point: the processor only reads the monitored container's feed, but it creates, replaces, deletes, and queries lease documents.

Keep the global endpoint

Leases are tied to the endpoint the client uses: the change feed processor creates lease documents that are scoped to the configured endpoint, hence changing the endpoints results in the creation of new independent lease documents[6]. Build the CosmosClient for the monitored and lease containers with the account's global endpoint (for example contoso.documents.azure.com), and move traffic between regions with ApplicationRegion or ApplicationPreferredRegions (preferredRegions in Java). Switching to a regional endpoint such as contoso-westus.documents.azure.com does not carry the checkpoint over; it starts a new, independent set of leases.

The takeaway: give the processor an /id-partitioned lease container, reach it through the global endpoint, and grant the identity write access to leases but only feed-read access to the monitored container.

Scaling out with deployment units

This section covers how several processor instances share one workload, and how separate workloads stay separate. A single change feed processor deployment unit consists of one or more compute instances that have the same value for processorName and the same lease container configuration, but different instance names[6]. Within a deployment unit, the processor distributes all the leases across all running instances and parallelizes compute by using an equal-distribution algorithm[6], provided all three conditions hold:

  1. All instances have the same lease container configuration.
  2. All instances have the same processorName.
  3. Each instance has a different instance name (WithInstanceName).

Break condition 2 and you have not scaled out; you have created a second workload. Separate deployment units are how one container feeds several business flows: when a change happens in your monitored container, all your deployment units are notified[6]. They can even share one lease container, because in a shared lease container each deployment unit listens to a different monitored container or has a different processorName, and maintains an independent state[6].

Each deployment unit consists of one or more instances[6] and, in a shared lease container, maintains an independent state on the lease container[6], as the figure below shows. Suppose the monitored container has four physical partitions, so each deployment unit has four leases, numbered 0 to 3 here for illustration. Deployment unit A (processorName sync) runs two instances that split its four leases. Deployment unit B (processorName audit) runs one instance that owns all four of its own leases. Both units read the changes independently; inside unit A, each lease has one owner at a time, but processing is at least once.

The lease count caps useful parallelism

A lease is owned by one instance at any time, so the number of instances shouldn't be greater than the number of leases[6]. With five instances in unit A and four leases, at least one instance would have no lease and sit idle, because two instances cannot own one lease at the same time. The lease count is not fixed, though. The number of instances can grow and shrink while the processor redistributes the load[6], and when the container's throughput or storage grows, the processor dynamically increases the leases and distributes the new leases among existing instances[6].

The takeaway: the same processorName, the same lease container, and unique instance names share one workload; a different processorName is a separate consumer that reads every change again.

Lease container(partition key /id)Deployment unit AprocessorName syncDeployment unit BprocessorName auditInstance 1leases 0, 1Instance 2leases 2, 3Instance 3leases 0 to 3Each unit has its own leasesand reads every change
Two deployment units sharing one lease container: unit A splits its leases across two instances, unit B reads the same changes independently.

Tuning leases against their RU cost

This section covers the request units the push model spends on coordination and the three lease timers that set that spend. Both containers consume throughput: change feed read operations on the monitored container consume request units, and operations on the lease container (updating and maintaining state) consume request units[6]. The higher the number of instances that use the same lease container, the higher the potential consumption of request units[6]. Throttling hurts on both sides: on the monitored container it delays change feed events, and on the lease container it adds delays and can even completely end processing[6]. Adding workers to a throttled lease container can increase lease operations and worsen lease-container throttling. Microsoft sums up the bill this way: the only cost for the change feed is the lease container's provisioned throughput and request units for each request[1], read as two parts: the lease container's throughput plus the RUs every request consumes, including each change feed read on the monitored container.

Three key configurations affect how the change feed processor works, and each one affects the request unit consumption on the lease container[6]. In .NET all three are set with WithLeaseConfiguration(acquireInterval, expirationInterval, renewInterval)[14]:

Setting Default What the host does Lowering it Cost of lowering it
Lease acquire Every 17 seconds Runs a query on the lease container to check lease distribution and consider acquiring leases Rebalances and acquires leases faster More query RUs on the lease container
Lease renewal Every 13 seconds Replaces each lease it owns, even when there are no new changes Detects leases lost by a crashed host sooner More replace RUs on the lease container
Lease expiration 60 seconds Lets a lease go this long without renewal before another host acquires it Recovers faster after a host crash Must never be lower than the renewal interval

Two rows carry common traps. Renewal is a write that happens even if there are no new changes to consume[6], so an idle monitored container still costs lease RUs. And when a host crashes, the leases it owned are picked up by other hosts after the expiration period plus the configured renewal interval[6]; an expiration shorter than renewal would let a healthy owner's lease expire between its own renewals.

Keep these three apart from WithPollInterval, the idle wait between feed reads from How the change feed processor works. Shortening the acquire interval rebalances leases faster but does not make an idle processor look for new changes sooner, and shortening the poll interval does not speed up rebalancing.

The takeaway: budget RUs on both the monitored and lease containers, and treat the three lease intervals as a dial between responsiveness and lease RU cost, with one hard rule: expiration is never lower than renewal.

Monitoring lag with the change feed estimator

This section covers how to tell whether a processor deployment keeps up with its container. A deployment processes changes at a rate set by its CPU, memory, and network, and if this rate is slower than the rate at which your changes happen in your Azure Cosmos DB container, your processor starts to lag behind[15]. The change feed estimator measures that lag: the difference between the last processed item (defined by the state of the leases container) and the latest change in the container[15]. An estimate that keeps growing means changes arrive faster than the deployment processes them.

It must point at the processor it measures

The estimator reads lease state, so it must name the same lease set as the processor: both the processor and the estimator share the same leaseContainer and the same name[15]. An estimator built with a new processor name looks at a different set of leases and reports some other deployment's backlog, or none.

Two ways to read it in .NET

The push form calls your delegate with a number that represents how many changes are pending to be read by the processor[15], at an interval you choose (default 5 seconds). The listing below creates one for the orderSync processor from How the change feed processor works.

A push estimator for the orderSync processor (adapted from Microsoft's sample)

ChangeFeedProcessor estimator = monitoredContainer
    .GetChangeFeedEstimatorBuilder(
        "orderSync",                       // same name as the processor
        HandleEstimationAsync,             // receives the pending-change estimate
        TimeSpan.FromMinutes(1))           // how often to measure
    .WithLeaseContainer(leaseContainer)    // same lease container as the processor
    .Build();
await estimator.StartAsync();

The on-demand form gives more detail. GetChangeFeedEstimator("orderSync", leaseContainer) followed by GetCurrentStateIterator() returns one ChangeFeedProcessorState per lease, with its LeaseToken, its EstimatedLag, and the InstanceName of the instance that owns it, so you can identify if there's an issue on an instance[15] rather than across the whole deployment.

What the number is, and what it costs

Microsoft documents the estimator, like the processor, for .NET and Java.

The takeaway: run one estimator outside the workers, with the processor's own name and lease container, at a modest cadence, and read its output as an approximate backlog.

Reading pages with the pull model

This section covers how a pull-model reader is created and how it knows it has caught up. In .NET you create a FeedIterator with a required ChangeFeedStartFrom value, which holds both the starting position and the FeedRange, and a required ChangeFeedMode value[8], then call ReadNextAsync for each page. A FeedRange is a range of partition key values that limits which items' changes the iterator reads; leave it out to read the whole container.

A .NET pull reader that polls the whole container (adapted from Microsoft's sample)

FeedIterator<Order> iterator = container.GetChangeFeedIterator<Order>(
    ChangeFeedStartFrom.Now(),            // where to start
    ChangeFeedMode.LatestVersion);        // which mode to read

while (iterator.HasMoreResults)           // always true for a change feed
{
    FeedResponse<Order> response = await iterator.ReadNextAsync();
    if (response.StatusCode == HttpStatusCode.NotModified)
    {
        // 304: no new changes right now; wait, then ask again
        await Task.Delay(TimeSpan.FromSeconds(5));
    }
    else
    {
        foreach (Order order in response) { /* process the change */ }
        // ... then persist response.ContinuationToken
    }
}

Reading the listing against the rules:

HTTP 304, not an empty page, means caught up

When there are no new changes, the service answers with HTTP 304 NotModified. This is different than receiving a response with no changes and OK status: you can get empty change feed responses while more changes are available, and you should continue polling until receiving NotModified[8]. The figure below traces the continuous loop. A bounded catch-up job, such as a nightly export, runs the same loop but exits at the first 304 after saving its continuation token; it must not exit at the first empty 200 page.

Page size is a hint that transactions can exceed

ChangeFeedRequestOptions.PageSizeHint sets the maximum number of items received per page, but if operations in the monitored collection are performed through stored procedures, transaction scope is preserved, so the number of items received might be higher than the specified value[8]. Do not size buffers on the assumption that the hint is an absolute ceiling.

The takeaway: create the iterator with an explicit start and mode, keep reading while responses are 200 (even empty ones), and treat 304 as the only caught-up signal.

Create the iteratorReadNextAsync()HTTP 304Not Modified?YesNoWait, thenread again200 OK: processthe pagePersist thecontinuation token
Pull model polling loop in .NET: only HTTP 304 Not Modified means caught up; a 200 OK page, even an empty one, is processed and the token persisted.

What the pull model leaves to your code

The processor stores progress, picks ranges, and spreads work for you; in the pull model those jobs are yours: saving the checkpoint, scoping a reader to one partition key value, and assigning feed ranges to parallel readers, in Python as in .NET.

Continuation tokens are your checkpoint

A continuation token is a string value that keeps track of the iterator's last processed changes and allows it to resume at this point later; if specified, it takes precedence over the start time and start-from-beginning values[8]. Nothing stores it for you, so persist it durably if the reader must survive a restart, and persist it after the page's effects are committed. Saving the new token first and crashing before processing would skip those changes on restart. Token lifetime depends on the mode: in latest version mode the continuation token never expires as long as the container still exists; in all versions and deletes mode it is valid as long as the changes happened within the retention window for continuous backups[8].

A continuation token and a processor lease are both checkpoints, but you can't convert continuation tokens to a lease or vice versa[8]. Moving a consumer from one model to the other needs a deliberate start position and a reconciliation plan, not a copied token.

Python: query_items_change_feed

The Python SDK does the same jobs through container.query_items_change_feed: the reader call, the saved continuation token, and the partition_key scope. The mode parameter takes LatestVersion (the default) or AllVersionsAndDeletes[8], and AllVersionsAndDeletes follows the start rule from Reading all versions and deletes events (now or a continuation token, never start_time). The listing below reads one customer's changes and keeps the checkpoint.

Reading one partition key's changes and saving the checkpoint in Python (adapted from Microsoft's sample)

# ... container is a ContainerProxy obtained from a CosmosClient
# Latest version mode is the default, so no mode argument is needed.
changes = container.query_items_change_feed(
    start_time="Beginning",
    partition_key="c-42",          # one partition key value only
)
for doc in changes:
    handle(doc)                     # your processing

# The feed's etag response header is the continuation token.
continuation_token = container.client_connection.last_response_headers["etag"]

# Later: resume from the bookmark; the token's saved mode wins.
changes = container.query_items_change_feed(continuation=continuation_token)

Two details in this listing deserve attention. The checkpoint is the response's etag header, which is the feed ETag from Working with latest version mode, not any item's _etag. And since the continuation token contains the previously used mode, the mode parameter is ignored when continuation is used, and the mode from the token is used instead[8], so a saved token plus a new mode argument does not switch modes.

Reading one partition key value

Only the pull model can process changes from only a single partition key[8]; Microsoft's comparison marks it "Not supported" for the change feed processor. In .NET pass FeedRange.FromPartitionKey(new PartitionKey("c-42")) inside ChangeFeedStartFrom.Beginning(...) or ChangeFeedStartFrom.Now(...); in Python pass partition_key, as in the listing above.

Parallel readers need an orchestrator

GetFeedRangesAsync returns one FeedRange per physical partition[8], and you can create one iterator per range on different threads or machines. Unlike the processor, nothing assigns the ranges: you need an orchestrator process that obtains FeedRanges and distributes them to the machines[8], for example by serializing each range with FeedRange.ToJsonString and rebuilding it on the worker with FeedRange.FromJsonString. Python's equivalents are read_feed_ranges and the feed_range argument. Starting several whole-container readers instead does not divide the work: each one reads every change.

The takeaway: in the pull model your code owns the checkpoint (persisted after processing), the scope (the whole container, one feed range, or one partition key value), and the assignment of ranges to workers.

How container copy jobs work

Container copy jobs solve a different problem with the same change feed machinery: moving a container's data into a container with different settings. Copy jobs in Azure Cosmos DB (preview)[16] cover these documented scenarios: copying all items from one container to another, changing throughput granularity between database and container, changing a container's partition key (repartitioning), updating unique keys, renaming a container or database, and adopting features supported only for new containers, such as hierarchical partition keys (HPK).

The destination always exists first: create the target container by using the settings that you want to use (partition key, throughput granularity, request units, unique key, and so on), then create the copy job[16]. A job copies data into that container; it does not create it or infer its settings, and job creation fails with "Owner resource doesn't exist" (404) when the target container isn't created yet[16].

Offline copy or online copy

Aspect Offline copy Online copy
Change feed mode the job reads Latest version mode All versions and deletes mode
Source writes during the job Stopped before the job starts Allowed until cutover
Extra source prerequisites None listed Continuous backup, all versions and deletes mode, and the EnableOnlineContainerCopy capability
How it ends Runs to completion; then repoint clients You stop writes and run az cosmosdb copy complete

Offline copy. Stop performing any operations on the source container before you begin the offline job; item deletions and updates made after the job starts might not be captured, and continued operations can leave duplicate or missing data on the target[16]. Offline jobs use latest version change feed mode[16]. They are a point-in-time move, not a live synchronization.

Online copy. Online jobs use all versions and deletes change feed mode to copy the data and replicate incremental changes[16], so the source keeps serving traffic until cutover. The source account needs continuous backup and all versions and deletes mode (from Enabling all versions and deletes mode), then the EnableOnlineContainerCopy capability, added to the account's capability list with az cosmosdb update --capabilities. Wait at least 30 minutes after enabling the EnableOnlineContainerCopy capability before creating an online container copy job[16]. The capability has a write cost: replace and delete operations on the source account incur additional RU charges to retain both the previous and current versions of an item; the surcharge scales with item size from 50 to 100 percent on top of the base write charges, and create operations aren't affected[16].

How the jobs run

The platform allocates server-side compute instances for the destination account to run copy jobs, and a single job executes across all instances at any time[16]. The platform may deallocate those instances after about 15 minutes of inactivity; that is idle clean-up, not a deadline for an active job. An account can hold several jobs, but the jobs run consecutively[16], and copying an entire database requires a job for each container[16].

Three things set a job's speed: the source throughput, the target throughput, and the server-side compute instances the platform allocates; Microsoft advises setting target container throughput to at least two times the source container's throughput[16]. Raising only the source's throughput cannot speed up a job held back by writes to an under-provisioned target. And there's no service-level agreement (SLA) for the time jobs take to finish[16], so plan validation and cutover around the job you observe, not a promised duration.

The takeaway: precreate the target with the new settings, choose offline (writes paused) or online (prerequisites plus a completion step), and expect jobs to run one at a time at a speed set by both containers' throughput.

Running a copy job with the Azure CLI

This section covers the commands, from creating a job to the online cutover. The copy commands come from the Azure Cosmos DB preview extension, installed with az extension add --name cosmosdb-preview, and the account's write region must be one of the supported regions[17].

Creating an online copy job between two accounts (Azure CLI in PowerShell, from Microsoft's how-to)

az cosmosdb copy create `
    --resource-group $sourceAccountRG `
    --job-name $jobName `
    --src-account $sourceAccount `
    --dest-account $destinationAccount `
    --src-nosql database=$sourceDatabase container=$sourceContainer `
    --dest-nosql database=$destinationDatabase container=$destinationContainer `
    --mode Online

In this listing --src-account and --dest-account name the two accounts, and --src-nosql and --dest-nosql name the database and container on each side; database and container names alone do not say which accounts are involved. Microsoft's offline example is the same command without --mode Online. --job-name should be unique for each job within an account[17].

Cross-account copies need an identity grant first

While copying data from one account to another, you need to grant the source account's identity read-write access to the destination account; this step isn't required if you're copying data within the same account[17]. The documented steps assign a system-assigned or user-assigned managed identity to the source account, set it as the account's default identity, and create a role assignment on the destination account with the read-write role definition 00000000-0000-0000-0000-000000000002 at scope /.

Managing a job

Command What it does
az cosmosdb copy show Shows one job's status and progress
az cosmosdb copy list Lists all the copy jobs created in the account
az cosmosdb copy pause Pauses an ongoing job
az cosmosdb copy resume Resumes the job
az cosmosdb copy cancel Cancels the job; use pause, not cancel, for a temporary stop
az cosmosdb copy complete Finishes an online job and writes any remaining changes

Each management command takes --resource-group and --account-name; commands for a single job also take --job-name, while copy list does not, as shown in Microsoft's create and manage copy jobs[17] guide.

The online cutover sequence

In copy show output, Total count is the total number of changes in the source container (total documents plus any new changes), and Processed count is the number of change feed events the copy job has processed[17]. Processed catching up with total does not end the job, because the source is still taking writes. The figure below shows the whole online sequence, and its shaded steps 5 and 6 are the cutover: when the processed count becomes greater than or equal to the total count, turn off any updates on the source container and wait 5 to 10 minutes to flush remaining changes, then run the completion API, which finishes the job, frees compute resources, and writes the remaining changes to the destination[17]. Only then (step 7) point client applications at the destination container.

When the write region changes

A container copy job runs in the account's write region; in an account with multi-region writes it runs in one of the write regions[16]. If the write region changes after a region outage or a manual failover, incomplete copy jobs fail and you need to re-create them; re-created jobs run in the new write region[16]. The fix is a new job, not copy resume.

The takeaway: precreate the target, grant cross-account access when the accounts differ, add --mode Online when the source must stay live, and end an online job only with stop writes, wait, copy complete, and repoint.

1. Enable prerequisites, wait 30 min2. Create the destination container3. copy create --mode Online4. Wait until processed ≥ total5. Stop source writes, wait 5-10 min6. az cosmosdb copy complete7. Point clients at the destination
Online container copy from prerequisites to cutover; the shaded steps 5 and 6 are the stop-writes-and-complete cutover that a caught-up counter does not replace.

Why copy jobs fail or copy surprising data

This section covers the conditions that make a copy job fail outright or finish with data you did not expect.

Eligibility

Repartitioning can create identity collisions

An item is unique by its partition key value plus its id, so a new partition key can turn two valid source items into one destination identity. Microsoft's example: two items with id 101 are distinct under /department because one is in HR and one in Finance, but under a new key /employeeName both become (John Doe, 101), and this conflict results in an insertion error; ensure the new partition key and id combinations are unique across all documents in the destination container[16]. Check uniqueness under the new key before copying; uniqueness under the old key proves nothing.

The new key must also keep each logical partition (all items that share one partition key value) within its size limit: a new partition key whose data exceeds the 20 GB logical partition key size limit fails the job with a 403 error (substatus 1014)[16]. Microsoft points to hierarchical partition keys, with up to three levels, as the way to exceed 20 GB for a first-level key.

Changing an id during an online copy

While using online container copy, if the id field is modified in the source container, the destination container stores two separate documents, each corresponding to the distinct id values[16]. Keep identities stable while a job synchronizes, and include any identity changes in migration validation. This is a different problem from the repartitioning collision above: there, two unchanged identities collide; here, one changed identity leaves a duplicate.

TTL is copied per item, not per container

Item-level TTL values are copied to the destination container and recalculated to preserve the remaining time until expiration; container-level TTL settings aren't copied, so configure them separately on the destination, and copied items follow the destination container's TTL configuration[16].

The takeaway: before a repartitioning copy, check new-key uniqueness and logical partition size; during an online copy, keep id values stable; and set container-level TTL on the destination yourself.

Recognizing change feed scenarios

Under Implement change feed, the Microsoft DP-420 study guide skills measured[2] lists bullets such as 'Differentiate between change feed processor and pull mode models' and 'Implement copy container jobs', and the table below applies them to concrete requirements.

Requirement Choice Why the alternative fails
A Python app must react to the latest state of created and updated items Pull model (query_items_change_feed) or an Azure Functions trigger The change feed processor exists only in the .NET and Java SDKs
A report needs one known customer's changes Pull model scoped to that partition key value The processor cannot be scoped to one partition key value
An audit must capture deletes, including TTL expiries All versions and deletes mode on a continuous backup account Latest version mode never records hard deletes
A second worker must share an existing processor's load Same processorName and lease container, new instance name A new processorName creates a second consumer that reads everything again
A redeployed processor must reprocess from the beginning New lease state (for example a new processor name) started with WithStartTime(DateTime.MinValue.ToUniversalTime()) Start options are ignored once leases exist
Checkpoints advance but some downstream writes never land Await all work inside the delegate Fire-and-forget tasks let the checkpoint move before the work is durable
An external total is double-counted after a failure Make the effect idempotent or deduplicate it The processor delivers at least once
A pull reader stops early and misses changes Keep polling until HTTP 304 Not Modified An empty 200 page does not mean caught up
A processor moved to a regional endpoint lost its checkpoint Global endpoint plus ApplicationPreferredRegions Leases are scoped to the endpoint, so a new endpoint creates new leases
An all versions and deletes reader must backfill history Plan a separate initial load This mode starts only from now or a saved checkpoint
A container's partition key must change while the app stays live Online container copy job into a precreated container Offline copy needs source writes stopped for the whole job

The takeaway: three useful change feed decisions are which mode records what, which consumer exists in which SDK, and where the checkpoint lives.

Push model (Azure Functions trigger or change feed processor) vs pull model

Decision factorPush: Azure Functions triggerPush: change feed processorPull model
Who runs the read loopThe Functions host, using the change feed processor internallyYour own long-running hostsYour code, one request per page
Where progress is savedLease containerLease containerA continuation token your code persists
Spreading work across workersAutomaticAutomatic within a deployment unitManual: your code hands out feed ranges
When no new changes existSame as the processor it hostsWaits for the poll interval (WithPollInterval), then rechecksYour code handles HTTP 304 Not Modified and rechecks
A batch whose handler throwsNot retried; the function moves on to the next changeRetried from the last saved checkpoint (at least once)No built-in guarantee; your code decides
SDKs and languages, latest version modeAll Functions programming models and languages.NET (V3) and Java (V4) SDKs only.NET, Java, Python, and Node.js SDKs
All versions and deletes mode support.NET isolated worker with extension 4.16.1 or later.NET SDK 3.60.0+, Java SDK 4.81.0+.NET SDK 3.60.0+, Java SDK 4.81.0+, Python SDK 4.9.1b1+, Node.js SDK 4.1.0+

Decision tree

One partition key, ownpace, or one-time read?YesNoPull modelWant hosted workers,no infrastructure?YesNoAzure FunctionstriggerApp uses the .NETor Java SDK?YesNoChange feedprocessorPull model(Python, Node.js)All versions and deletes inFunctions: .NET isolated only

Sharp facts the exam loves — give these one last read before exam day.

Cheat sheet

Sharp facts the exam loves — scan these before test day.

Change-feed ordering is guaranteed within a partition key rather than globally

The change feed provides modification ordering per partition-key value, not a total order across all keys. Changes sharing a modification time within transactional or grouped work may be delivered in any order within that group. A consumer combining different partition ranges must not infer one global event sequence from arrival order.

Trap Using arrival order from independent feed ranges as the global business-event order, which has no cross-key ordering guarantee.

2 questions test this
Latest-version mode exposes the newest item state rather than every mutation

Latest-version mode captures creates and updates, but an item updated several times between reads may appear only in its newest version. Hard deletes are not captured, and a deleted item is no longer available from this mode. Use it for maintaining current state when intermediate mutations and delete events are unnecessary.

Trap Using latest-version mode as a complete mutation audit, which can omit intermediate versions and does not record hard deletes.

3 questions test this
A soft-delete marker lets a latest-version consumer observe deletion intent

When a latest-version consumer must react to deletion intent, write a marker such as deleted=true before eventual physical deletion. The marker is an update the feed can expose. If TTL later removes the item, ensure the consumer processes the marker before expiration because the deleted item will disappear from the latest-version feed.

Trap Setting a soft-delete marker and immediately deleting the item before the consumer can read it, which removes the state that latest-version mode exposes.

2 questions test this
A patched item appears in the change feed as an item version rather than a patch diff

Change-feed processing returns the changed document even when the write was a partial Patch. A latest-version consumer receives the full resulting item, not just the list of paths or Increment operations sent by the writer. Process that state accordingly rather than reapplying the original update operation.

Trap Applying the original increment again when processing a patched item from the feed, which mistakes resulting state for an unapplied patch command.

2 questions test this
Different applications can consume the same container in different change-feed modes

A container's change feed can serve multiple independent applications, including applications selecting different modes. Each individual change-feed application reads in one mode. Adding a consumer does not consume and remove events for the other applications as a competing-message queue would.

Trap Deploying a second independent consumer and expecting it to receive only changes the first consumer has not taken, which treats the feed as a destructive queue.

2 questions test this
Latest-version mode supports beginning, time, now, and checkpoint starting positions

A latest-version reader can start from the container's beginning, a specified time, now, or a saved checkpoint. This mode has no fixed history-retention window, but it exposes surviving item states rather than an immutable event archive. Time-based starts have approximately five-second precision.

Trap Treating a beginning read as recovery of every original item version, which latest-version retention does not preserve.

2 questions test this
The response feed ETag sequences the feed while the item ETag identifies an item version

In latest-version responses, item metadata includes _etag and _ts, with _lsn added for change-feed transaction sequencing. The response's feed ETag serves a different purpose from the item's _etag. Do not substitute an item-version ETag for a feed-position bookmark.

Trap Persisting the last item's _etag as the pull reader's continuation token, which confuses item identity with feed progress.

2 questions test this
Latest-version mode does not provide an operation-type filter

Latest-version mode does not directly filter the feed to a specific mutation type. If a workflow needs to distinguish business changes, add a suitable marker to items and inspect it while processing. For native create, replace, and delete metadata, evaluate all versions and deletes mode instead.

2 questions test this
Latest-version change feed is enabled by default for NoSQL accounts

Latest-version change feed is available by default in Azure Cosmos DB for NoSQL. A consumer can use this mode without enrolling the account in the additional feature required for all versions and deletes.

Trap Enabling continuous backup as a prerequisite for a latest-version consumer, because that backup prerequisite belongs to all versions and deletes mode.

Multi-write change-feed ordering uses crts rather than the local write timestamp

In a multi-region write account, _ts records when an item was written in its local region. The crts value records when the absence of a conflict was confirmed or a conflict was resolved in the hub region, and change-feed ordering follows crts. Treat the two timestamps as different stages of a write's progress rather than using _ts to reconstruct the feed sequence.

All versions and deletes mode requires continuous backup and account feature enablement

Use all versions and deletes mode when every intermediate create or update and delete must be observed. This preview mode is supported for NoSQL accounts and requires continuous backup plus enablement of the all-versions-and-deletes account feature. Current documentation describes enabling the feature on an existing account rather than during account creation.

Trap Selecting this feed mode on a periodic-backup account without changing prerequisites, which does not have the required continuous change history.

2 questions test this
All-versions-and-deletes reads are bounded by continuous-backup retention

All versions and deletes mode can read only changes within the account's continuous-backup retention window. Attempting to resume from changes outside that window returns an error. A consumer outage longer than retention cannot be repaired merely by retaining its old continuation token.

Trap Keeping an old token indefinitely as guaranteed access to every historical mutation, which does not extend the account's retained history.

2 questions test this
All versions and deletes mode starts from now or a retained checkpoint

An all-versions-and-deletes reader starts from now or resumes from a valid previous checkpoint within retention. Starting from the container's beginning or from an arbitrary historical timestamp is not supported. Design initial synchronization separately from ongoing retained-change consumption when those start restrictions matter.

Trap Using ChangeFeedStartFrom.Beginning to backfill all-versions-and-deletes history, which that mode does not support.

2 questions test this
Delete records identify the removed item but do not include its previous body

All-versions-and-deletes create and replace records contain the current item image plus metadata such as operationType. A delete record carries identifying metadata including id, partitionKey, and previousImageLSN, not the deleted item's previous body. Retain earlier create or replace versions when downstream logic will need the deleted content.

Trap Reading previousImageLSN as if it were the deleted document's body, which is a reference to earlier sequence progress rather than the image itself.

3 questions test this
TTL delete events are emitted when expired items are purged

All versions and deletes mode captures TTL deletions and includes timeToLiveExpired metadata to distinguish them. The delete event is not guaranteed immediately at the expiration deadline; it appears when the service purges the item. A lifecycle consumer must allow for that background-deletion delay.

Trap Using the feed's TTL delete event as an exact expiration-time timer, which is delayed until physical purge.

3 questions test this
All-versions-and-deletes requests use Gateway regardless of the client's configured mode

Requests to read all versions and deletes mode use Gateway mode even if the SDK client is configured for Direct. Account for that route when planning consumer connectivity. Changing the generic client connection mode does not force this feed operation onto the Direct data path.

Trap Assuming a Direct-configured client makes every all-versions-and-deletes read a backend TCP operation, which this feed mode overrides.

2 questions test this
Partition-merge history can make an account ineligible for all versions and deletes

Current all-versions-and-deletes limitations exclude accounts with partition merge enabled and accounts that have ever merged a partition. Disabling the feature after a merge does not erase that historical restriction. Check eligibility before depending on this mode for an audit workflow.

Trap Disabling partition merge after a previous merge and assuming eligibility is restored, which overlooks the account's merge history.

2 questions test this
All versions and deletes requires a supporting SDK and a change-event response type

The documented .NET support for all versions and deletes begins with SDK 3.60.0, while Python support begins with 4.9.1b1. In .NET, process ChangeFeedItem<T> events so the application can inspect Current and Metadata, instead of treating every event as a plain item T. Delete handling must branch on metadata because a current document is not supplied.

Trap Reusing a plain-item deserializer for every delete event, which does not match the event's metadata-oriented shape.

2 questions test this
Azure Functions change-feed mode support depends on the programming model

The Azure Functions trigger supports latest-version mode across its programming models and languages. All versions and deletes mode requires the .NET isolated worker model with Microsoft.Azure.Functions.Worker.Extensions.CosmosDB version 4.16.1 or later. Select a consumer whose language and extension support the required feed mode rather than assuming generic trigger support covers every mode.

Trap Selecting a Python Functions trigger for all versions and deletes because Python can consume latest-version changes, which does not satisfy the documented .NET isolated-worker requirement for the other mode.

2 questions test this
The processor manages polling and checkpoints while pull mode leaves those responsibilities to the application

Choose the change feed processor when automatic polling, persisted progress, load balancing, and recovery are desired. The pull model gives the application direct control but requires it to manage those responsibilities. Azure Functions change-feed triggers use the processor underneath rather than constituting a third low-level reading mechanism.

Trap Choosing pull mode to avoid writing checkpoint and load-balancing code, which is functionality the processor supplies.

2 questions test this
The change feed processor library is available for .NET and Java rather than Python

The change feed processor is included in the .NET v3 and Java v4 SDK families. Python and Node.js applications use the pull model for direct SDK consumption rather than instantiating this processor library. Select a supported consumption model before porting a processor-based sample to another SDK.

Trap Porting GetChangeFeedProcessorBuilder directly into a Python SDK application, which has no matching processor implementation.

2 questions test this
A processor is built from the monitored container and must be started

For latest-version mode in .NET, call GetChangeFeedProcessorBuilder on the monitored container with a processor name and delegate. Configure WithInstanceName and WithLeaseContainer, call Build, then StartAsync. All versions and deletes uses GetChangeFeedProcessorBuilderWithAllVersionsAndDeletes instead.

Trap Building the processor from the lease container and expecting it to monitor a different data container, which selects the wrong feed source.

2 questions test this
Processor delivery is at least once, so effects should tolerate replay

The processor resumes from persisted lease progress and can deliver a batch again after failure. Make downstream effects idempotent or deduplicate them using a suitable application identity. Automatic checkpointing is not an exactly-once guarantee for effects in another system.

Trap Incrementing an external total unconditionally for every delivered change, which can count a replayed batch twice.

2 questions test this
The processing delegate must finish its work before returning successfully

The processor updates lease progress after the delegate successfully completes. Await all required asynchronous work before returning rather than launching untracked background tasks. Otherwise, the checkpoint can advance before effects are durable and a later failure may leave work unprocessed.

Trap Starting fire-and-forget tasks inside the delegate and returning immediately, which permits checkpoint advancement before the tasks finish.

2 questions test this
Persisting failed changes separately can prevent an endlessly retried poison batch

An unhandled processor-delegate exception causes the affected range to resume from its last persisted point and retry the batch when saved progress exists. If the first-ever delegate execution fails before progress is saved, retry uses the initial starting configuration and might not include that batch. If a change cannot be processed, durably record it in an error queue or container under a deliberate failure-handling policy. Silently swallowing it loses the opportunity to repair it, while continually throwing can stall that range.

Trap Catching and discarding every failed event just to advance the feed, which records no recoverable failure information.

2 questions test this
Processor start-time options affect initial lease creation rather than later resumes

By default, a newly initialized processor starts from its initialization time rather than replaying old data. For latest-version mode, WithStartTime can choose an earlier time, including DateTime.MinValue.ToUniversalTime() for the beginning. Once lease state exists, changing that option does not override the saved progress.

Trap Changing WithStartTime on a processor with existing leases to force a replay, which resumes from persisted lease state instead.

2 questions test this
Keep a global endpoint when changing a processor's preferred region

Use the account's global endpoint for the client serving a change feed processor and change ApplicationRegion or ApplicationPreferredRegions to redirect regional traffic. Processor lease identity is scoped to the configured endpoint. Replacing the global endpoint with a different regional endpoint can create independent lease documents instead of preserving progress.

Trap Changing the client to a region-specific endpoint to retain the same processor checkpoint, which changes the endpoint-scoped lease identity.

2 questions test this
The Azure Functions trigger supplies change-feed processing without self-managed workers

Choose the Azure Functions change-feed trigger when processor-based scaling and reliable change detection are wanted without maintaining worker infrastructure. Implement the function's processing logic while the hosted trigger supplies the worker integration. This is a hosted consumption choice, not a different change-feed data model.

Trap Choosing a custom pull reader solely to avoid hosting processor workers while still requiring automatic polling and balancing, which leaves those responsibilities with the application.

1 question tests this
WithPollInterval controls the processor's wait after finding no changes

Configure WithPollInterval on the change feed processor builder to set how long it waits before checking again when no changes are available. This tunes idle polling responsiveness and the associated read work. It is separate from the intervals used to acquire or renew leases.

Trap Shortening the lease-acquisition interval to control empty-feed polling, which changes lease distribution checks rather than the processor's no-change wait.

2 questions test this
Processor lifecycle handlers report lease acquisition and release

Register WithLeaseAcquireNotification and WithLeaseReleaseNotification handlers when an application needs to observe a processor host starting or stopping work on a lease. These notifications identify ownership transitions during processor operation. They do not measure the number of unprocessed changes.

Trap Using the change-feed backlog estimator as a lease-transition callback, which reports estimated progress lag rather than acquisition and release events.

2 questions test this
WithErrorNotification exposes processor errors for source-aware handling

Register WithErrorNotification to observe exceptions encountered by the change feed processor host. The handler can distinguish an unhandled user-delegate failure from a failure accessing the monitored container, such as a connectivity error. Use that distinction to investigate the processing code or the source-access path appropriately.

2 questions test this
Lease documents persist progress and coordinate ownership for feed ranges

A processor's lease container stores per-range progress and ownership rather than copies of the business documents. Each range advances separately, and the complete set of leases represents processor progress. WithLeaseContainer selects that state store in the .NET builder.

Trap Using the lease container as the destination for the application's materialized business view, which confuses coordination state with processing output.

2 questions test this
A partitioned lease container uses id as its partition key

Create a partitioned lease container with the /id partition-key definition required for lease storage. The lease container may be in the monitored account or a different account. It need not share the business data's partition-key path.

Trap Copying the monitored container's /tenantId partition-key definition to the lease container, which does not meet the lease document layout.

2 questions test this
Cooperating processor instances share a processor name but have distinct instance names

Instances in one deployment unit use the same processorName and lease-container configuration, with a unique WithInstanceName value for each instance. That shared identity lets the library distribute leases between them. Independent workflows can instead share the lease container with different processor names, giving each its own progress rather than making their workers cooperate on one checkpoint set.

Trap Giving every scale-out worker a different processorName, which creates independent consumers instead of sharing one processing workload.

2 questions test this
Useful processor parallelism is bounded by the available leases

A lease has only one owner at a time within a deployment unit. Adding workers beyond the lease count does not create more independently assignable ranges. The processor redistributes leases as workers join or leave and creates additional lease work as the monitored container splits.

Trap Adding more worker instances than leases to split one lease among them simultaneously, which violates exclusive lease ownership.

2 questions test this
Both feed reads and lease maintenance need sufficient throughput

Reading the monitored container consumes RUs, and maintaining lease ownership and checkpoints consumes RUs in the lease container. Throttling either resource can delay processing; lease throttling can even stop it. More workers increase potential lease-maintenance demand rather than providing cost-free parallelism.

Trap Increasing worker count to solve a throttled lease container without adding coordination capacity, which can increase its maintenance load.

2 questions test this
A shorter lease-acquisition interval accelerates balancing at additional RU cost

The default lease-acquisition interval is 17 seconds. At each acquisition check, a host queries lease state to assess distribution and possible ownership changes. Reducing the interval makes rebalancing more responsive but increases lease-container query work.

Trap Reducing the feed poll interval to accelerate lease balancing, which controls feed polling rather than ownership-acquisition checks.

2 questions test this
Lease renewal writes occur even when there are no new business changes

A host renews owned leases by replacing lease documents, with a default renewal interval of 13 seconds. These writes continue even when the feed has no new data. Reducing the interval increases coordination work and must remain compatible with the lease-expiration interval.

Trap Budgeting zero lease-maintenance RUs during an idle monitored workload, which still requires ownership renewals.

1 question tests this
Lease expiration governs when another host can recover abandoned work

The default lease-expiration interval is 60 seconds. After a host stops renewing a lease, another host can acquire it once expiration and the relevant checking intervals allow. A shorter expiration can improve recovery speed, but it must not be set below the renewal interval.

Trap Setting expiration shorter than normal lease renewal to speed recovery, which lets an actively owned lease expire between renewals.

2 questions test this
Pull mode can read changes for one partition-key value

Choose pull mode when a consumer needs only one customer's partition-key changes rather than the whole container. In .NET, provide FeedRange.FromPartitionKey with the chosen ChangeFeedStartFrom value; Python accepts partition_key on query_items_change_feed. The change feed processor does not offer single-partition-key processing.

Trap Selecting the processor for a report that must consume only one known customer's partition feed, which does not support that scope.

2 questions test this
HTTP 304 means no current changes while an empty HTTP 200 page does not

A change-feed pull iterator represents an ongoing feed, so HasMoreResults remains true. When no new changes are currently available, the service returns HTTP 304 NotModified; the application can wait and poll again or end a bounded catch-up read. An empty HTTP 200 page is not sufficient evidence that the feed is caught up.

Trap Ending a catch-up read at the first empty HTTP 200 page, which can leave subsequent changes unread.

2 questions test this
Pull consumers should persist their continuation only after processing the corresponding changes

Pull mode exposes a continuation token that bookmarks the iterator's progress and must be persisted by the application when restart recovery is required. Persist it after completing the associated processing so restart does not skip unfinished work. A latest-version change-feed token remains valid while its container exists; all-versions-and-deletes history remains subject to retention.

Trap Saving a newly received token before committing the page's processing effects, which can skip those effects after a crash.

2 questions test this
Pull-mode parallelism requires distributing FeedRanges explicitly

GetFeedRangesAsync returns ranges corresponding to the container's physical partitions. A pull application can create an iterator per range and distribute them to threads or machines, but it must coordinate that assignment itself. The processor supplies automatic range balancing when that custom control is unnecessary.

Trap Starting multiple whole-container pull readers and assuming they automatically divide the workload, which duplicates reads instead of assigning ranges.

2 questions test this
Pull continuation tokens and processor leases are not interchangeable checkpoints

A pull continuation token and a processor lease both track progress, but they cannot be converted into one another. Switching consumption models therefore needs a deliberate starting and reconciliation strategy. Copying a token into a lease document is not a supported way to preserve exact progress.

Trap Migrating a pull reader to the processor by inserting its token as lease state, which relies on an unsupported checkpoint conversion.

2 questions test this
Change-feed PageSizeHint can be exceeded to preserve transaction scope

ChangeFeedRequestOptions.PageSizeHint influences how many changes a pull response should contain. When preserving stored-procedure transaction scope requires returning a larger atomic group, the response can exceed that hint. Do not size a consumer's buffers on the assumption that the hint is an absolute maximum.

Trap Allocating a fixed buffer exactly equal to PageSizeHint for every response, which can be exceeded by an indivisible transaction group.

2 questions test this
A Python change-feed continuation preserves the previously selected mode

Python uses container.query_items_change_feed to consume changes and supports mode values LatestVersion and AllVersionsAndDeletes. A supplied continuation takes precedence over initial starting settings. Because the continuation contains the previously used mode, supplying it causes that mode to be used rather than a conflicting new mode argument.

Trap Reusing a saved Python token while changing only mode to switch feed modes, which continues in the token's recorded mode.

2 questions test this
GetChangeFeedIterator constructs a typed pull reader with a starting position and mode

In .NET, construct a typed pull reader with container.GetChangeFeedIterator<T>, supplying ChangeFeedStartFrom and ChangeFeedMode. These arguments choose where consumption starts and which feed mode is read. Consume the returned feed iterator with ReadNextAsync.

Trap Using GetItemQueryIterator to create a change-feed consumer, which executes item queries rather than reading the selected feed mode.

2 questions test this
GetChangeFeedStreamIterator reads change-feed responses without typed deserialization

Use container.GetChangeFeedStreamIterator with the chosen ChangeFeedStartFrom and ChangeFeedMode when the application needs response streams rather than deserialized entity objects. The stream form allows custom processing without first constructing typed payload objects. Use GetChangeFeedIterator<T> when typed results are wanted.

Trap Choosing GetItemQueryStreamIterator merely because it returns streams, which uses the item-query path rather than the change-feed path.

2 questions test this
The change-feed estimator reports pending-change lag rather than an exact processing-time delay

Use the change-feed estimator to assess how far processor progress lags behind the container's latest changes. It estimates pending changes for both feed modes and is not guaranteed to be an exact outstanding-event count. A growing estimate indicates that arrival rate exceeds the deployment's sustained processing capacity.

Trap Interpreting EstimatedLag as milliseconds of guaranteed processing latency, which measures an approximate pending-change backlog instead.

2 questions test this
An estimator must use the processor's name and lease configuration

To measure a particular deployment unit, create its estimator with the same processor name and lease container. A push estimator can notify a delegate at a chosen interval, with a documented default interval of five seconds. Different processor identities represent different saved progress and therefore different backlog estimates.

Trap Giving the estimator a new processor name to distinguish it operationally, which points it away from the checkpoint set being measured.

2 questions test this
On-demand estimation identifies each lease's lag and current owner

Use GetChangeFeedEstimator and GetCurrentStateIterator for detailed on-demand state in .NET. Each ChangeFeedProcessorState includes the lease token, EstimatedLag, and InstanceName of its owner. This distinguishes an isolated stalled range or host from a broadly underpowered deployment.

Trap Using only one aggregate backlog number to identify the responsible worker, which omits the per-lease ownership information.

2 questions test this
One independent estimator can monitor the deployment but its measurements consume RUs

The estimator can run independently of the processor deployment, and one instance can monitor all its leases and workers. Each measurement consumes RUs from the monitored and lease containers. Increasing measurement frequency adds database work, so choose a cadence appropriate to the operational need.

Trap Running a high-frequency estimator on every worker as a requirement for monitoring, which duplicates work that one independent estimator can perform.

2 questions test this
A copy job needs an existing destination container with the desired new settings

Create the destination container before starting a copy job, with the desired partition key, unique keys, throughput granularity, and other settings. Copy jobs support changes that cannot be applied in place, including repartitioning or adopting HPK. The job copies data into that configured resource rather than editing the source definition.

Trap Starting a copy job expecting it to create the destination and infer its new partitioning policy, which requires the target to exist first.

2 questions test this
Offline copy requires source operations to stop before the job starts

For an offline copy, pause applications and clients operating on the source, start the job, and wait for completion before resuming against the intended container. Offline copy uses latest-version change feed. Updates and deletes made after the job starts may not be captured reliably, so it is not a live synchronization contract.

Trap Continuing source writes throughout an offline copy and assuming cutover consistency, which can leave missing or duplicate destination data.

1 question tests this
Online copy adds incremental change capture after its source prerequisites are enabled

Online copy uses all versions and deletes change feed to replicate incremental changes while copying. The source needs continuous backup, the all-versions-and-deletes feature, and the EnableOnlineContainerCopy capability. Wait at least 30 minutes after enabling that capability before creating the online job.

Trap Selecting --mode Online on a source without all-versions-and-deletes readiness, which omits the change history the online mechanism needs.

2 questions test this
Online-copy cutover requires stopping source updates and explicitly completing the job

When processed count catches up with total count, stop source updates and allow the documented five-to-ten-minute flush interval. Call az cosmosdb copy complete to finish the online job and flush remaining changes, then redirect clients as required. A temporarily caught-up counter is not itself the final cutover operation.

Trap Redirecting writes as soon as processed count matches total count while the source remains active, which skips the controlled stop-and-complete cutover.

2 questions test this
Copy speed depends on source capacity, destination capacity, and allocated copy compute

A copy job reads using source throughput and writes using destination throughput, with platform-allocated server-side compute also limiting progress. Documentation recommends target throughput of at least twice the source throughput. Increasing only one side cannot remove a bottleneck on the other side or in the copy workers.

Trap Scaling only source throughput to accelerate a destination-throttled copy, which leaves its write bottleneck unchanged.

2 questions test this
Copy jobs have distinct CLI commands for creation, inspection, pausing, and cancellation

Install the cosmosdb-preview Azure CLI extension to use the documented copy commands. Use az cosmosdb copy create with --src-nosql and --dest-nosql database/container identifiers, show for one job, and list for the account's jobs. Pause and resume preserve an ongoing job, while cancel abandons it; --mode Online explicitly selects online copying.

Trap Using cancel as a temporary pause before resuming the same job, which confuses abandonment with pause and resume.

2 questions test this
Copy jobs run consecutively within an account and operate at container scope

An account can contain several copy jobs, but they execute consecutively rather than all running simultaneously on independent worker sets. Copying an entire database requires a job for each container. Job names must be unique within the account.

Trap Creating many jobs in one account to force simultaneous copy-worker execution, which the consecutive scheduling model does not provide.

2 questions test this
Copy jobs preserve remaining item TTL but do not copy the container TTL policy

Copy jobs copy item-level TTL values and recalculate them to preserve remaining time until expiration. Container-level TTL settings are not copied and must be configured independently on the destination. Copied items then follow the destination's container-level TTL configuration.

Trap Assuming copied items automatically enable the source's default TTL policy on the target, which is not copied with the data.

2 questions test this
Repartitioning can make previously valid item identities collide

Before copying to a different key, check that every destination partition-key and id combination is unique. Items with the same id in separate source partitions can map to one destination partition and cause an insertion conflict. New-key groups must also remain within full logical-partition storage limits.

Trap Checking uniqueness only under the source partition key before repartitioning, which can miss identities that collide in the new layout.

2 questions test this
Partition merge is an eligibility constraint for copy jobs

Current copy-job preview limitations exclude accounts with merge partition enabled. Check capability compatibility before scheduling a migration that relies on these jobs. A supported container layout does not by itself establish that the account is eligible for the preview service.

2 questions test this
Online-copy enablement adds source replace and delete RU overhead

The documented EnableOnlineContainerCopy mechanism retains previous and current versions for source replace and delete operations. Those operations incur an additional size-dependent RU surcharge documented as 50 to 100 percent over base write charges; creates are unaffected. Budget source capacity for that added work during the online-copy design.

Trap Sizing online-copy source writes using only their original replace and delete charges, which omits version-retention overhead.

2 questions test this
Copy-job eligibility depends on support in the account's write region

A container copy job runs in a write region, and the account's write-region placement must meet the preview's supported-region requirements. For a multi-write account, the job runs in one of its write regions. Check the current supported-region list before relying on otherwise valid source and destination settings.

2 questions test this
A write-region change fails incomplete copy jobs

When an account's write region changes, its incomplete container copy jobs fail. Recreate those failed jobs so they execute in the new current write region.

Trap Issuing copy resume after a write-region change has failed the job, which does not recreate it in the new write region.

2 questions test this
Cross-account copy creation identifies both source and destination accounts

The documented az cosmosdb copy create command identifies the accounts with --src-account and --dest-account. Its --src-nosql and --dest-nosql values then identify the database and container on each side. Database and container names alone do not specify a cross-account copy route.

2 questions test this
Cross-account copy requires destination access for the source account's selected identity

Before starting a cross-account copy job, configure the source account's selected managed identity with the documented read-write access to the destination account. The setup can use a system-assigned or user-assigned identity. This cross-account authorization prerequisite is unnecessary for a copy within the same account.

2 questions test this
Changing source identity during online copy can leave separate destination documents

During online container copy, changing an item's source id can leave two destination documents corresponding to the distinct id values. Keep identities stable during synchronization and include identity changes in migration validation. This issue differs from two unchanged source identities colliding under a new destination partition key.

Container copy jobs have no guaranteed completion-time SLA

Container copy jobs currently operate on a best-effort basis without an SLA for how long they take to finish. Plan validation and cutover around observed job completion rather than a promised fixed migration duration.

2 questions test this
The platform can release copy compute after about fifteen minutes of inactivity

The platform allocates server-side compute for copy jobs and can deallocate idle instances after approximately 15 minutes. That interval describes idle worker cleanup, not a deadline for finishing an active copy job.

Also tested in

References

  1. https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed
  2. https://learn.microsoft.com/en-us/credentials/certifications/resources/study-guides/dp-420
  3. https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-modes
  4. https://learn.microsoft.com/en-us/azure/cosmos-db/continuous-backup-restore-introduction
  5. https://learn.microsoft.com/en-us/azure/cosmos-db/online-backup-and-restore
  6. https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-processor
  7. https://learn.microsoft.com/en-us/azure/cosmos-db/partial-document-update
  8. https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-pull-model
  9. https://learn.microsoft.com/en-us/azure/cosmos-db/merge
  10. https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/sdk-connection-modes
  11. https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-functions
  12. https://learn.microsoft.com/en-us/azure/cosmos-db/read-change-feed
  13. https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.changefeedprocessorbuilder
  14. https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.changefeedprocessorbuilder.withleaseconfiguration
  15. https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-use-change-feed-estimator
  16. https://learn.microsoft.com/en-us/azure/cosmos-db/container-copy
  17. https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-container-copy