feat(query-insights): demote score for wasteful single-field bitmap indexes#623
Conversation
…dexes
When a bitmap index is single-field AND returns >= 20% of the collection,
the badge becomes negative and the performance score is demoted one level.
Compound indexes are excluded (bitmap prefix + selective second key is valid).
This ensures queries like find({isFamilyFriendly: true}) on a 55/45 boolean
field get 'Good' instead of 'Excellent' — signaling the index is wasteful.
There was a problem hiding this comment.
Pull request overview
Adds a new Query Insights static-analysis rule to penalize wasteful single-field bitmap indexes that return a large fraction of a collection, improving the accuracy of performance ratings for DocumentDB-specific explain plans.
Changes:
- Demotes performance score by one level and marks the
bitmap_indexbadge asnegativewhen a bitmap index is single-field and coverage is ≥ 20%. - Updates the Query Insights static analysis spec to document the demotion behavior and rationale (compound indexes excluded).
- Adds new Jest test cases covering the demotion and non-demotion scenarios.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
src/documentdb/queryInsights/query-insights-static-analysis.md |
Documents the bitmap demotion rule and updates the post-score adjustment list. |
src/documentdb/queryInsights/ExplainPlanAnalyzer.ts |
Implements single-field bitmap detection via indexUsage[].scanKeys and applies badge/score demotion. |
src/documentdb/queryInsights/ExplainPlanAnalyzer.addIndexStrategyAdvisories.test.ts |
Adds/extends bitmap advisory tests to validate demotion behavior and compound-index exclusion. |
Adds Math.min(..., 1) to the bitmap demotion coverage calculation, matching the earlier coverage-badge logic. Prevents displaying >100% when totalCollectionDocs is an underestimate.
Updates the static-analysis spec and the JSDoc on addIndexStrategyAdvisories() to reflect that bitmap index and severe multikey expansion advisories can demote scores.
Changes isSingleField from .some() to a strict check requiring exactly one indexUsage entry with exactly one scanKey. Mixed entries are conservatively treated as compound to avoid false demotions. Adds a test for the mixed-entry edge case.
|
Review fix #3: Fixed in 12127d3 — changed Added a test ( |
On plans with multiple IXSCAN stages (e.g., OR, index intersection), findStageInPlan could return different index scans for the planner and execution trees. Now correlates by indexName so the bitmap flag and scanKeys are read from the same index. Adds a test for the mismatched-indexName edge case.
|
Review fix #4: Planner IXSCAN and execution-stats IXSCAN are not correlated Fixed in bb5a427 — the bitmap check now correlates the planner IXSCAN and the execution-stats IXSCAN by Added a test ( |
Moves the duplicated scoreOrder/demotion pattern into a shared private static method and a module-level SCORE_ORDER constant. Both bitmap and multikey demotion blocks now use the helper.
makeExplainResult now accepts an nReturned option so the raw executionStats.nReturned stays in sync with the analysis object. All tests that override analysis.nReturned now pass the same value to the fixture.
Adds a test confirming that bitmap and severe multikey demotions stack independently (e.g., excellent → fair when both fire). Documents this in the static-analysis spec.
|
Review fix #7: Double-demotion behavior is not specified Fixed in a229c1e — added a test ( Also documented this in the static-analysis spec under a new "Cumulative demotions" note. |
✅ Code Quality Checks
This comment is updated automatically on each push. |
📦 Build Size Report
Download artifact · updated automatically on each push. |
Summary
Adds a score demotion rule to the Query Insights static analysis for single-field bitmap indexes that return a large fraction of the collection.
Previously, a query using a bitmap index with high selectivity (≥20% of documents returned) could still receive an
Excellentperformance rating because the index was technically efficient —docsExamined ≈ nReturned. This was misleading: bitmap indexes on low-cardinality fields carry ongoing write and storage overhead that outweighs the marginal read benefit when the index returns many documents.What changed
isBitmap: true, the index is single-field, and selectivity ≥ 20%, the bitmap badge type is set tonegativeand the performance score is demoted one level (e.g.Excellent→Good).query-insights-static-analysis.mddocuments the demotion table and design decision.ExplainPlanAnalyzer.addIndexStrategyAdvisories.test.ts; all 10 bitmap tests pass.Non-DocumentDB safety
isBitmapis a DocumentDB-specific explain plan field. Standard MongoDB explain plans never include it, so this rule is never triggered for non-DocumentDB clusters.