Indexing Deep Dive

Cosmos’s default — index every property of every document on every path — is a deliberate choice. It means your queries work the moment you write them, with no upfront DBA work. The cost is that every write has to update every index, and most apps have many fields that nobody ever queries. Tuning the index policy is where you get write RUs back.

What the default policy actually looks like

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [{ "path": "/*" }],
  "excludedPaths": [{ "path": "/_etag/?" }]
}

Translation — “index everything except the system etag.” Every JSON path on every doc is in the index, supporting equality, ordering, and range queries.

The cost you’re paying

A 1 KB document with a default policy adds ~5 RU to a write. Half of that is index maintenance. Strip out fields you never query and that drops to 3 RU — a 40% saving on a write-heavy workload.

For an event log container ingesting 10K writes/sec — that’s 20K RU/s saved, which translates directly to provisioned throughput cost.

Excluding paths

{
  "indexingMode": "consistent",
  "includedPaths": [{ "path": "/*" }],
  "excludedPaths": [
    { "path": "/payload/*" },
    { "path": "/diagnostics/?" },
    { "path": "/_etag/?" }
  ]
}

/payload/* — exclude an entire subtree. Useful when you’re storing large blobs of data that you only fetch by id.

/diagnostics/? — exclude one specific path. The ? matches the leaf only.

The full reference uses globs — * matches one segment, ? matches a leaf — and the most-specific match wins.

Index types

Range — the default. Supports =, <, >, <=, >=, BETWEEN, ORDER BY. Works on numbers, strings, booleans.

Spatial — for ST_DISTANCE, ST_WITHIN, polygon containment. Only on GeoJSON points/polygons. Opt-in.

Composite — required for multi-field ORDER BY. Declared as an ordered list:

{
  "compositeIndexes": [
    [
      { "path": "/tenantId", "order": "ascending" },
      { "path": "/createdAt", "order": "descending" }
    ]
  ]
}

This index serves ORDER BY c.tenantId ASC, c.createdAt DESC and the reverse. Other field orderings require additional composite indexes.

Indexing modes

• Consistent (default) — index updates synchronously with writes. Reads always see the latest. Highest write cost.
• None — no indexing. Only point reads work; queries fail. Use for write-only logs you’ll consume by Change Feed and never query directly.

There’s no “lazy” mode anymore — Cosmos retired it. Modern choice is consistent or none.

Tuning workflow

1. Run your app a week with the default policy.
2. Open the portal → container → “Indexing Metrics.” It tells you per-path utilization.
3. Look for paths with “0 reads, N writes” — those are pure cost.
4. Either exclude them with a glob, or — if you have a tightly scoped app — flip to an includedPaths allow-list.
5. Update the policy. Cosmos rebuilds in background. Watch RU/s and 429s during the rebuild.

For most teams, two iterations of this loop drop write RUs by 30–50%. Over a year, that’s the salary of an SDE.

Vector indexes

Lesson V14 covers these in depth, but worth a mention — Cosmos now has native vector indexes for similarity search. They’re declared in the index policy with their own type (quantizedFlat, diskANN) and dimension. If you’re doing RAG inside Cosmos, you’ll write this policy too.