Skip to article
Databases Azure Cosmos DB

Composite index

an Azure Cosmos DB indexing policy entry that combines multiple item properties in a defined order so certain filters and multi-property sorts run efficiently

Source: Microsoft Learn - Indexing policies - Azure Cosmos DB Reviewed 2026-05-12

Exam trap
Adding a composite index with property paths in the wrong sequence.
Production check
Confirm owner, scope, resource IDs, region, tags, and environment before accepting the current state.
Practice this topic Microsoft Learn
Article details and learning context
Aliases
None listed
Difficulty
Intermediate
CLI mappings
3
Last verified
2026-05-12
Compare related concepts Search related resources Browse the glossary

Understand the concept

In plain English

Composite index means an Azure Cosmos DB indexing policy entry that combines multiple item properties in a defined order so certain filters and multi-property sorts run efficiently. Teams use it to support ORDER BY queries across multiple fields, reduce request-unit consumption, improve predictable query performance, and avoid full scans for common access patterns. In Azure work, operators usually see it in portal settings, deployment output, metrics, logs, and runbooks. The practical question is who owns it, what scope it affects, and what evidence proves it is working.

Why it matters

Composite index matters because missing or mismatched composite indexes can turn normal application queries into expensive scans or failed multi-property sorts. The business impact is rarely abstract: users see slower workflows, missing data, failed automation, audit gaps, support delays, or unexpected cost when the term is misunderstood. A strong glossary entry gives architects, developers, security reviewers, and operators the same language for design reviews and incident handoffs. It connects Azure configuration to measurable objectives, ownership, rollback paths, and evidence, so teams treat it as an operational control rather than a portal label. That discipline helps teams make safer changes under pressure.

Official wording and source

A composite index in Azure Cosmos DB is an indexing policy entry over two or more property paths and sort orders, required for some multi-property ORDER BY queries and useful for query optimization.

Open Microsoft Learn

Technical context

Technically, Composite index is a container-level indexing policy definition that lists multiple property paths and ascending or descending order requirements. Engineers verify it with service configuration, IDs, logs, metrics, request records, and deployment evidence. Important configuration includes property path order, ascending or descending direction, indexing mode, excluded paths, container partition key, query workload, and deployment sequencing. Production reviews should capture owner, scope, region, identity, limits, recent changes, and diagnostics before changing behavior. Those details make troubleshooting repeatable across portal, CLI, SDK, and pipeline evidence.

Exam context

Compare with

Azure Cosmos DB for NoSQL Autoscale throughput

Where it is used

Where you see it

  1. You see Composite index in Cosmos DB indexing policies, query plans, SDK errors, and RU metrics when confirming ordered index paths, sort direction, filters, and query shape for release, audit, or incident evidence.
  2. You see Composite index during troubleshooting when queries consume high RUs or reject ORDER BY combinations and operators must connect portal state, CLI output, logs, metrics, owners, and rollback notes.
  3. You see Composite index in architecture reviews when teams decide which multi-field queries need explicit index support, how evidence is gathered, and how it affects security, reliability, operations, cost, and performance.

Common situations

  • Reduce RU cost for multi-property sort and filter queries.
  • Validate indexing policy before scaling container throughput.
  • Track index transformation after adding a composite index.

Illustrative Azure scenarios

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

Scenario 01 Retail order query optimization Scenario, objectives, solution, measured impact, and takeaway.
Scenario

Fabrikam Retail queried orders by customer, status, and updated time, but the support portal consumed too many request units during peak returns.

Goals
  • Cut RU charge for common support queries by 50 percent
  • Support multi-property ordering without failures
  • Avoid increasing provisioned throughput
  • Deploy indexing changes safely
Approach using Composite index

Database engineers reviewed query diagnostics and found repeated filters on customerId and status with ORDER BY updatedAt. They added a composite index matching the query order in the container indexing policy and deployed it through Bicep during a low-traffic window. Azure Monitor tracked RU charge, index transformation progress, and latency. The support application kept the old query shape while the index transformed, and rollout notes defined rollback conditions if RU cost or latency increased unexpectedly. The runbook captured owner, environment, approval link, rollback condition, and the exact Azure evidence operators had to collect before and after each change. A dashboard tracked adoption, exceptions, and operational signals so support, security, and finance teams could review outcomes without relying on informal notes.

Potential outcomes
  • Average RU charge fell 63 percent
  • Support query latency dropped 41 percent
  • No throughput increase was required
  • Index transformation completed before peak weekend load
What to learn

A composite index can solve a real Cosmos DB performance problem when it is matched to the exact query shape.

Scenario 02 Logistics shipment sorting Scenario, objectives, solution, measured impact, and takeaway.
Scenario

Northwind Logistics needed dispatchers to sort shipments by region, priority, and promised delivery time without waiting on slow scans.

Goals
  • Keep dispatcher searches under two seconds
  • Reduce query-cost variance across regions
  • Support sorting by multiple properties
  • Document index policy ownership
Approach using Composite index

The data team captured production query metrics and identified a multi-property ORDER BY pattern that could not use existing range indexes efficiently. They added composite indexes for region, priority, and deliveryTime with the correct path order. The change was managed as infrastructure code and reviewed with application owners because query shapes and index paths had to stay aligned. Dashboards compared RU consumption by region after index transformation and alerted when new query patterns bypassed indexes. The runbook captured owner, environment, approval link, rollback condition, and the exact Azure evidence operators had to collect before and after each change. A dashboard tracked adoption, exceptions, and operational signals so support, security, and finance teams could review outcomes without relying on informal notes. The team reviewed results after the pilot and kept the design in the standard platform checklist for future deployments.

Potential outcomes
  • P95 dispatcher search latency stayed under 1.4 seconds
  • RU variance across regions dropped 48 percent
  • New query drift alerts found two unsupported filters
  • Index ownership moved into the platform runbook
What to learn

Composite indexes are operational assets, not one-time tuning tricks, because application query shapes keep evolving.

Scenario 03 Financial fraud workload tuning Scenario, objectives, solution, measured impact, and takeaway.
Scenario

Alpine Payments ran fraud investigations on Cosmos DB transactions but analysts saw high cost when sorting by merchant risk and event time.

Goals
  • Lower investigation query RU cost
  • Preserve audit evidence for query changes
  • Avoid exposing transaction data in diagnostics
  • Keep analytical workflow responsive
Approach using Composite index

Architects tested representative fraud queries in a nonproduction container with production-like partitioning. Composite indexes were added for merchantRisk and eventTime, then validated with query metrics and continuation behavior. Diagnostics stored query shape, RU charge, and timings but excluded transaction payloads. The team deployed the indexing policy through change control, waited for transformation completion, and verified that investigator dashboards no longer required extra throughput during business hours. The runbook captured owner, environment, approval link, rollback condition, and the exact Azure evidence operators had to collect before and after each change. A dashboard tracked adoption, exceptions, and operational signals so support, security, and finance teams could review outcomes without relying on informal notes. The team reviewed results after the pilot and kept the design in the standard platform checklist for future deployments.

Potential outcomes
  • Investigation query cost fell 57 percent
  • Dashboard response time improved 34 percent
  • Diagnostics excluded transaction payloads
  • Extra business-hour throughput was removed
What to learn

Composite indexes help control both performance and cost when Cosmos DB query design is tied to measured workload behavior.

Azure CLI

Use CLI, deployment, and query-metric evidence to confirm container indexing policy and query impact before scaling throughput to hide inefficiency.

Useful for

  • Show a Cosmos DB container indexing policy before a query-performance review.
  • Compare RU charge before and after adding a composite index.
  • Validate deployment output when an indexing policy is updated through infrastructure as code.

Before you run a command

  • 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 the 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 commands

Cosmos operations

direct 
az cosmosdb list --resource-group <resource-group>
az cosmosdbdiscoverDatabases
read-only Microsoft Learn 
az cosmosdb show --name <account> --resource-group <resource-group>
az cosmosdbdiscoverDatabases
read-only Microsoft Learn 
az cosmosdb create --name <account> --resource-group <resource-group> --locations regionName=<region>
az cosmosdbprovisionDatabases
cost-impacting Microsoft Learn 
az cosmosdb update --name <account> --resource-group <resource-group> --enable-automatic-failover true
az cosmosdbconfigureDatabases
mutating Microsoft Learn 
az cosmosdb keys list --name <account> --resource-group <resource-group>
az cosmosdb keysdiscoverDatabases
security-impacting Microsoft Learn 
az cosmosdb sql database list --account-name <account> --resource-group <resource-group>
az cosmosdb sql databasediscoverDatabases
read-only Microsoft Learn 
az cosmosdb sql database create --account-name <account> --resource-group <resource-group> --name <database>
az cosmosdb sql databaseprovisionDatabases
cost-impacting Microsoft Learn 
az cosmosdb sql container list --account-name <account> --resource-group <resource-group> --database-name <database>
az cosmosdb sql containerdiscoverDatabases
read-only Microsoft Learn 
az cosmosdb sql container create --account-name <account> --resource-group <resource-group> --database-name <database> --name <container> --partition-key-path <path>
az cosmosdb sql containerprovisionDatabases
cost-impacting 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 
az cosmosdb sql container throughput update --account-name <account> --resource-group <resource-group> --database-name <database> --name <container> --throughput <ru>
az cosmosdb sql container throughputconfigureDatabases
cost-impacting Microsoft Learn

Architecture context

Technically, Composite index is a container-level indexing policy definition that lists multiple property paths and ascending or descending order requirements. Engineers verify it with service configuration, IDs, logs, metrics, request records, and deployment evidence. Important configuration includes property path order, ascending or descending direction, indexing mode, excluded paths, container partition key, query workload, and deployment sequencing. Production reviews should capture owner, scope, region, identity, limits, recent changes, and diagnostics before changing behavior. Those details make troubleshooting repeatable across portal, CLI, SDK, and pipeline evidence.

Security
Security for Composite index starts with understanding who can change container indexing policies, deploy schemas, read query diagnostics, access data paths, and approve performance-related production changes. Review identities, roles, secrets, network paths, data classification, logs, and who can change the setting. Prefer least privilege, private access when available, managed identity or protected credentials, and audit evidence. Watch for broad permissions, sensitive data in logs, shared keys, public endpoints, stale owners, and exceptions without expiry. Production use should include an approved owner, access boundary, alert routing, and a revocation process operators can execute during an incident. Security reviewers should tie every exception to risk acceptance and expiry.
Cost
Cost for Composite index comes from request units, index storage, index transformation work, query retries, slow investigation time, and extra provisioned throughput used to hide bad query design. Direct costs may be obvious, but indirect costs can appear as retries, duplicate processing, idle capacity, data movement, investigation time, or support effort. Review budgets, tags, usage metrics, quota, retention, SKU, and forecasts before enabling or scaling it. Connect spend to business-unit ownership and expected workload value. Define normal usage, alert thresholds, cleanup rules, and exception approval before the feature becomes a hidden default across environments. Finance teams need evidence that the cost aligns to real demand, not leftover experiments.
Reliability
Reliability for Composite index depends on index transformation completion, query-plan stability, deployment order, partition-aware testing, and rollback if an indexing change affects live workload behavior. Operators should know the expected failure mode, dependency chain, recovery target, and whether retries, failover, reprocessing, or manual approval are required. Monitor health, latency, quota, backlog, error rates, stale state, and downstream failures. Test behavior during maintenance, regional incidents, expired credentials, schema changes, and burst traffic. Runbooks should explain how to validate current state, preserve evidence, reduce blast radius, and restore service without duplicate work or data loss. Reliability reviews should include the human handoff path, not only platform health.
Performance
Performance for Composite index is about RU charge per query, sort and filter shape, index path order, partition key selectivity, continuation behavior, and index transformation completion time. Measure signals that reflect user or workload experience, such as latency, throughput, request units, node startup time, model response time, queue depth, cache behavior, or throttled operations. Avoid tuning one setting in isolation when identity, network path, partitioning, model size, region, or downstream capacity may be the real bottleneck. Compare baseline and peak results after changes, then document which limit would be reached first as demand grows. Keep tests close to production patterns.
Operations
Operationally, Composite index needs clear ownership, naming, tagging, change records, and repeatable verification. Teams should know where it appears, which commands or queries prove state, which dashboard shows health, and what is safe to change during business hours. Keep examples, approvals, rollback notes, and exception records with the service runbook rather than personal notes. For production changes, capture before-and-after evidence, including resource IDs, region, tenant, policy assignment, deployment version, and linked services. Review stale resources and permissions regularly. Escalation contacts should stay current as teams reorganize. This prevents tribal knowledge from becoming the only support path. It also helps new operators support the service with confidence.

Common mistakes

  • Adding a composite index with property paths in the wrong sequence.
  • Expecting immediate improvement before index transformation has completed.
  • Increasing throughput instead of fixing a predictable multi-property query pattern.