feat(tools): report the query optimiser's plan for a ranked query - #141
Merged
Conversation
`SOQL_EXECUTE_EXPLAIN` sits directly under the query it explains, so the
plan correlates structurally. `apexlog_list_slow_operations` now returns a
`queryPlans` table of {name, leadingOperationType, relativeCost,
cardinality, sObjectCardinality} rows for the queries it ranked.
A separate table, not a column: `relativeCost` is null on every row that is
not a query, and TOON's tabular form needs one key set per table. Only the
returned rows are explained, so the table qualifies the response rather
than ranking a second time, and it obeys `limit` for free.
The worst plan wins where one query was explained more than once — a plan
that was selective on one call does not make the query selective.
A plan is emitted at `DB,FINEST` alone, so the table is left out when none
was recorded; `dbLevel` says whether one could have been.
Closes certinia#120
lcottercertinia
approved these changes
Aug 14, 2026
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.
Closes #120
apexlog_list_slow_operationsreturns a secondqueryPlanstable: one row of{name, leadingOperationType, relativeCost, cardinality, sObjectCardinality}per query it ranked and the log explained.SOQL_EXECUTE_EXPLAINis a direct child of itsSOQL_EXECUTE_BEGIN, so the plan correlates structurally — no line-number matching.Why a table, not a column
relativeCostis null on every row that is not a query, and TOON's tabular form needs one key set per table. Only the returned rows are explained, so the table qualifies what the response says rather than ranking a second time, it obeyslimitfor free, and a response with no query among its slowest rows pays nothing.What it reports, and what it does not
relativeCostis the figure; the verdict is the caller's — above 1 the optimiser does not treat the query as selective.sObjectTypeis left out (it is in the query text the row is named by) andfieldsis an array, which breaks the tabular form.cardinalityandsObjectCardinalitycost about two tokens each, are not derivable, and change the reading: an unselective query over a tiny object does not matter.The worst plan wins where one query text was explained more than once. A plan that was selective on one call does not make the query selective.
A plan is emitted at
DB,FINESTalone, so the table is left out when none was recorded, and thedbLevelscalar beside it says whether one could have been.The
namerepeats the query text from theoperationsrow, as the join key. Measured on real logs an index into the ranked rows is cheaper but error-prone to count;limitsByNamespacerepeats limit names on the same rule.Cost
apexlog_list_slow_operationsongovernor-heavy.logmoves ~320 → ~390 tokens, still 4% under 1.x. The definition moves ~361 → ~377 for one clause in the description. Both budgets raised deliberately inscripts/eval.mjs; both README tables regenerated.Verification
pnpm run build,pnpm test(282 tests) andpnpm run evalpass. New jest cases pin the plan on a ranked query, the worst-plan rule, the row cap, the absent table, and a plan the log did not record in full. The eval gains an answerability question, restricted togovernor-heavy—minimal.logruns no query, and the harness gained a per-fixture filter for it.