Skip to content

feat(tools): report the query optimiser's plan for a ranked query - #141

Merged
lcottercertinia merged 1 commit into
certinia:mainfrom
lukecotter:120-query-plans
Aug 14, 2026
Merged

feat(tools): report the query optimiser's plan for a ranked query#141
lcottercertinia merged 1 commit into
certinia:mainfrom
lukecotter:120-query-plans

Conversation

@lukecotter

Copy link
Copy Markdown
Collaborator

Closes #120

apexlog_list_slow_operations returns a second queryPlans table: one row of {name, leadingOperationType, relativeCost, cardinality, sObjectCardinality} per query it ranked and the log explained.

SOQL_EXECUTE_EXPLAIN is a direct child of its SOQL_EXECUTE_BEGIN, so the plan correlates structurally — no line-number matching.

Why a 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 what the response says rather than ranking a second time, it obeys limit for free, and a response with no query among its slowest rows pays nothing.

What it reports, and what it does not

relativeCost is the figure; the verdict is the caller's — above 1 the optimiser does not treat the query as selective. sObjectType is left out (it is in the query text the row is named by) and fields is an array, which breaks the tabular form. cardinality and sObjectCardinality cost 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,FINEST alone, so the table is left out when none was recorded, and the dbLevel scalar beside it says whether one could have been.

The name repeats the query text from the operations row, as the join key. Measured on real logs an index into the ranked rows is cheaper but error-prone to count; limitsByNamespace repeats limit names on the same rule.

Cost

apexlog_list_slow_operations on governor-heavy.log moves ~320 → ~390 tokens, still 4% under 1.x. The definition moves ~361 → ~377 for one clause in the description. Both budgets raised deliberately in scripts/eval.mjs; both README tables regenerated.

Verification

pnpm run build, pnpm test (282 tests) and pnpm run eval pass. 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 to governor-heavyminimal.log runs no query, and the harness gained a per-fixture filter for it.

`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
lcottercertinia merged commit 42d016d into certinia:main Aug 14, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: report the query optimiser's selectivity verdict

2 participants