Databases Cosmos DB premium

Change feed

Change feed is an ordered stream of changes from an Azure Cosmos DB container that applications can read to react when data is inserted or updated. In everyday Azure work, it helps teams build event-driven workflows, synchronize projections, feed search indexes, replicate data, and process operational changes without polling every item in the container. You usually see it around Cosmos DB containers, Azure Functions triggers, SDK pull readers, change feed processor hosts, lease containers, diagnostic logs, and event-driven architecture diagrams.

Aliases
No aliases mapped yet
Difficulty
fundamentals
CLI mappings
2
Last verified
2026-05-12

Microsoft Learn

Change feed provides an ordered log of changes to items in a Cosmos DB container. Microsoft Learn places it in Reading Azure Cosmos DB change feed; operators confirm scope, configuration, dependencies, and production impact. Use the linked source for exact Azure behavior.

Microsoft Learn: Reading Azure Cosmos DB change feed2026-05-12

Technical context

Technically, Change feed appears as a Cosmos DB container feed read through push models such as Functions or the change feed processor, or through a pull model with continuation state. Engineers verify it through container name, partition key, lease container, continuation token, request charge, lag, processor host logs, function trigger logs, and downstream writes. Important configuration includes start position, feed mode, lease storage, host scale, poll interval, preferred regions, throughput, retry handling, and poison message strategy. It connects to monitoring, identity, networking, automation, and cost records for consistent review.

Why it matters

Change feed matters because mismanaged change feed processing can miss business events, duplicate downstream writes, consume unexpected RUs, or hide failures until projections are stale. The business impact is rarely abstract: users see slower systems, missing data, failed sign-ins, confusing reports, or unexpected cost when the setting is misunderstood. A solid glossary entry gives architects and operators the same language for design reviews, support handoffs, and audit evidence. It also helps teams decide what to check first, which metric or log proves the current state, who owns remediation, and when a change should be rolled back instead of patched live.

Where you see it

Signals, screens, and Azure surfaces where this term usually becomes operational.

Signal 01

In the Azure portal, Change feed appears near Cosmos DB container settings, where operators confirm scope, owner, diagnostics, access, and production state before release or incident response.

Signal 02

In CLI, ARM, SDK, REST, or Bicep output, Change feed appears as lease, continuation, and processor metadata, giving teams repeatable release and audit evidence during deployments and incidents.

Signal 03

In logs, metrics, tickets, or reviews, Change feed appears beside document changes, lag, retries, and downstream writes, linking symptoms to security, reliability, cost, and performance decisions quickly.

When this becomes relevant

Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.

  • Decide how application data is stored, indexed, scaled, cached, and protected.
  • Troubleshoot connection failures, throughput pressure, indexing, backup, or regional availability.
  • Explain why one database capability changes cost, latency, consistency, or recovery behavior.
  • Prepare production changes with source, identity, network, and command context visible.

Real-world case studies

Different enterprise-style examples that show the term being used to hit measurable objectives.

Case study 01

Order projection service

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Litware Market, an ecommerce marketplace, needed to update order status projections whenever Cosmos DB order documents changed.

Business/Technical Objectives
  • Reflect order changes in customer views within one minute
  • Avoid polling every order document
  • Keep duplicate processing harmless
  • Track RU cost for event processing
Solution Using Change feed

Developers used the Azure Cosmos DB change feed with Azure Functions triggers to react to inserts and updates in the orders container. The projection service wrote normalized status records to Azure SQL and ignored duplicate events using order version fields. Engineers monitored function failures, RU consumption, and projection lag through Application Insights and Cosmos DB metrics. The design used a dedicated lease container, private endpoints, and alerting for trigger failures. During release testing, the team replayed changes from a controlled dataset and verified that customer views matched source order documents. The runbook also captured dashboard links, owner contacts, rollback criteria, and monthly review steps so operators could verify the design without tribal knowledge during incidents or release windows. Evidence from each change was saved with the deployment record for audit, support, and future capacity planning.

Results & Business Impact
  • Customer order views updated in 38 seconds on average
  • Polling jobs that scanned 4 million documents were removed
  • Duplicate event handling passed replay tests
  • RU consumption for projections fell by 47 percent
Key Takeaway for Glossary Readers

Change feed is valuable when applications react to data changes while still designing for retries, duplicates, and throughput.

Case study 02

IoT device state synchronization

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Alpine Sensors, an industrial IoT provider, needed device state changes in Cosmos DB synchronized to a command center and search index.

Business/Technical Objectives
  • Synchronize device state within five minutes
  • Support millions of daily item updates
  • Avoid rebuilding search indexes hourly
  • Detect stale projections automatically
Solution Using Change feed

The architecture used Cosmos DB change feed readers to process updates from the device state container and publish downstream work to Service Bus and Azure AI Search indexing jobs. Continuation state and monitoring were documented so operators could see whether processors were current. The team partitioned devices by fleet, measured request charges, and created alerts for lag, throttling, and repeated downstream failures. A recovery procedure allowed a one-time pull model read for selected FeedRanges when a downstream outage required replay. All consumers used idempotent writes keyed by device ID and version. The rollout plan included before-and-after measurements, escalation contacts, exception rules, and a control review with finance, security, and application owners. That evidence made the improvement repeatable and gave support teams a clear baseline when later incidents raised similar symptoms.

Results & Business Impact
  • Search freshness improved from hourly to under four minutes
  • Command center stale-device alerts dropped by 62 percent
  • Processor lag was visible to on-call engineers
  • Replay testing recovered a simulated downstream outage
Key Takeaway for Glossary Readers

A change feed turns database updates into an integration stream when consumers, checkpoints, and idempotency are intentionally designed.

Case study 03

Customer profile replication

Scenario, objectives, solution, measured impact, and takeaway.

Scenario

Mercury Bank, a regional bank, needed to replicate approved customer profile changes from Cosmos DB to a risk analytics store.

Business/Technical Objectives
  • Replicate profile updates without nightly exports
  • Preserve compliance evidence for data movement
  • Throttle processing during peak banking hours
  • Avoid missing updates during regional maintenance
Solution Using Change feed

Engineers implemented a Cosmos DB change feed workflow that read customer profile updates and wrote redacted fields into an analytics container. The processing service tracked continuation state, request charge, and downstream write success. Preferred regions were configured so the workflow could continue during maintenance without switching to regional endpoints that would create confusing state. Security limited access to the source container and logged processing identity activity. The runbook covered pause, resume, and controlled replay. Analysts received only fields approved by the data governance group. Release evidence included configuration snapshots, CLI output, representative metrics, and ticket notes, giving operations a durable baseline for training, audits, and later optimization work. The team also defined when to scale back, rotate credentials, or open a vendor support case.

Results & Business Impact
  • Nightly export duration dropped from seven hours to zero
  • Profile analytics freshness improved to 12 minutes
  • No unauthorized fields appeared in the analytics target
  • Regional maintenance completed without missed updates
Key Takeaway for Glossary Readers

Change feed supports governed replication when source access, regional behavior, redaction, and replay plans are clear.

Why use Azure CLI for this?

Use CLI, REST, SDK, or scripted queries for Change feed because change feed troubleshooting needs repeatable evidence of containers, leases, consumers, throughput, and downstream processing state and to avoid portal-only evidence during reviews.

CLI use cases

  • Verify source and lease containers before deploying a new event processor.
  • Capture RU usage, lag, and host logs when downstream projections fall behind.
  • Confirm whether a consumer reads from the beginning or only new changes.

Before you run CLI

  • Confirm the active tenant, subscription, resource group, workspace, account, or region before running commands.
  • Use least-privileged access and avoid storing secrets, prompts, certificates, tokens, or personal data in command output.
  • Know whether the command is read-only, mutating, cost-impacting, security-impacting, or destructive before production use.

What output tells you

  • Output confirms whether the live Azure configuration exists at the expected scope and matches the approved design.
  • Returned IDs, settings, metrics, timestamps, or logs help separate configuration drift from application behavior.
  • Differences between expected and actual state create evidence for rollback, escalation, audit, or owner follow-up.

Mapped Azure CLI commands

Adjacent discovery commands

adjacent
az resource list --resource-group <resource-group> --output table
az resourcediscoverDatabases
az resource show --ids <resource-id>
az resourcediscoverManagement and Governance

Architecture context

In Cosmos DB architecture, change feed is the event stream that lets applications react to writes without scanning the container repeatedly. It is commonly used to update projections, feed search indexes, replicate data, trigger Functions, or drive event-driven workflows. Architects review it against partition key design, throughput, feed mode, start position, continuation handling, preferred regions, downstream idempotency, and monitoring for lag or retries. The feed reflects data changes, but the application architecture determines whether processing is safe during scale-out, failover, or replay. A production design should document which container is the source of truth, where checkpoints live, what happens to poison events, and how downstream systems avoid duplicate side effects.

Security

Security for Change feed starts with understanding which identities, secrets, certificates, endpoints, data stores, or management-plane permissions it touches. Review who can view, change, or use it, and confirm that production access follows least privilege. Check whether private networking, firewall rules, RBAC, key vault storage, managed identity, audit logs, and data classification apply. Operators should avoid exposing tokens, connection strings, prompts, certificate material, or cost-sensitive business metadata in troubleshooting output. A secure design also documents emergency access, rotation responsibilities, and evidence retention so an incident response team can prove the current configuration without inventing access during an outage. Security reviewers should confirm least privilege, private access paths, and audit retention before approving production use.

Cost

Cost for Change feed comes from the resources, transactions, data movement, retention, compute, capacity, tokens, or operational labor it influences. Some costs are direct meters, while others appear as extra storage, higher throughput, duplicate processing, export jobs, monitoring ingestion, or engineering time. Review budgets, cost allocation, tags, usage metrics, and SKU limits before scaling or enabling new behavior. The safest approach is to define the owner, expected usage pattern, and alert thresholds up front. That way finance conversations use evidence instead of opinions after the bill arrives. Finance and engineering teams should agree which metric proves usage and which scope owns remediation.

Reliability

Reliability for Change feed depends on whether the design behaves predictably during scale events, regional incidents, expired credentials, throttling, schema changes, or downstream failures. Identify the dependency chain, expected failure mode, and recovery target before production use. Monitor the signals that show backlog, lag, retries, health state, capacity saturation, authentication failures, or stale data. Test restore, rotation, failover, replay, or rollback paths where they apply. Operators need a runbook that separates platform configuration problems from application defects and says which evidence is required before escalating to networking, identity, database, or product teams. Runbooks should state the first observable symptom, safe rollback path, and owner escalation route.

Performance

Performance for Change feed is about how quickly and consistently the related workload can complete useful work. Measure the right signals: latency, throughput, backlog, request units, token volume, CPU, memory, bytes scanned, file counts, retries, or throttled operations depending on the service. Avoid tuning one setting in isolation when partitions, replicas, keys, network paths, identity calls, downstream services, or client behavior may be the real bottleneck. Performance reviews should compare expected workload shape with live metrics and include a safe test plan before increasing capacity or changing production configuration. Load tests should compare expected throughput, latency, queue depth, and saturation signals against live limits.

Operations

Operationally, Change feed needs ownership, naming, tagging, change records, and repeatable verification. Teams should know where it appears in the portal, which commands or queries prove state, which dashboards show health, and which settings are safe to change during business hours. Keep examples, approvals, and rollback notes with the service runbook rather than in personal notes. For production changes, capture current configuration before and after the work, including resource IDs, region, owner, timestamp, and related deployment. Good operations turn the term into a checklist that first responders can follow under pressure. Operational evidence should include timestamps, resource IDs, owner names, and links to the approved change record.

Common mistakes

  • Assuming every failed change is retried the same way across Functions and custom processors.
  • Using a lease container with unclear ownership or insufficient throughput.
  • Ignoring duplicate handling even though at-least-once delivery can process events more than once.