Distinguish required composite indexes from query optimizations

[Vsevolod Kukol (sevoku)]

Summary

Correct index-composite.md and index-composite-direction.md to consistently distinguish required multi-property sorting indexes from optional equality-filtered sort optimizations, and explain supported sort directions.

Problem

The rule says any equality filter combined with sorting on another property requires a composite index, otherwise the query fails in production or needs client-side sorting. It repeats that claim in the emulator warning, TypeScript example, and type-discriminator guidance.

A single-property ORDER BY can instead use the default range indexes. Composite indexes can improve RU efficiency for suitable query shapes, but a filter or type discriminator alone does not make them mandatory.

The related direction rule also incorrectly requires composites for all cross-partition sorts, shows one-property composites, and requires duplicate inverse-direction indexes. The Node.js examples need explicit container references and independent setup so the baseline container does not silently retain its original policy during the optimization example.

Changes

• State the actual requirement: sorting on two or more properties requires a matching composite index.
• Remove the claim that the single-property TypeScript example fails in production and present it as a valid baseline.
• Show the documented optimization rewrite: add equality-filtered properties before the original sort property in ORDER BY and provide a matching composite index. Those properties are constant within the filtered results, preserving the requested ordering.
• Align the related C#, Java, and TypeScript example descriptions with their composite-index paths.
• Replace blanket type-discriminator requirements with workload-dependent optimization guidance and recommend measuring request charges.
• Use two-property direction examples showing that one index supports both its declared directions and their full reverse, but not a partial reversal; remove redundant inverse indexes from the companion example.
• Make the Node.js baseline and optimized examples independent, with distinct container IDs, fresh create() calls, and the returned container references. Existing IDs fail explicitly instead of silently retaining a different policy.

Documentation Evidence

Microsoft's composite-index documentation states that queries with ORDER BY on two or more properties require a composite index.

The filter-and-ORDER-BY section explicitly says that without a composite index for a filter on one property and sorting on another, "the query will still succeed", while a composite index can reduce RU cost. It demonstrates rewriting WHERE c.name = "John" ORDER BY c.timestamp as ORDER BY c.name, c.timestamp to apply a composite index.

The same indexing-policy documentation specifies two or more composite paths and support for the "opposite order on all paths." The JavaScript SDK implementation returns an existing container from createIfNotExists() without applying the supplied creation policy, motivating the explicit fresh-container setup.

Original Discussion And Scope

Addresses the original review discussion on microsoft/vscode-cosmosdb#3355, where the rule is vendored into the VS Code extension.

The follow-up consistency review and example-setup concerns from the review summary are addressed by fb28dd1. Changes are confined to the two composite-index rules; version metadata is unchanged.

The existing-container replacement example is untouched; its settings-preservation fix remains in #258, which is not included in this branch.

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved moderate issues affect example correctness and consistency with related guidance.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Resolve contradictory guidance on composite indexes for single-property sorts · New
• Bump package and skill manifests to the corrected rule version · New

What changed in this PR

This PR corrects Cosmos DB composite-index guidance by distinguishing required multi-property indexes from optional filter-and-sort optimizations.

Changes:

• Clarifies composite-index requirements for multi-property ORDER BY.
• Adds equality-filtered ORDER BY optimization examples.
• Updates SDK and type-discriminator guidance.

File	Summary and findings
skills/​cosmosdb-best-practices/​rules/​index-composite.md	Revises composite-index guidance and examples. Findings: Moderate (1 vote): optimization setup ignores the policy created by the baseline path. Moderate (3 votes): guidance conflicts with index-composite-direction.md. Nit (3 votes): manifests remain at version 1.2.0. Moderate (1 vote): the baseline example uses an uninitialized container.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Review comments identify unresolved version-metadata and evaluation-guidance updates needed before approval.

Review effort: Lite
Findings: None

Resolved since last review (2)

• Resolve contradictory guidance on composite indexes for single-property sorts
• Bump package and skill manifests to the corrected rule version