{{ message }}
feat(advisor): read-only EXPLAIN-based query cost estimator (plan 49) - #2233
Merged
Conversation
Add estimate_query_cost, a pre-flight agent tool that estimates rows scanned, bytes read, peak memory, and wall time for a query from EXPLAIN alone. It never executes or mutates the analyzed query - only ever runs EXPLAIN json=1,header=1,indexes=1 through the existing readonly transport, gated by the same SQL validator as the rest of the agent tools. Parses the plan's ReadFromMergeTree/Join/Aggregating nodes (shape verified against ClickHouse's own EXPLAIN json test fixtures) and combines granule-pruning counts with system.columns sizing to derive the estimate; peak memory follows max(scan floor, join build side, aggregation state) rather than total bytes read, since ClickHouse streams a plain scan rather than materializing it. Co-Authored-By: duyetbot <bot@duyet.net>
duyet
enabled auto-merge (squash)
July 3, 2026 13:05
github-actions
Bot
added
documentation
This was referenced Jul 3, 2026
Co-Authored-By: duyetbot <bot@duyet.net>
Co-Authored-By: duyetbot <bot@duyet.net>
…stimator tsc flagged `t` as possibly null in the read-table filter — `Boolean(t)` doesn't narrow for TypeScript. Use optional chaining instead. Co-Authored-By: duyetbot <bot@duyet.net>
Contributor
☁️ Cloudflare Preview Deployment
|
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
1 participant
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.
What (plan 49 — query cost estimator)
Read-only
estimateQueryCost(sql, hostId)that runsEXPLAIN json=1, header=1, indexes=1(never the raw SQL) and returns{ estRows, estBytesRead, estPeakMemoryBytes, estWallMs, confidence, warnings[] }, exposed as the agent toolestimate_query_cost.lib/ai/advisor/cost-estimator.ts+ 17 tests; parser grounded against ClickHouse's own EXPLAIN fixtures.ALTER/DROP/INSERT) throws beforefetchDatais called, and the EXPLAIN call setsreadonly=1.bun test src/lib/ai/advisor src/lib/ai/agent/tools --isolate→ 148 pass, 0 fail.bun run check/depcruiseclean.Reviewer note — parallel tool-count coordination
Bumps
tool-docs-sync.test.ts(24→25) and updatesai-agent.mdx. Held plans 46 (advisor engine) and 47 (MV designer) also add agent tools; whichever merges after this must reconcile the tool count. This PR is safe to land first (read-only, self-contained).Risk
Read-only; no billing/security/destructive surface.
Co-Authored-By: duyetbot bot@duyet.net