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]
- Changes to customer
c-42arrive in the order they were made, but a change toc-42and a change toc-77can arrive in either order. Arrival order across partition key values, or across separately read ranges of the feed, is not a business event order. - Items written in one transactional batch, stored procedure, or bulk mode request have the same modification time, and changes within that scope may be delivered in any order[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
- 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.
- 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": truein the accountpropertiesthrough the REST API, with preview API version2024-12-01-previewor 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
- Partition merge history. Partition merge is a preview feature that merges physical partitions[9] to reduce their number. Accounts that have ever merged a partition, or currently have partition merge enabled, aren't supported[3], so turning merge off afterward does not restore eligibility for an account that has already merged.
- Retention window. Only changes within the retention window for continuous backups can be read; attempting to read changes outside it results in an error[3]. Microsoft's example: a container created eight days ago on an account with seven-day retention exposes only the last seven days. A consumer that stays down longer than retention cannot catch up just by keeping its old checkpoint.
- Gateway mode for every request. The SDKs connect in one of two modes: Gateway mode routes requests through a gateway server, and Direct mode connects directly to the backend replicas[10]. Regardless of the connection mode configured in your application, all requests made with all versions and deletes change feed use Gateway mode[3], so a client configured for Direct mode still reaches this feed through the gateway.
- No previous image. Receiving the previous version of items that were deleted or updated isn't currently available[3].
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:
operationTypeiscreate,replace, ordelete, so a consumer can branch on the kind of change.lsnis the batch ID (many items can share one), andcrtsis the conflict-resolved timestamp from What the change feed records.previousImageLSN, present on replace and delete events, is the batch ID of the change prior to this one[3]. It is a number pointing at an earlier position in the feed, not the deleted item's body.- There is no
currenton a delete, only identifying fields (idandpartitionKey). If downstream logic needs the deleted content, it must have kept that item's earlier create or replace event itself. timeToLiveExpiredistruewhen TTL caused the delete. Deletes from TTL expirations aren't guaranteed to appear in the feed immediately after the item expires; they appear when the item is purged from the container[3], so the event is not a precise expiry timer.
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:
- 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].
- 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].
- 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]:
- The monitored container: the container whose changes you read.
- The lease container: acts as state storage and coordinates the processing of the change feed across multiple workers[6] (detailed in Configuring the lease container).
- The compute instance: the host running the processor, such as a virtual machine (VM), a Kubernetes pod, or an Azure App Service instance, identified by a unique instance name.
- The delegate: your code that handles each batch of changes.
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 entry point for both modes is always the monitored container[6]:
GetChangeFeedProcessorBuilderis called onorders, and the lease container only goes in throughWithLeaseContainer. Calling the builder on the lease container would make the lease documents the data being monitored. processorNameis a distinct name that describes the goal of this processor[6]. It identifies the workload, whileWithInstanceNameidentifies the host.Build()only creates the processor; nothing is read untilStartAsync()runs. For all versions and deletes mode, callGetChangeFeedProcessorBuilderWithAllVersionsAndDeletesinstead[6], with a delegate that takesChangeFeedItem<T>.
The processing life cycle
The normal life cycle of a host instance[6] is a four-step loop, which the figure below traces:
- Read the change feed.
- If there are no changes, sleep for the poll interval set with
WithPollInterval, then go back to step 1. - If there are changes, send them to the delegate.
- 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.
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 specificDateTime..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
- Partition key
/id. Partitioned lease containers are required to have a/idpartition key definition[11]. The lease container does not copy the monitored container's partition key: a monitored container partitioned on/tenantIdstill gets a lease container on/id. - Location. The lease container can be stored in the same account as the monitored container or in a separate account[6].
- Who creates it. With the processor library you create it and pass it to
WithLeaseContainer. The Azure Functions trigger can create the lease container automatically when you set theCreateLeaseContainerIfNotExistsproperty, or you can create it manually[11]. - In-memory leases.
WithInMemoryLeaseContainerkeeps lease state in memory instead, and using an in-memory container restricts the scaling capability to just the instance running the current processor[13].
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:
- All instances have the same lease container configuration.
- All instances have the same
processorName. - 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.
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
- It is an approximate count of pending changes, not a time: in both change feed modes, the estimate provided isn't guaranteed to be an exact count of outstanding changes to process[15].
EstimatedLagis not milliseconds of delay. - The estimator doesn't need to be deployed as part of your change feed processor; Microsoft recommends an independent instance, and a single estimator instance can track the progress for all the leases and instances in the deployment[15]. Running one on every worker only multiplies the cost.
- Each estimation consumes request units from your monitored and lease containers, and a frequency of 1 minute in between is a good starting point[15]; shorter intervals consume more RUs.
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:
GetChangeFeedIterator<T>orGetChangeFeedStreamIterator. The typed method returns deserializedTobjects.GetChangeFeedStreamIteratorreturnsStreamresponses, which let you read data without having it first deserialized, saving client resources[8]. Both take the sameChangeFeedStartFromandChangeFeedModearguments. Neither is interchangeable withGetItemQueryIteratororGetItemQueryStreamIterator, which run queries, not change feed reads.ChangeFeedMode.LatestVersion. For SDK versions earlier than 3.34.0 the same mode is set withChangeFeedMode.Incremental; both refer to latest version mode[8]. For all versions and deletes mode useChangeFeedMode.AllVersionsAndDeletes, start fromChangeFeedStartFrom.Now()or a continuation token (the start rule from Reading all versions and deletes events), and type the iterator asChangeFeedItem<T>.HasMoreResultsnever turns false. Because the change feed is effectively an infinite list of items that encompass all future writes and updates, the value ofHasMoreResultsis alwaystrue[8].
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.
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.
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
- Partition merge. Container copy jobs don't work with accounts that have merge partition enabled; disable it before you run container copy jobs[16]. Online copy also inherits the stricter all versions and deletes rule from Enabling all versions and deletes mode: an account that has ever merged a partition is not supported.
- Region. Container copy is supported only in the listed regions[16], and it is the account's write region that must be on the list. Check the current list before planning a migration around a job.
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 factor | Push: Azure Functions trigger | Push: change feed processor | Pull model |
|---|---|---|---|
| Who runs the read loop | The Functions host, using the change feed processor internally | Your own long-running hosts | Your code, one request per page |
| Where progress is saved | Lease container | Lease container | A continuation token your code persists |
| Spreading work across workers | Automatic | Automatic within a deployment unit | Manual: your code hands out feed ranges |
| When no new changes exist | Same as the processor it hosts | Waits for the poll interval (WithPollInterval), then rechecks | Your code handles HTTP 304 Not Modified and rechecks |
| A batch whose handler throws | Not retried; the function moves on to the next change | Retried from the last saved checkpoint (at least once) | No built-in guarantee; your code decides |
| SDKs and languages, latest version mode | All 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
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
- You have an Azure Cosmos DB for NoSQL account named account1. A container named orderEvents is partitioned by /eventId, which is unique for every event. A change feed consumer must process the events
- You have an Azure Cosmos DB for NoSQL account named account1. An application writes an order header and its line items to a container named orders in one transactional batch for the same partition key
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A cache service reads a container named products in latest version mode and copies each changed item into a key-value cache. Product manag
- You have an Azure Cosmos DB for NoSQL account named account1. A container named shipments is read by a change feed processor in latest version mode every 30 seconds. An item's status changed from pack
- You have an Azure Cosmos DB for NoSQL account named account1. A container named reservations is read by a change feed processor in latest version mode that polls every five minutes. A customer created
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses periodic backup. A container named profiles is synchronized to a search index by a change feed processor in latest version mode.
- You have an Azure Cosmos DB for NoSQL account named account1. To signal deletions to a latest version consumer, code for a container named accounts first patches deleted=true onto an item and then imm
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A search indexer reads a container named articles in latest version mode and expects complete documents. To reduce payload sizes, the writ
- You have an Azure Cosmos DB for NoSQL account named account1. A writer updates items in a container named products by using partial document update with an Increment operation on /stock. A latest-vers
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A container named orders already has a fulfillment application that reads its change feed. The analytics team plans a second application w
- You have an Azure Cosmos DB for NoSQL account named account1. One .NET worker for a container named assets must backfill a projection from the beginning of the container and must also record every del
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses periodic backup. A container named catalog has existed for three years. A new reporting projection must be built from every item
- You have an Azure Cosmos DB for NoSQL account named account1. A latest version pull reader for a container named trades is configured with ChangeFeedStartFrom.Time set to exactly 09:30:00 UTC so that
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A Python worker reads a container named orders with query_items_change_feed in latest version mode. After each run it must persist a bookm
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET change feed consumer for a container named tickets updates each received ticket with an escalation flag. Another service can modify
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A container named orders is read by a latest version change feed processor. A notification function must react only when an order's status
- You have an Azure Cosmos DB for NoSQL account named account1 that uses continuous backup and is enabled for all versions and deletes mode. A billing consumer for a container named subscriptions must c
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that was created with the continuous 30-day backup tier. A .NET 3.60.0 application calls GetChangeFeedIterator with ChangeFeedMode.AllVersi
- You have an Azure Cosmos DB for NoSQL account named account1 that uses periodic backup. An auditing service must read every create, every intermediate update, and every delete in a container named ord
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses the continuous 7-day backup tier. A Python worker reads a container named payments with query_items_change_feed in AllVersionsAnd
- You have an Azure Cosmos DB for NoSQL account named account1 that uses the continuous 7-day backup tier. A compliance consumer reads a container named claims in all versions and deletes mode and store
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 with continuous backup and all versions and deletes mode enabled. A Java change feed processor in all versions and deletes mode already pro
- You have an Azure Cosmos DB for NoSQL account named account1 that is enabled for all versions and deletes mode. A brand-new .NET worker with no saved continuation token is assigned one FeedRange, stor
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A container named invoices is read in all versions and deletes mode by an archiving service. When an invoice is deleted, the service must
- You have an Azure Cosmos DB for NoSQL account named account1. An application reads a container named orders, partitioned by /customerId, in all versions and deletes mode. When an order is deleted, the
- You have an Azure Cosmos DB for NoSQL account named account1. A Python worker reads a container named profiles with query_items_change_feed in AllVersionsAndDeletes mode and receives each change as a
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A container named sessions has a default TTL of 3,600 seconds, and users can also sign out, which deletes their session item. An auditing
- You have an Azure Cosmos DB for NoSQL account named account1. Items in a container named carts expire through TTL, and a cleanup service reads all versions and deletes events to release reserved stock
- You have an Azure Cosmos DB for NoSQL account named account1 that uses provisioned throughput. A container named tokens expires items with TTL, and a security service reads all versions and deletes ev
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET service shares one CosmosClient configured for Direct mode for low-latency point reads and adds an all versions and deletes reader
- You have an Azure Cosmos DB for NoSQL account named account1. One .NET service uses a single CosmosClient created with the SDK's default connection mode for point reads and also reads a container name
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. While the account used periodic backup, an engineer enabled partition merge, merged two fragmented containers, and then disabled the merge
- You have four Azure Cosmos DB for NoSQL accounts that use periodic backup. account1 has partition merge enabled, account2 merged a container last year and then disabled merge, account3 has never enabl
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that is enabled for all versions and deletes mode. You are completing this .NET code for a container named orders: FeedIterator<TARGET> it
- You have an Azure Cosmos DB for NoSQL account named account1 that is enabled for all versions and deletes mode. A .NET application that references Microsoft.Azure.Cosmos 3.45.0 reads a container named
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 with continuous backup and all versions and deletes mode enabled. A .NET isolated worker Azure Functions app references Microsoft.Azure.Fun
- You have an Azure Cosmos DB for NoSQL account named account1 with continuous backup and all versions and deletes mode enabled. A team maintains Azure Functions apps written in Python and wants a new C
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A team replaced a .NET change feed processor that reads a container named orders with change feed pull model iterators, so that it control
- You have an Azure Cosmos DB for NoSQL account named account1. An architect describes three independent ways to read a container named events: the change feed processor, the pull model, and an Azure Fu
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A Python team must port a .NET sample that uses GetChangeFeedProcessorBuilder to read a container named readings. The Python service must
- You have an Azure Cosmos DB for NoSQL account named account1. Four teams plan to consume the change feed of a container named orders: one uses the .NET v3 SDK, one the Java v4 SDK, one the Python SDK,
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. In a .NET worker service, the constructor calls GetChangeFeedProcessorBuilder<Item>("inventoryProc", HandleAsync) on a container named inv
- You have an Azure Cosmos DB for NoSQL account named account1 with containers named orders and leases. A developer wrote leasesContainer.GetChangeFeedProcessorBuilder<Order>("ordersProc", HandleChanges
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed processor for a container named payments sends a confirmation email for each changed item. After the delegate threw an unhan
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed processor delegate for a container named payments adds each payment amount to a daily total in another container. After a ho
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. You are reviewing a .NET change feed processor for a container named stock, and you must explain to the team at what point in the processi
- You have an Azure Cosmos DB for NoSQL account named account1. A processor delegate for a container named orders starts Task.Run(() => PublishAsync(change)) for each change and returns immediately to k
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. One malformed document in a container named invoices makes a processor delegate throw an unhandled exception every time its batch is deliv
- You have an Azure Cosmos DB for NoSQL account named account1. A brand-new change feed processor for a container named orders started with default settings, and its very first delegate execution threw
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. You are deploying a new change feed processor in latest version mode, with a new processor name and an empty lease container, to build a f
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed processor for a container named sales has run in latest version mode for six months. To reprocess last week's changes, a dev
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 replicated to West US 2 and East US 2. A .NET change feed processor for a container named orders runs in East US 2 but reads through West U
- You have two Azure Cosmos DB for NoSQL accounts named account1 and account2, each replicated to West US 2 and East US 2. A new .NET change feed processor monitors a container in account1 and stores it
- 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.
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET processor for a container named archive, which receives only a few changes per hour, issues frequent empty change feed reads that c
- You have an Azure Cosmos DB for NoSQL account named account1. A container named alerts is quiet for long periods, and after a quiet spell the first new change takes noticeably longer than expected to
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. Operators of a change feed processor for a container named shipments want an alert each time a lease moves between hosts during scale-out
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET change feed processor for a container named carts keeps a per-lease in-memory cache on each host. Whenever a host stops processing
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET change feed processor for a container named devices sometimes stops making progress, and nothing appears in the logs because the de
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET change feed processor for a container named invoices registers WithErrorNotification. Operators want errors thrown by the team's ow
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed processor for a container named telemetry uses a lease container named leases that was configured with WithLeaseContainer. A
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET change feed processor that runs on three instances reads a container named orders and writes a summary per customer to a container
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A container named orders is partitioned by /tenantId. You are manually creating a partitioned lease container for an Azure Functions trigg
- You have two Azure Cosmos DB for NoSQL accounts named account1 and account2. A container named orders in account1 runs near its provisioned RU/s, and the team doesn't want lease maintenance traffic to
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
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET change feed processor for a container named orders must scale out from one virtual machine to three virtual machines. The three ins
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed processor named fulfillment reads a container named orders and uses a lease container named leases. You are adding an email
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed processor deployment for a container named iotData runs eight instances, and the container's storage and throughput have dou
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed processor deployment for a container named events has six leases. To speed up processing, operators started ten instances wi
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed deployment of 30 instances reads a container named orders, and its lease container is provisioned at 400 RU/s. The lease con
- You have an Azure Cosmos DB for NoSQL account named account1. You are estimating the cost of adding a change feed processor to a container named catalog, which already has provisioned throughput for i
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. Operators add instances to a change feed processor deployment for a container named orders during sales events. New instances take up to a
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET processor for a container named devices calls WithLeaseConfiguration and lowers acquireInterval from the default of 17 seconds to 5
- 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.
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A processor for a container named orders calls WithLeaseConfiguration with expirationInterval set to 10 seconds and leaves renewInterval a
- You have an Azure Cosmos DB for NoSQL account named account1. When a host in a change feed processor deployment for a container named payments crashes, other hosts take over its leases only after a mi
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A container named orders is partitioned by /customerId and holds millions of customers. A .NET report must consume only the changes for th
- You have an Azure Cosmos DB for NoSQL account named account1. A Python service calls container.query_items_change_feed(start_time="Beginning", partition_key="tenant7") on a container named events that
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A nightly .NET job catches up on the change feed of a container named sales and exits its loop on the first response that contains zero do
- You have an Azure Cosmos DB for NoSQL account named account1. A developer reviews a pull-model loop for a container named logs that runs while (iterator.HasMoreResults) and expects the loop to end aut
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses periodic backup. A quarterly pull-model job reads a container named prices in latest version mode and saves its continuation toke
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET pull-model reader for a container named payments calls ReadNextAsync, immediately writes response.ContinuationToken to a blob, and
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. An orchestrator calls GetFeedRangesAsync on a container named telemetry and must hand each returned range to a different remote machine ov
- You have an Azure Cosmos DB for NoSQL account named account1. Four worker machines each run container.GetChangeFeedIterator<Order>(ChangeFeedStartFrom.Beginning(), ChangeFeedMode.LatestVersion) agains
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A team is replacing a .NET pull-model reader for a container named orders with a change feed processor that uses a new lease container. Th
- You have an Azure Cosmos DB for NoSQL account named account1. A pull-model reader for a container named orders is being replaced with a change feed processor. A developer plans to copy the reader's la
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A pull-model reader for a container named ledger sets PageSizeHint to 50 and preallocates a fixed array of exactly 50 slots for each respo
- You have an Azure Cosmos DB for NoSQL account named account1. Writes to a container named orders run through a stored procedure that updates up to 150 items in one transaction. A pull-model reader set
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 with all versions and deletes mode enabled. A Python job calls container.query_items_change_feed(continuation=token, mode="AllVersionsAndDe
- You have an Azure Cosmos DB for NoSQL account named account1 that is now enabled for all versions and deletes mode. A Python reader for a container named orders has used latest version mode with a sav
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. You inherit a .NET reader for a container named carts that uses SDK 3.30.0 and calls GetChangeFeedIterator<Cart>(ChangeFeedStartFrom.Begin
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET 8 service must read the latest-version change feed of a container named orders from the beginning, deserializing each change into a
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET relay service for a container named orders currently calls GetChangeFeedIterator<Order> and reserializes every object before forwar
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET relay service reads the latest-version change feed of a container named events and forwards each page's raw JSON to Azure Event Hub
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed estimator push delegate for a processor on a container named orders sends a value of 1,200 to a dashboard, where an operator
- You have an Azure Cosmos DB for NoSQL account named account1. A change feed estimator for a processor that reads a container named clicks reports 2,000 at 09:00, 9,000 at 11:00, and 18,000 at 13:00 du
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A processor named ordersProcessor reads a container named orders with a lease container named leases. A monitoring service builds an estim
- You have an Azure Cosmos DB for NoSQL account named account1. A .NET processor named invoiceSync reads a container named invoices and stores state in a lease container named leases. An operations team
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A processor deployment for a container named payments runs on six hosts, and the total estimated backlog is high. Operators suspect that o
- You have an Azure Cosmos DB for NoSQL account named account1. You created ChangeFeedEstimator estimator = monitoredContainer.GetChangeFeedEstimator("payProcessor", leaseContainer); for a container nam
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A single change feed estimator runs on its own instance to monitor a processor deployment that reads a container named orders and stores i
- You have an Azure Cosmos DB for NoSQL account named account1. A processor deployment for a container named shipments runs on 12 instances in Azure Kubernetes Service. The team wants backlog monitoring
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. You run az cosmosdb copy create to copy a container named orders into a destination container named ordersV2 that will use a new partition
- You have an Azure Cosmos DB for NoSQL account named account1. A container named sessions is partitioned by /tenantId, and a few tenants are approaching the 20 GB logical partition limit. You plan to u
- 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.
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses continuous backup. You need to copy a container named orders to a new container with a minimal write outage by using an online co
- You have an Azure Cosmos DB for NoSQL account named account1 that uses continuous backup and all versions and deletes mode. A script adds the EnableOnlineContainerCopy capability with az cosmosdb upda
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. An online container copy job named job1 copies a container named carts to a container named carts2. The output of az cosmosdb copy show re
- You have an Azure Cosmos DB for NoSQL account named account1. An online container copy job from orders to ordersV2 is running, and az cosmosdb copy show now reports that the processed count is greater
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. You are planning a container copy job from a container named products, which is provisioned at 10,000 RU/s, to a new container named produ
- You have an Azure Cosmos DB for NoSQL account named account1. A container copy job from a container named events, provisioned at 20,000 RU/s, into a container named eventsV2, provisioned at 5,000 RU/s
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A long-running container copy job named job1 must be halted during a quarterly finance close so that its reads and writes don't compete wi
- You have an Azure Cosmos DB for NoSQL account named account1 with the EnableOnlineContainerCopy capability enabled. A script runs az cosmosdb copy create --job-name job2 --src-account account1 --dest-
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. You need to copy an entire database named sales, which contains five containers, into a new database named salesV2 in the same account by
- You have an Azure Cosmos DB for NoSQL account named account1 that contains a database named sales with four containers. To copy the whole database, you created four offline container copy jobs in acco
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A container named sessions has a container-level default TTL of 86,400 seconds, and its items don't set their own ttl. After a container c
- You have an Azure Cosmos DB for NoSQL account named account1. In a container named tokens, each item sets its own ttl. An item that was written with a ttl of 30 days has 10 days of its lifetime remain
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A container named staff is partitioned by /department, and ids are unique only within each department. A copy job writes the items to a ne
- You have an Azure Cosmos DB for NoSQL account named account1. A copy job that repartitions a container named telemetry from /deviceId to /siteId fails with a 403 error, substatus 1014, stating that a
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that uses periodic backup. Partition merge was enabled last year, several containers were merged, and the feature was then disabled. You mu
- You have an Azure Cosmos DB for NoSQL account named account1 that uses periodic backup. Partition merge is currently enabled on account1 to reduce fragmentation of several containers. You must use a c
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. You plan an online container copy job for a container named ledger and must enable the EnableOnlineContainerCopy capability first. The sou
- You have two Azure Cosmos DB for NoSQL accounts named account1 and account2. You plan an online container copy job from a container named ledger in account1 to a container named ledger2 in account2, a
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 with a single write region and two read regions. You plan to create container copy jobs on account1. The documentation lists the regions in
- You have an Azure Cosmos DB for NoSQL account named account1 that is configured with multi-region writes in East US, West Europe, and Japan East. You plan container copy jobs for account1 and must con
- 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
- You have an Azure Cosmos DB for NoSQL account named account1 that has a single write region. A manual failover moved the write region from North Europe to West Europe while a container copy job was ru
- You have an Azure Cosmos DB for NoSQL account named account1 with East US as its write region and West US as a read region. An offline container copy job named job7 was halfway through copying a conta
- 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
- You have two Azure Cosmos DB for NoSQL accounts named source1 and target1 in the same resource group. You are writing az cosmosdb copy create to copy container orders in database sales on source1 to c
- You have two Azure Cosmos DB for NoSQL accounts named source1 and target1. Your az cosmosdb copy create command already sets --src-account source1, --dest-account target1, and --src-nosql database=sal
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. You plan a container copy job that copies a container named orders to a new container named ordersV2 in the same account. A colleague prep
- You have two Azure Cosmos DB for NoSQL accounts named source1 and target1 in different subscriptions. You will run container copy jobs from source1 to target1. Security requires a managed identity, no
- 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
- You have an Azure Cosmos DB for NoSQL account named account1. A vendor contract for migrating a 2-TB container named telemetry must state the guaranteed completion time that Microsoft provides for a c
- You have an Azure Cosmos DB for NoSQL account named account1. You must plan the cutover for an online container copy job that moves a container named catalog to a container named catalogV2 with a new
- 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
- https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed
- https://learn.microsoft.com/en-us/credentials/certifications/resources/study-guides/dp-420
- https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-modes
- https://learn.microsoft.com/en-us/azure/cosmos-db/continuous-backup-restore-introduction
- https://learn.microsoft.com/en-us/azure/cosmos-db/online-backup-and-restore
- https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-processor
- https://learn.microsoft.com/en-us/azure/cosmos-db/partial-document-update
- https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-pull-model
- https://learn.microsoft.com/en-us/azure/cosmos-db/merge
- https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/sdk-connection-modes
- https://learn.microsoft.com/en-us/azure/cosmos-db/change-feed-functions
- https://learn.microsoft.com/en-us/azure/cosmos-db/read-change-feed
- https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.changefeedprocessorbuilder
- https://learn.microsoft.com/en-us/dotnet/api/microsoft.azure.cosmos.changefeedprocessorbuilder.withleaseconfiguration
- https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-use-change-feed-estimator
- https://learn.microsoft.com/en-us/azure/cosmos-db/container-copy
- https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-container-copy