Skip to article
Databases Azure Cosmos DB

Cosmos DB composite index

Container indexing-policy setting that improves selected multi-property query patterns, often reducing RU cost for filters, aggregates, and ORDER BY queries.

Source: Microsoft Learn - Azure Cosmos DB indexing policies

Exam trap
Adding composite indexes without tying them to measured queries.
Production check
Which query is this composite index intended to support?
Practice this topic Microsoft Learn
Article details and learning context
Aliases
Azure Cosmos DB composite index, composite index, composite indexing policy
Difficulty
intermediate
CLI mappings
3
Last verified
Learning paths Graph Databases concept cluster Cosmos DB composite index
Compare related concepts Search related resources Browse the glossary

Understand the concept

In plain English

A Cosmos DB composite index is an index that combines more than one document property so certain queries can run efficiently. It is most visible when a query filters or sorts by multiple fields, such as status plus date, region plus priority, or customer plus timestamp. The default indexing policy is helpful, but it does not solve every multi-property query shape. Composite indexes are not random performance boosters; they should match real queries, property order, and sort direction. Used well, they can reduce RU cost and latency.

Why it matters

Cosmos DB composite index matters because query cost can surprise teams after an application grows. A query that sorts open claims by priority and updated time may look simple, but without the right index it can cost more RU and respond slower than expected. Composite indexes let teams intentionally support important access patterns instead of overpaying for repeated inefficient queries. The value is strongest when the business query is frequent, latency-sensitive, or expensive at scale. The risk is adding indexes without evidence, which can increase write overhead and operational complexity. Good designs connect each composite index to a named query path.

Official wording and source

A Cosmos DB composite index is an indexing policy entry that supports efficient queries involving multiple properties, especially multi-property ORDER BY or filter-plus-sort patterns.

Open Microsoft Learn

Technical context

Technically, composite indexes are defined inside the Cosmos DB container indexing policy for the NoSQL API. Each composite path specifies properties and ordering that the query engine can use for matching multi-property ORDER BY, filters with sort, and selected aggregate patterns. Property order, sort direction, case sensitivity, and scalar path rules matter. Adding or changing an indexing policy can trigger index transformation and should be tested before production rollout. Architects should inspect query diagnostics, RU charge, result size, and whether the query pattern truly benefits from a composite index.

Exam context

Compare with

Cosmos DB account Cosmos DB database

Where it is used

Where you see it

  1. In the Azure portal or IaC, it appears inside a NoSQL container indexing policy under compositeIndexes with property paths, ordering, and policy-change history during production reviews and runbooks.
  2. In query diagnostics, it appears when multi-property filters, ORDER BY clauses, or aggregates consume high RU and need an indexing-policy review in release reviews and support tickets.
  3. In release reviews, it appears beside slow query tickets, index transformation plans, regression tests, rollback steps, and measured before-and-after request charge during incident triage and architecture reviews.

Common situations

  • Optimize multi-property ORDER BY queries in NoSQL containers.
  • Reduce RU cost for frequent filter-plus-sort workloads.
  • Support operational dashboards that rely on predictable sorted results.
  • Document query-specific index choices for governance and tuning.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Travel search optimization Scenario, objectives, solution, measured impact, and takeaway.
Scenario

WingTrail Travel had a flight-search container where users filtered by origin, destination, fare class, and departure time.

Goals
  • Reduce search query RU by at least 40 percent
  • Keep sorted results under 150 milliseconds P95
  • Avoid increasing booking write latency materially
  • Manage index changes through release pipelines
Approach using Cosmos DB composite index

Query diagnostics showed that the most expensive search path sorted by departure time after filtering origin, destination, and fare class. Architects added a composite index matching the filter and ORDER BY pattern, then tested it with production-like route volume. The indexing policy moved through IaC, not a portal change, and the rollout included RU monitoring during index transformation. Developers also removed an unused experimental composite index that had increased write cost. Dashboards compared request charge, latency, and booking write performance before and after rollout. The final review documented service owners, rollback triggers, monitoring thresholds, and escalation contacts so production support could act without guessing.

Potential outcomes
  • Search query RU dropped 52 percent for the target route pattern
  • P95 sorted search latency improved from 241 to 118 milliseconds
  • Booking write latency changed by less than 3 percent
  • Index policy drift was eliminated by IaC enforcement
What to learn

A Cosmos DB composite index should be tied to a measured query path and deployed with the same discipline as application code.

Scenario 02 Claims work queue sorting Scenario, objectives, solution, measured impact, and takeaway.
Scenario

Evergreen Mutual needed adjusters to see high-priority claims sorted by region and last update time without slow dashboards.

Goals
  • Load adjuster queues in under two seconds
  • Cut dashboard query RU during morning peaks
  • Keep claim update writes within current throughput budget
  • Document why each index exists
Approach using Cosmos DB composite index

The claims platform team reviewed slow query diagnostics from the adjuster portal and found repeated filters on claim status and region with ordering by lastUpdatedUtc. They added a composite index for the approved queue query and kept a design note linking the index to that screen. Before rollout, a staging container replayed real claim update traffic to measure write overhead. Operations monitored index transformation progress, RU, and dashboard latency after deployment. An older composite index for a retired queue view was removed during the same release. A follow-up runbook captured validation queries, owner approvals, cost guardrails, and support handoff steps for the next release. Operations also added a quarterly review to confirm metrics, access, backup assumptions, and application behavior still matched the original design.

Potential outcomes
  • Adjuster queue load time fell from 4.8 seconds to 1.3 seconds
  • Morning dashboard RU consumption decreased 47 percent
  • Claim update writes stayed inside the existing autoscale range
  • Every composite index had an owner and query reference
What to learn

Composite indexes work best when they support durable business screens, not temporary reporting experiments.

Scenario 03 Logistics dispatch dashboard Scenario, objectives, solution, measured impact, and takeaway.
Scenario

RoadPoint Delivery used Cosmos DB for dispatch tasks and struggled with slow queries sorted by depot, priority, and promised delivery window.

Goals
  • Make dispatcher views responsive during peak routing windows
  • Reduce RU spent on repeated sort queries
  • Avoid broad cross-partition scans where possible
  • Create rollback steps for indexing-policy changes
Approach using Cosmos DB composite index

Engineers measured the dispatch dashboard queries and found that the priority queue needed a composite index on depot, task status, and promised delivery time. They adjusted the query to include the depot partition key, added the composite index through the deployment pipeline, and watched index transformation during a low-traffic window. Operations kept a rollback policy file and tracked before-and-after RU metrics. Dispatchers were trained to use approved filters instead of ad hoc combinations that were not backed by measured indexes. Operations also added a quarterly review to confirm metrics, access, backup assumptions, and application behavior still matched the original design. The final review documented service owners, rollback triggers, monitoring thresholds, and escalation contacts so production support could act without guessing.

Potential outcomes
  • Dispatcher dashboard P95 latency improved by 64 percent
  • RU per priority queue query dropped from 38 to 14
  • Cross-partition query volume fell after depot filters became mandatory
  • Rollback documentation was approved before production rollout
What to learn

Composite indexing can make operational dashboards fast, but it must be paired with query discipline and partition-aware design.

Azure CLI

Use CLI to inspect container indexing policy and capture before-and-after evidence before changing composite indexes for production queries.

Useful for

  • Show the container indexing policy during slow query analysis.
  • Export container configuration before an index policy change.
  • Update indexing policy only through approved change control or IaC.

Before you run a command

  • Confirm the affected database, container, query, and application owner.
  • Capture query diagnostics before changing any indexing policy.
  • Plan for index transformation and monitor RU during rollout.

What the output tells you

  • Container output shows current indexing policy and composite index paths.
  • Policy differences reveal whether the expected composite index exists.
  • Throughput and metrics help explain rollout impact during index transformation.

Mapped commands

Cosmos DB composite index commands

direct 
az cosmosdb sql container show --account-name <account> --resource-group <resource-group> --database-name <database> --name <container>
az cosmosdb sql containerdiscoverDatabases
read-only Microsoft Learn 
az cosmosdb sql container update --account-name <account> --resource-group <resource-group> --database-name <database> --name <container> --idx @indexing-policy.json
az cosmosdb sql containerconfigureDatabases
changes indexing policy Microsoft Learn 
az cosmosdb sql container throughput show --account-name <account> --resource-group <resource-group> --database-name <database> --name <container>
az cosmosdb sql container throughputdiscoverDatabases
read-only Microsoft Learn

Architecture context

A Cosmos DB composite index is a query-shape commitment written into the container indexing policy. I review it when applications sort and filter by multiple properties, especially dashboards, work queues, search-like screens, and operational reports. The architecture needs to connect real query patterns to index paths, sort direction, partition key, and RU impact. Adding every possible combination is not good design because write cost and index maintenance still matter. Operators should capture query text, metrics, index policy, RU charge, and latency before and after changes. Composite indexes are most useful when they support known high-value queries. They should be managed through deployment templates and reviewed like application schema, not tweaked manually after every slow page.

Security
Security for Cosmos DB composite index is less about granting access and more about understanding what indexed query paths make easy to retrieve. Indexes can enable fast discovery of sensitive combinations such as account status plus region or patient category plus date. They should be reviewed with data classification, approved query use cases, and least-privilege access. Teams should avoid exposing broad query tools simply because indexed queries are fast. Indexing policy changes also need change control because they can affect application behavior and cost. Security evidence should show who approved the query path, what data it touches, and which identities can run it.
Cost
Cost for Cosmos DB composite index has two sides. A well-matched composite index can reduce RU for frequent multi-property queries and improve latency. Extra indexes can also increase write cost, storage, and policy complexity, especially when teams index paths that are rarely used. Cost review should start with query diagnostics and business frequency: how often does the query run, what RU does it consume, and what would the index change save? Teams should also account for index transformation during rollout and storage growth over time. Do not add composite indexes because they sound advanced; add them because measurements justify them.
Reliability
Reliability for Cosmos DB composite index depends on safe indexing policy changes, realistic query testing, and monitoring during index transformation. A production change can temporarily affect RU consumption or query behavior if it is rushed. Teams should stage index updates, measure before-and-after RU, and understand how application code behaves while the index catches up. Reliable operations also include rollback planning, test queries with representative documents, and dashboards for throttling and latency during rollout. A composite index should support a stable business query, not chase every temporary filter a developer tried during debugging. Include realistic failure drills, owner escalation, and recovery evidence in the runbook.
Performance
Performance for Cosmos DB composite index is about matching the index to the exact query shape. Multi-property ORDER BY queries usually need a composite index, and filter-plus-sort or aggregate patterns may benefit when properties are arranged correctly. Direction, path casing, and order can determine whether the index is used. Teams should test with realistic item counts, partition distribution, and result sizes. Compare query diagnostics before and after the change, including RU, retrieved document count, output count, and latency percentiles. Performance tuning should also verify that the query includes the partition key when possible. Validate tuning with representative traffic, documented baselines, and user-facing service targets.
Operations
Operationally, Cosmos DB composite index belongs in query review, indexing policy management, and release planning. Teams should keep a catalog of composite indexes, the application query each one supports, expected property order, sort direction, owner, and evidence from query diagnostics. Index changes should move through IaC or controlled configuration pipelines rather than portal experiments. During incidents, operators should compare current indexing policy, recent deployments, RU charge, and slow query diagnostics. Good runbooks explain when to add an index, when to remove an unused index, and how to watch transformation progress and application impact. Keep ownership, dashboard links, deployment history, and support escalation steps current.

Common mistakes

  • Adding composite indexes without tying them to measured queries.
  • Using the wrong property order or sort direction for the query.
  • Ignoring write and storage overhead from unnecessary indexes.