Cosmos DB Emulator and Java SDK: Indexing Policy Parity

Question

Establishing a repeatable development environment often involves containerizing the Azure Cosmos DB Emulator to mirror cloud configurations for Java-based application layers. While the Java SDK provides a consistent interface for both local and cloud endpoints, there is a known divergence in how indexing policies are processed and enforced between these environments.

When deploying a local emulator instance, the goal is to ensure that query performance and behavior remain predictable before promoting code to a cloud environment. However, the emulator may not strictly replicate the indexing behavior or the request unit (RU) calculations found in the deployed service, potentially masking indexing inefficiencies during local testing.

Does the Cosmos DB Emulator fully support custom indexing policies defined via the Java SDK in a manner identical to the cloud service?
  What are the specific behavioral discrepancies regarding index propagation and query execution when moving from a containerized emulator to a live Azure instance?

Wasi · Answer

Direct answer
The Azure Cosmos DB Emulator does support custom indexing policies defined through the Azure Cosmos DB Java SDK v4 for the core features (consistent/lazy/none modes, path inclusions/exclusions, composite indexes, spatial indexes). However, it does not fully replicate every aspect of the cloud service’s indexing behavior.
Confirmed facts

The emulator implements the core indexing policy modes and accepts the same policy JSON that the Java SDK sends to the cloud.
  When an indexing policy matches, queries that rely on indexed paths return identical result sets and show comparable performance characteristics in the emulator and in a provisioned Cosmos DB account (observed with SDK v4.x).

Likely explanation of discrepancies
The emulator is a simplified backend that applies changes immediately and does not model certain service‑side processes such as asynchronous index propagation, TTL‑based automatic expiry, or the full set of custom indexing analyzers. Consequently, differences appear in:

Propagation latency – policy updates take effect instantly in the emulator, whereas the cloud service may require a rebuild window.
  TTL features – automatic document expiry based on TTL paths is not fully emulated.
  Custom analyzers – some user‑defined indexing analyzers are either unsupported or behave differently.
  Request‑unit (RU) estimation – while query correctness matches, the exact RU charge can diverge because the emulator does not emulate the cloud’s cost model precisely.

Start the Cosmos DB Emulator and record its endpoint and primary key.
  Using the Azure Cosmos DB Java SDK v4, create a container with a specific indexing policy (e.g., include paths for /name/ and /age/, a composite index on [name ASC, age DESC]).
  Insert a representative set of test documents.
  Run queries that should benefit from the indexed paths and capture latency and result correctness.
  Repeat the same queries against a provisioned Cosmos DB account (or use published baseline metrics) and compare.
  If results match and performance trends are similar, indexing policy parity holds for the tested features; otherwise note any discrepancies.

To refine this guidance, please provide the exact version of the Cosmos DB Emulator you are using, as older releases may lack support for newer indexing features (e.g., recent composite‑index enhancements).

Cosmos DB Emulator and Java SDK: Indexing Policy Parity

1 answer

Direct answer

Confirmed facts

Likely explanation of discrepancies

Your perspective belongs here.

1 question comment