Repository navigation
feat(mcp): run multiple clickstack_sql queries in parallel - #3421
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: e7f6db7 The changes in this PR will be included in the next version bump. This PR includes changesets to release 3 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
| }; | ||
| try { | ||
| const prepared = await prepareSqlQuery( | ||
| { |
There was a problem hiding this comment.
🔵 minor — Batch runner and its 60s budget duplicate the queryTiles batch loop
runSqlBatch re-implements the loop in packages/api/src/mcp/tools/dashboards/queryTiles.ts (lines 229-312): a PQueue, a shared deadlineAt, withDeadline around runConfigTile with an abort signal, folding each result into an ok/error entry, and a summary count. SQL_BATCH_DEADLINE_MS = 60_000 also restates BATCH_DEADLINE_MS = 60_000 from queryTiles, so the two tools' budgets now have to be kept in sync by hand. The PR already moved withDeadline into mcp/utils/timeout.ts; move the shared deadline constant there too, or a small generic runBatchUnderDeadline(items, concurrency, work) helper, and have both tools import it.
Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond
|
|
||
| /** Total serialized size budget split evenly across the batch's results. */ | ||
| const SQL_BATCH_RESPONSE_BUDGET = 100_000; | ||
| const SQL_SINGLE_RESPONSE_LIMIT = 50_000; |
There was a problem hiding this comment.
🔵 minor — SQL_SINGLE_RESPONSE_LIMIT restates trimToolResponse's default
SQL_SINGLE_RESPONSE_LIMIT = 50_000 copies the default maxSize = 50000 in packages/api/src/utils/trimToolResponse.ts:17, which is the limit single-query clickstack_sql actually uses. If that default changes, batch mode silently stops matching. Export the default from trimToolResponse.ts (e.g. DEFAULT_TOOL_RESPONSE_MAX_CHARS) and use it in both places.
Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond
PR Review
3 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 3 minor 2 posted as inline comment(s) on the changed lines. 1 listed below. Findings outside the changed lines1 minor
Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides. |
[Medium impact] The PR appears safe to merge; no new actionable issues were found. SummaryAdds parallel queries to
|
Deep Review✅ No critical issues found. The batch runner is careful and unusually well-tested — the 🟡 P2 -- recommended
🔵 P3 nitpicks (7)
Reviewers (9): correctness, adversarial, testing, maintainability, kieran-typescript, reliability, performance, previous-comments, project-standards. Testing gaps:
No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond |
| return { raw: text }; | ||
| } | ||
|
|
||
| /** The row array of an ok entry: `result` itself, or ClickHouse's `result.data`. */ |
There was a problem hiding this comment.
🔵 minor — rowsOf re-implements the row extraction in summarizeRows
summarizeRows in packages/api/src/mcp/tools/dashboards/queryTiles.ts (L89-100) already turns a formatQueryResult payload into rows: result when it is an array, or result.data. Move that into a shared helper (e.g. extractRows(result) next to formatQueryResult in query/helpers.ts) and use it from both places, so a change to the payload shape only has to be made once. The 60s deadline is also duplicated: BATCH_DEADLINE_MS in queryTiles.ts L59 and SQL_BATCH_DEADLINE_MS here. Share it from mcp/utils/timeout.ts, next to withDeadline.
Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond
…-queries # Conflicts: # packages/api/src/mcp/tools/query/sql.ts
🟡 Tier 3 — StandardIntroduces new logic, modifies core functionality, or touches areas with non-trivial risk. Why this tier:
Review process: Full human review — logic, architecture, edge cases. Stats
|
Duplicate code analysisNo new duplicate code introduced by this PR. jscpd compared this branch against |
| * ClickHouse's own max_execution_time; this bounds the call as a whole so a | ||
| * queue of slow queries cannot run past the client's patience. | ||
| */ | ||
| export const SQL_BATCH_DEADLINE_MS = 60_000; |
There was a problem hiding this comment.
🔵 minor — Batch deadline constant and batch-runner pattern duplicated from queryTiles.ts
SQL_BATCH_DEADLINE_MS = 60_000 restates BATCH_DEADLINE_MS in packages/api/src/mcp/tools/dashboards/queryTiles.ts:60. Both files also repeat the same PQueue + shared deadlineAt + per-item try/catch + status-summary loop. withDeadline was moved to mcp/utils/timeout.ts, so export one batch deadline constant from there too (ideally with a small shared runner) instead of keeping two copies that must be kept in sync by hand.
Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond
E2E Test Results✅ All tests passed • 460 passed • 1 skipped • 1561s
Tests ran across 4 shards in parallel. |
| } | ||
| const payload = { summary, results }; | ||
| fitToBudget(payload, SQL_BATCH_RESPONSE_BUDGET); | ||
| const trimmed = results.filter(entry => entry.note !== undefined).length; |
There was a problem hiding this comment.
🔵 minor — mcp.sql.batch.trimmed also counts queries that runConfigTile trimmed, not just ones the batch budget trimmed
parsePayload copies runConfigTile's own note ("Result was trimmed for context size…", from formatQueryResult in helpers.ts) onto the entry. So entry.note !== undefined is true for every query trimmed per-query, even when fitToBudget never touched it. Track batch trimming separately: have setRows/fitToBudget return or record the indices it trimmed, and count those.
Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond
| } | ||
|
|
||
| /** The row array of an ok entry: `result` itself, or ClickHouse's `result.data`. */ | ||
| function rowsOf(entry: SqlBatchEntry): unknown[] | undefined { |
There was a problem hiding this comment.
🔵 minor — rowsOf repeats the row extraction in summarizeRows
summarizeRows in packages/api/src/mcp/tools/dashboards/queryTiles.ts (lines 90-101) already turns a result that is either an array or { data: [] } into rows. Move that branch into a shared helper (e.g. extractRows(result) in query/helpers.ts next to formatQueryResult) and use it in both places. The DRY rule in the conventions is marked REQUIRED.
Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond
|
This PR currently has a merge conflict. Please resolve this and then re-add the |
…-queries # Conflicts: # packages/api/src/mcp/tools/dashboards/queryTiles.ts
| } | ||
|
|
||
| /** The row array of an ok entry: `result` itself, or ClickHouse's `result.data`. */ | ||
| function rowsOf(entry: SqlBatchEntry): unknown[] | undefined { |
There was a problem hiding this comment.
🔵 minor — rowsOf duplicates the row extraction in summarizeRows
summarizeRows in packages/api/src/mcp/tools/dashboards/queryTiles.ts:91-102 already reads rows from a payload's result, whether it is a top-level array or a { data: [...] } object. Move that logic into a shared helper next to formatQueryResult in query/helpers.ts, which produces the payload, and have both callers use it.
Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond
| * ClickHouse's own max_execution_time; this bounds the call as a whole so a | ||
| * queue of slow queries cannot run past the client's patience. | ||
| */ | ||
| export const SQL_BATCH_DEADLINE_MS = 60_000; |
There was a problem hiding this comment.
🔵 minor — The 60s batch deadline is defined twice
SQL_BATCH_DEADLINE_MS = 60_000 repeats BATCH_DEADLINE_MS = 60_000 in packages/api/src/mcp/tools/dashboards/queryTiles.ts:61. The PQueue + withDeadline + error-to-status loop is also repeated (queryTiles.ts:233-301). withDeadline already moved to mcp/utils/timeout.ts, so put one exported batch deadline constant there and have both tools import it.
Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond
Summary
Agents investigating an incident often need several independent raw SQL queries (compare two sources, a few breakdowns of the same window). Today each one is a separate
clickstack_sqlround trip. This adds aqueriesarray so one call runs up to 10 of them in parallel.clickstack_sqltakes eithersql(unchanged) orqueries: [{ id?, sql, connectionId?, sourceId? }]. Queries sharestartTime/endTimeand default to the top-levelconnectionId/sourceId.ok,error, ortimeout, in input order, with its index and optionalid. One bad query doesn't fail the call;isErroris set only when every query fails.$__sourceTablewithout a source) moved intoprepareSql.tswith no behavior change. Source lookups are cached per call.withDeadlinemoved fromqueryTiles.tstomcp/utils/timeout.tsso both batch tools share it.mcp.sql.modeandmcp.sql.batch.*span attributes, plus ahyperdx.mcp.sql.batch.queriescounter tagged by status.Schema change to note:
sqlis no longer in the tool'srequiredlist, sincesqlandqueriesare alternatives. The handler rejects calls that pass both or neither.We looked at MCP tasks for this and decided against them for now: the SDK API is experimental, and the 2026-07-28 spec moved tasks into a separate, redesigned extension that the v2 SDK doesn't implement on the server.
How to reproduce
Starting point:
yarn dev, then connect an MCP client (e.g.yarn dev:mcpinpackages/apifor the inspector) with a personal API key.On
main:clickstack_sqlwithqueries: [{ "sql": "SELECT 1" }]and anyconnectionId. The call fails becausesqlis required andqueriesis unknown.On this branch:
clickstack_sqlwith aconnectionIdandqueries: [{ "id": "a", "sql": "SELECT 1 AS v" }, { "id": "b", "sql": "SELECTT 1" }].summary: { total: 2, ok: 1, error: 1, timeout: 0 }, rows fora, and a syntax error forb.sql: "SELECT 1"and confirm the response matchesmain.How to test on Vercel preview
N/A — non-UI change.
References