Repository navigation
fix(mcp): stop clickstack_sql callers guessing table and timestamp names - #3354
Conversation
🦋 Changeset detectedLatest commit: 1efd7d2 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 |
|
@squaredg is attempting to deploy a commit to the HyperDX Team on Vercel. A member of the Team first needs to authorize it. |
|
Agents writing raw SQL had no tool that named a source's table, and the sql examples hard-coded otel_logs and TimestampTime. Unqualified otel_logs only resolves when tables sit in the connection's default database, and the seed otel_logs schema has no TimestampTime, so the examples fail on most schemas. - clickstack_list_sources returns each source's database-qualified table, and the database for metric sources. - The sql examples use <table> and <timestampColumn> placeholders. - Unknown-table errors hint at clickstack_list_sources.
f84f6d5 to
cf7b0d8
Compare
| } | ||
| // Checked before unknown identifiers: "Unknown table expression identifier" | ||
| // names a table, so describe_source's column list would not help. | ||
| if ( |
There was a problem hiding this comment.
🔵 minor — New unknown-table hint is SQL-specific but shown for every MCP tool's ClickHouse errors
errorHint runs for every tool that calls clickHouseErrorResult, not just clickstack_sql. That includes runQuery/runConfigQuery in helpers.ts, runEventPatterns.ts, eventDeltas.ts, trace/waterfall.ts, trace/breakdown.ts and describeMetric.ts. When a builder tool's source points at a dropped or renamed table, the agent is told to "use the table of a source from clickstack_list_sources", which is the same broken table and doesn't help, since builder tools take a sourceId. Fix: attach this hint only from sql.ts (for example via the existing suffix context, or a flag passed to errorHint). For source-backed tools, give a hint that says the source's configured table is missing.
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
There was a problem hiding this comment.
Fixed in cc07b20: errorHint only adds the unknown-table hint when called from the raw SQL path (clickHouseErrorResult(e, { rawSql: true })). Source-based tools get no hint for a missing source table, as on main. New unit tests and a clickstack_table integration test cover it.
| // connection's default database. Metric sources keep one table per | ||
| // kind in metricTables, so they get the database to qualify them with. | ||
| if (s.from.tableName) { | ||
| meta.table = `${s.from.databaseName}.${s.from.tableName}`; |
There was a problem hiding this comment.
🔵 minor — table is joined from raw names without quoting, so it can produce SQL that won't run
The code builds ${databaseName}.${tableName} from the raw names. Callers are told to paste this value into FROM, so a database or table named like otel-prod or my.logs gives invalid or misparsed SQL. Quote each part with quoteIdentifierIfNeeded (packages/common-utils/src/core/metadata.ts:158). Bare names stay unchanged, so the existing tests still pass.
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
There was a problem hiding this comment.
Fixed in 5fb2477: each part is quoted with quoteIdentifierIfNeeded, so observability-prod / otel.logs comes back as `observability-prod`.`otel.logs` and bare names are unchanged. Covered by a new list_sources test.
PR Review
2 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 2 minor 2 posted as inline comment(s) on the changed lines. Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides. |
Deep Review✅ No critical issues found. Eight reviewers ran; the three prior greptile P1s (unquoted table names, missing metric 🟡 P2 -- recommended
🔵 P3 nitpicks (5)
Reviewers (8): correctness, testing, maintainability, project-standards, kieran-typescript, api-contract, previous-comments, agent-native. 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 |
|
@squaredg can you please check the greptile feedback and fix linting? |
The cast tripped no-unsafe-type-assertion and took the api package one warning over the CI lint ceiling.
| } | ||
| // Checked before unknown identifiers: "Unknown table expression identifier" | ||
| // names a table, so describe_source's column list would not help. | ||
| if ( |
There was a problem hiding this comment.
🔵 minor — The unknown-table hint also fires for source-based builder tools, where the agent never wrote a table name
errorHint is reached through clickHouseErrorResult, which is shared by every tool: the builder path at helpers.ts:617 (clickstack_timeseries/table/search), trace/waterfall.ts, trace/breakdown.ts, eventDeltas.ts, runEventPatterns.ts and describeMetric.ts. All of these get the table from the source's from. If that table has been dropped or renamed, the agent is told to "use the table of a source from clickstack_list_sources". That table is the one that just failed, and these tools take no table argument anyway. Fix: attach this hint only on the clickstack_sql path (for example, pass it as a suffix from sql.ts), or reword it for the builder tools so it says the source's configured table is missing.
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
There was a problem hiding this comment.
Fixed in cc07b20: errorHint only adds the unknown-table hint when called from the raw SQL path (clickHouseErrorResult(e, { rawSql: true })). Source-based tools get no hint for a missing source table, as on main. New unit tests and a clickstack_table integration test cover it.
| // connection's default database. Metric sources keep one table per | ||
| // kind in metricTables, so they get the database to qualify them with. | ||
| if (s.from.tableName) { | ||
| meta.table = `${s.from.databaseName}.${s.from.tableName}`; |
There was a problem hiding this comment.
🔵 minor — The qualified table is built by plain string concatenation, so names that need quoting produce SQL that won't run
${databaseName}.${tableName} is returned for agents to paste into FROM as-is. A source whose database or table name contains -, ., or a space (allowed in ClickHouse when backtick-quoted) gives an unparseable or wrongly split FROM. Fix: backtick-quote each part, escaping backticks, when it isn't a plain identifier. The quoting rule already exists in tableExpr in packages/common-utils/src/clickhouse/index.ts:826, which renders {Identifier} parts.
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
There was a problem hiding this comment.
Fixed in 5fb2477: each part is quoted with quoteIdentifierIfNeeded, so observability-prod / otel.logs comes back as `observability-prod`.`otel.logs` and bare names are unchanged. Covered by a new list_sources test.
… its database Agents paste table into FROM, so a database like observability-prod broke the query. Metric sources that also set from.tableName got a table instead of the database their metricTables live in.
…lder guidance Source-based tools were sent back to clickstack_list_sources, which hands back the same table that just failed. The sql examples now say to use the first timestampColumn expression and how to qualify metric tables.
|
@brandon-pereira lint is fixed (1c68142: a type assertion in the new test pushed the api package one warning over the ceiling; this PR adds no net warnings now). Review feedback, all in new commits:
Deep review P3s:
Unit tests and the |
| return formatQueryResult(result); | ||
| } catch (e) { | ||
| return clickHouseErrorResult(e); | ||
| return clickHouseErrorResult(e, { rawSql: true }); |
There was a problem hiding this comment.
🔵 minor — The rawSql hint reaches dashboard raw-SQL tiles too, not just clickstack_sql
runConfigTile's raw-SQL branch is also called by clickstack_query_tile and clickstack_query_tiles (tools/dashboards/queryTile.ts:85, queryTiles.ts:303). For a tile using $__sourceTable, the failing table is the source's own table, so pointing the agent at clickstack_list_sources just returns that same table. That is the case this PR deliberately excludes for builder tools. Fix: pass rawSql from sql.ts via a runConfigTile option, or set it only when savedConfig.source is unset.
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
| // same source table that just failed. | ||
| if ( | ||
| options?.rawSql && | ||
| /Unknown table expression identifier|(Table|Database) \S+ does not exist|UNKNOWN_(TABLE|DATABASE)/.test( |
There was a problem hiding this comment.
🔵 minor — Unknown-table regex misses the "doesn't exist" wording
Older ClickHouse servers report Table db.t doesn't exist.. @clickhouse/client puts the UNKNOWN_TABLE code in error.type and leaves it out of .message, so neither branch of the regex matches on those servers. The existing int test (queryTool.int.test.ts ~line 928) already allows /doesn.t exist/ for this reason. Fix: use does(n't| not) exist, and/or check e.type for UNKNOWN_TABLE/UNKNOWN_DATABASE instead of the message.
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
…es (#3355) ## Summary `clickstack_sql` takes only a `connectionId`, so an agent has to write the table name itself, and it often guesses wrong (#3354 covers the guessing). `$__sourceTable` already exists in common-utils, and raw SQL dashboard tiles resolve it through `runConfigTile`. The MCP SQL tool just never accepted a source. This adds an optional `sourceId` to `clickstack_sql` and passes it to the tile, so `$__sourceTable` expands to that source's `database.table`. It reuses the existing `runConfigTile` path that dashboard tiles use. Checks on the input: - A `sourceId` that doesn't exist or belongs to another team is rejected as "Source not found". - A source whose connection differs from `connectionId` is rejected. Otherwise `$__sourceTable` would expand against a table on another server. - `$__sourceTable` without a `sourceId` is rejected with an error that says to pass one. Today the renderer's message comes through instead ("requires a source to be selected"), which is written for the dashboard UI. The time-series example now reads `FROM $__sourceTable`. The table example keeps `FROM <table>` to show the path for tables that aren't registered as sources. Tests (all failed before the change): - `$__sourceTable` resolves to the source's table (counts seeded rows). - `$__sourceTable` without `sourceId` is rejected, and the error says to pass one. - An unknown `sourceId` and another team's `sourceId` are both rejected as not found. - A source on a different connection than `connectionId` is rejected. - The tool schema exposes an optional `sourceId`. - The time-series example uses `$__sourceTable` and the table example uses `<table>`. This matches the `sourceId` handling in our enterprise build, which has had it since source filters were added. That build also scopes it with source filters and RBAC, which aren't part of OSS and aren't included here. ### How to test on Vercel preview N/A — non-UI change. ### References - Linear Issue: HDX-5684 - Related PRs: #3353, #3354 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Summary
Agents using
clickstack_sqlhave no tool that tells them which table a source reads from, so they guess. The tool's own examples make the guess for them:FROM otel_logsandTimestampTime.otel_logsonly resolves when the tables are in the connection's default database. That's true for the default install and false for most other deployments.otel_logsschema has noTimestampTimecolumn, so the time-series example fails even on a default install.clickstack_list_sourcesreturns each source'stimestampColumnand key columns, but not its database or table.Changes:
clickstack_list_sourcesreturnstable(<database>.<table>) for every source with a table, anddatabasefor metric sources, whose tables are already listed inmetricTables.sqlparameter examples use<table>and<timestampColumn>placeholders, with one line saying where both come from.tablefromclickstack_list_sources. Unknown-column errors keep theclickstack_describe_sourcehint.Tests (all failed before the change):
list_sourcesincludes the database-qualified table for log and trace sources, and the database for metric sources.sqlexamples use only placeholders, and run once those are filled from a source.errorHintand end to end throughclickstack_sql.Not in this PR:
prompts/dashboards/content.ts,tools/dashboards/schemas.ts) still hard-codeotel_tracesandTimestampTime. Raw SQL tiles can use$__sourceTablethere, so that's a separate change.sourceIdand$__sourceTabletoclickstack_sqlitself. I'll propose that separately.How to test on Vercel preview
N/A — non-UI change.
References
🤖 Generated with Claude Code