Clarify optimizer-controlled predicate ordering in FTS guidance

[Vsevolod Kukol (sevoku)]

Summary

Remove the claim that placing selective predicates earlier in the WHERE clause improves Cosmos DB query performance. Reconcile fts-hybrid-queries.md, the general query-order-filters.md rule, and their SKILL.md overview entries.

Problem

The FTS rule tells readers to put the most restrictive filter first, while the general filter rule explicitly claims left-to-right execution and invents intermediate row counts for equivalent queries. Both are indexed in the skill. This conflates adding useful filters with controlling evaluation order through SQL text and would leave conflicting instructions if only the FTS rule were corrected.

Selective indexed filters can narrow the matching document set, and a partition-key equality filter can scope a query to that partition. Reordering equivalent predicates is not the optimization: Cosmos DB's query engine determines predicate evaluation order.

Changes

• Preserve the recommendation to combine FTS with selective, appropriately indexed equality/range filters.
• Clarify partition-key filtering separately from textual predicate placement.
• Remove the ordering recommendation from both rules and their overview entries, and add the supporting indexing-documentation reference.
• Replace the general rule's invented execution counts and property-name selectivity rankings with equivalent-query examples, measured index-usage guidance, and a warning that Boolean regrouping can change results.

The FTS SQL and Java examples are unchanged. The general rule's examples now make clear that reordered predicates are equivalent, not a cheaper execution plan; fabricated intermediate row counts and fixed selectivity rankings are removed. Its filename and links remain stable, and both indexed rules now provide consistent optimizer-controlled guidance.

Documentation Evidence

Microsoft's Cosmos DB indexing overview explicitly states:

The order of filter clauses isn't important. The query engine figures out which predicates are more selective and run the query accordingly.

This is Cosmos DB-specific guidance, not an assumption based on other SQL engines. The correction does not promise a fixed RU reduction or a particular execution sequence.

Original Discussion And Scope

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

The follow-up review about contradictory general filter guidance is resolved by 798fcab, which includes the general-rule correction in this PR rather than leaving contradictory guidance in a companion rule.

Changes are limited to the two filter-order rules and their overview entries. Other indexing findings are being handled separately; version metadata is unchanged.

[Copilot]

Copilot review overview

🟡 Changes recommended

Reconcile contradictory filter-order guidance and bump the required metadata versions.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Reconcile conflicting query filter ordering guidance · New

What changed in this PR

This PR clarifies Cosmos DB FTS guidance by removing claims that SQL predicate order controls evaluation performance.

Changes:

• Emphasizes selective indexed filters and partition scoping.
• Updates the FTS rule and SKILL.md overview with indexing documentation.

File	Reviewed changes and findings
skills/​cosmosdb-best-practices/​SKILL.md	Updates the FTS summary. Nit (1 vote): bump the package and skill metadata version.
skills/​cosmosdb-best-practices/​rules/​fts-hybrid-queries.md	Clarifies filtering and optimizer-controlled ordering. Moderate (3 votes): reconcile the contradiction with query-order-filters.md. Nit (1 vote): bump package and skill metadata versions.

---

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

[Copilot]

Copilot review overview

🟡 Changes recommended

Repository manifests need an atomic version bump for the substantially revised rule.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Bump repository manifests for revised rule · New

Resolved since last review (1)

• Reconcile conflicting query filter ordering guidance