Databases Azure Cosmos DB premium

Composite index

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.

Aliases
No aliases mapped yet
Difficulty
Intermediate
CLI mappings
3
Last verified
2026-05-12

Microsoft Learn

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.

Microsoft Learn: Indexing policies - Azure Cosmos DB2026-05-12

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.

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.

Where you see it

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

Signal 01

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.

Signal 02

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.

Signal 03

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.

When this becomes relevant

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

  • 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.

Real-world case studies

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

Case study 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.

Business/Technical Objectives
  • Cut RU charge for common support queries by 50 percent
  • Support multi-property ordering without failures
  • Avoid increasing provisioned throughput
  • Deploy indexing changes safely
Solution 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.

Results & Business Impact
  • Average RU charge fell 63 percent
  • Support query latency dropped 41 percent
  • No throughput increase was required
  • Index transformation completed before peak weekend load
Key Takeaway for Glossary Readers

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

Case study 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.

Business/Technical Objectives
  • Keep dispatcher searches under two seconds
  • Reduce query-cost variance across regions
  • Support sorting by multiple properties
  • Document index policy ownership
Solution 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.

Results & Business Impact
  • 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
Key Takeaway for Glossary Readers

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

Case study 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.

Business/Technical Objectives
  • Lower investigation query RU cost
  • Preserve audit evidence for query changes
  • Avoid exposing transaction data in diagnostics
  • Keep analytical workflow responsive
Solution 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.

Results & Business Impact
  • Investigation query cost fell 57 percent
  • Dashboard response time improved 34 percent
  • Diagnostics excluded transaction payloads
  • Extra business-hour throughput was removed
Key Takeaway for Glossary Readers

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

Why use Azure CLI for this?

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

CLI use cases

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

Cosmos operations

direct
az cosmosdb list --resource-group <resource-group>
az cosmosdbdiscoverDatabases
az cosmosdb show --name <account> --resource-group <resource-group>
az cosmosdbdiscoverDatabases
az cosmosdb create --name <account> --resource-group <resource-group> --locations regionName=<region>
az cosmosdbprovisionDatabases
az cosmosdb update --name <account> --resource-group <resource-group> --enable-automatic-failover true
az cosmosdbconfigureDatabases
az cosmosdb keys list --name <account> --resource-group <resource-group>
az cosmosdb keysdiscoverDatabases
az cosmosdb sql database list --account-name <account> --resource-group <resource-group>
az cosmosdb sql databasediscoverDatabases
az cosmosdb sql database create --account-name <account> --resource-group <resource-group> --name <database>
az cosmosdb sql databaseprovisionDatabases
az cosmosdb sql container list --account-name <account> --resource-group <resource-group> --database-name <database>
az cosmosdb sql containerdiscoverDatabases
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
az cosmosdb sql container throughput show --account-name <account> --resource-group <resource-group> --database-name <database> --name <container>
az cosmosdb sql container throughputdiscoverDatabases
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

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.