Add query --explain to show execution plan and index usage#131
Open
mkrueger wants to merge 4 commits into
Open
Add query --explain to show execution plan and index usage#131mkrueger wants to merge 4 commits into
mkrueger wants to merge 4 commits into
Conversation
Implements a --explain flag on the query command that reports the query execution plan (utilized/potential indexes, index hit ratio, retrieved/output document counts, request charge) and a plain-language evaluation instead of returning documents. - Executes only the first page (MaxItemCount = 1) to keep RU cost low; reported metrics are an estimate. - Interactive sessions render a human-readable table with verdict lines; MCP, output redirection, and explicit --format json emit structured JSON. - Adds PlanEvaluation record, ParseIndexPlan, and EvaluatePlan helpers with unit tests. - Updates localization strings, docs/commands.md, and README. Closes #106
Contributor
There was a problem hiding this comment.
Pull request overview
Adds an --explain mode to the existing query command so the shell can report Cosmos DB query execution/index usage (human-readable in interactive sessions, structured JSON for MCP/redirected output), along with the supporting docs, localization, and unit tests.
Changes:
- Extend
QueryCommandwith--explainexecution path, plan parsing/evaluation helpers, and shared request-failure handling. - Introduce
PlanEvaluationdata model and add unit tests forParseIndexPlan/EvaluatePlan. - Update localization strings and user docs (
README.md,docs/commands.md) to describe the new option.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| README.md | Advertises query "<sql>" --explain as a supported feature. |
| docs/commands.md | Documents --explain usage, output intent, and cost/limit behavior. |
| CosmosDBShell/lang/en.ftl | Adds help text and user-facing strings for explain output. |
| CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/QueryCommand.cs | Implements explain execution, plan parsing/evaluation, rendering/JSON output, and refactors request error handling. |
| CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/PlanEvaluation.cs | Adds a record type to carry explain evaluation data. |
| CosmosDBShell.Tests/CommandTests/QueryCommandTests.cs | Adds unit coverage for explain plan parsing and evaluation behaviors. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements
query "<sql>" --explain, which reports how the query engine resolves a query instead of returning documents. Closes #106.The output shows whether the query performed a full scan or an index seek, lists the utilized and potential indexes, the index hit ratio, retrieved/output document counts, and the request charge, plus a plain-language evaluation that highlights full scans and recommends indexes to add.
Behavior
MaxItemCount = 1) to keep RU cost low. Reported metrics are an estimate based on that page.--maxis ignored when--explainis supplied.McpPort), output redirection (StdOutRedirect), and explicit--format jsonemit the structured JSON plan/evaluation document, so AI tool integration is unaffected.Changes
QueryCommand: new--explainoption,ExecuteExplainAsync,RenderExplain,BuildExplainJson, and extractedThrowIfRequestFailedAsyncshared with the normal query path.ParseIndexPlanandEvaluatePlanplus thePlanEvaluationrecord (own file).lang/en.ftl.docs/commands.mdquery section andREADME.mdfeature list.EvaluatePlan(full scan / index seek / recommendations) andParseIndexPlan(single + composite specs, null/empty/whitespace, malformed JSON).Validation
dotnet buildmain + test projects: 0 warnings / 0 errors.QueryCommandTests: 16 passing (8 new).Example:
