Skip to content

fix(mcp): bind interval params in clickstack_sql - #3353

Merged
kodiakhq[bot] merged 3 commits into
ClickHouse:mainfrom
squaredg:claude/hdx-5682-sql-interval-params
Oct 13, 2026
Merged

kodiakhq[bot] merged 3 commits into
ClickHouse:mainfrom
squaredg:claude/hdx-5682-sql-interval-params

Conversation

@squaredg

Copy link
Copy Markdown
Contributor

Summary

clickstack_sql's description advertises {intervalSeconds:Int64}, {intervalMilliseconds:Int64}, $__interval_s, $__timeInterval and $__timeInterval_ms, but every one of them failed with Substitution intervalSeconds is not set. That includes the tool's own time-series example, so an agent following the description gets an error.

The cause: the tool renders its query as a table tile. For raw SQL, displayType only selects which query params get bound (QUERY_PARAMS_BY_DISPLAY_TYPE in common-utils/src/rawSqlParams.ts), and only time-series types bind the interval params.

The fix renders the query as a line tile instead. Rows come back the same for any display type, and ClickHouse ignores params a query doesn't reference, so queries without interval macros are unaffected.

Tests added to queryTool.int.test.ts:

  • interval params and $__interval_s resolve to the same bucket size (ms = s × 1000)
  • time-series queries bucketed with $__timeInterval and $__timeInterval_ms run
  • a plain query returns its rows unchanged

The first two failed before the fix with the substitution error.

Not in this PR: the description's examples also filter on TimestampTime, which the seed otel_logs schema doesn't have. I'll fix that separately.

How to test on Vercel preview

N/A — non-UI change.

References

  • Linear Issue: HDX-5682
  • Related PRs:

🤖 Generated with Claude Code

clickstack_sql rendered its query as a table tile, and raw SQL only binds
{intervalSeconds} and {intervalMilliseconds} for time-series display types.
Every interval parameter and macro the tool description advertises
($__interval_s, $__timeInterval, $__timeInterval_ms), including its own
time-series example, failed with "Substitution intervalSeconds is not set".

Render as a line tile instead. displayType only picks which params to bind,
rows come back the same, and ClickHouse ignores params a query never uses.
@changeset-bot

changeset-bot Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 586c9d4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages
Name Type
@hyperdx/api Patch
@hyperdx/app Patch
@hyperdx/otel-collector Patch

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

@vercel

vercel Bot commented Oct 11, 2026

Copy link
Copy Markdown

@squaredg is attempting to deploy a commit to the HyperDX Team on Vercel.

A member of the Team first needs to authorize it.

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

✅ No issues found.

@greptile-apps

greptile-apps Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Medium impact] The PR appears safe to merge.

Summary

clickstack_sql now uses line to bind the interval parameters already promised by its description.

  • Raw SQL time-series queries now get their bucket-size parameters.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[clickstack_sql] --> B[Raw SQL tile with line display type]
  B --> C[Bind time range and interval parameters]
  C --> D[Expand SQL macros]
  D --> E[ClickHouse]
  E --> F[Return JSON rows]
Loading

Reviews (3) · Last reviewed commit: "Merge branch 'main' into claude/hdx-5682..." · Reviewed by Greptile

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

The change switches clickstack_sql's internal tile from displayType: 'table' to 'line' so the interval/bucket-size params the tool advertises actually bind. The core risk — whether rendering raw SQL as line alters the returned rows versus table — was traced end to end and confirmed safe: for configType:'sql', renderRawSqlChartConfig (packages/common-utils/src/core/renderChartConfig.ts) only substitutes macros and selects which params to bind via QUERY_PARAMS_BY_DISPLAY_TYPE, the raw-SQL branch of runConfigTile injects no GROUP BY / ORDER BY / bucketing / limit / gap-fill, and queryChartConfig returns resp.json() verbatim. The only behavioral delta is that intervalSeconds / intervalMilliseconds are now bound, which ClickHouse ignores when unreferenced. The changeset is correct (the fixed group in .changeset/config.json auto-bumps @hyperdx/app and @hyperdx/otel-collector, so declaring only @hyperdx/api is intentional), and the prior Deep Review P3 concerns are resolved in the current head — the $__timeInterval tests now seed logs and assert bucket-boundary alignment and one row per bucket rather than passing on an unseeded table.

🔵 P3 nitpicks (2)
  • packages/api/src/mcp/tools/query/sql.ts:79 — the tool description still states "Results are always returned as table rows" while the tile is now built with displayType: 'line'; rows are still returned as rows, but the wording reads in tension with the literal for a reader comparing the two.
    • Fix: note in the description or the adjacent comment that line is chosen only to select which query params bind, not to change the result shape.
    • maintainability
  • packages/api/src/mcp/__tests__/queryTool.int.test.ts:816 — the "returns plain query rows unchanged" test only covers a single constant-row SELECT, so no test pins the central claim that a multi-row, ordered, LIMIT-ed table-shaped query returns identical rows under line as it did under table.
    • Fix: add a case asserting a multi-row ordered/limited raw query returns the same rows, as a regression guard for the display-type switch.
    • correctness

Reviewers (5 returned): correctness, maintainability, project-standards, previous-comments, learnings-researcher.

Coverage: 4 of 9 dispatched reviewers (testing, api-contract, kieran-typescript, agent-native) had not returned at synthesis time and are not reflected above; the api-contract response-shape question they would have examined was independently resolved by the correctness reviewer's trace of the raw-SQL render path. The displayType: 'line' selection is an implicit cross-package coupling on QUERY_PARAMS_BY_DISPLAY_TYPE — mitigated by the explanatory comment and the interval-bucket test, but it would break silently if a future change made DisplayType.Line reshape raw-SQL rows.

Testing gaps:

  • No regression test asserting multi-row/ordered/limited raw queries return byte-identical rows under line vs the former table.
  • No test exercises a large date range where auto-granularity picks a large bucket, confirming the bound {intervalSeconds} value stays a valid integer Int64 across the granularity ladder.
  • The tool description's time-series example filters on TimestampTime, a column the seed otel_logs schema may lack; an agent copying the example verbatim could still error. The description text is unchanged by this diff (pre-existing) and the author states it is deferred to a follow-up.

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

The $__timeInterval tests queried otel_traces, which this suite never seeds,
so they passed on an empty result. Seed logs and assert each bucket starts on
an interval boundary and holds one row.
@squaredg

squaredg commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor Author

Re: Deep Review P3s

  1. Leaving as is: binds the interval parameters and $__interval_s to the same bucket size already fails if Line stops binding the interval params, since it goes through the real renderer. A unit test on the mapping would cover the same thing.
  2. Fixed in a5aa7af. The $__timeInterval tests queried otel_traces, which this suite never seeds, so they passed on an empty result. They now seed logs and assert each bucket starts on an interval boundary and holds one row. Both tests fail with the fix reverted.

Re: second-round P3s — no change for either.

  1. The description is still accurate (results are table rows), and the comment above displayType says line only selects which params bind.
  2. Row identity follows from the renderer path Deep Review traced; I'd rather not grow the PR for it.

That's two rounds of automated review, so I'm leaving the rest to a maintainer. @brandon-pereira could you review and merge when you have a moment?

@brandon-pereira brandon-pereira left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM - good find!

@kodiakhq
kodiakhq Bot merged commit cdfae45 into ClickHouse:main Oct 13, 2026
38 of 43 checks passed
kodiakhq Bot pushed a commit that referenced this pull request Oct 13, 2026
…mes (#3354)

## Summary

Agents using `clickstack_sql` have 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_logs` and `TimestampTime`.

- An unqualified `otel_logs` only resolves when the tables are in the connection's default database. That's true for the default install and false for most other deployments.
- The seed `otel_logs` schema has no `TimestampTime` column, so the time-series example fails even on a default install.
- `clickstack_list_sources` returns each source's `timestampColumn` and key columns, but not its database or table.
- Unknown-table errors come back with no hint.

Changes:
- `clickstack_list_sources` returns `table` (`<database>.<table>`) for every source with a table, and `database` for metric sources, whose tables are already listed in `metricTables`.
- The `sql` parameter examples use `<table>` and `<timestampColumn>` placeholders, with one line saying where both come from.
- Unknown-table and unknown-database errors get a hint pointing at the `table` from `clickstack_list_sources`. Unknown-column errors keep the `clickstack_describe_source` hint.

Tests (all failed before the change):
- `list_sources` includes the database-qualified table for log and trace sources, and the database for metric sources.
- The `sql` examples use only placeholders, and run once those are filled from a source.
- Real ClickHouse unknown-table messages produce the new hint, both from `errorHint` and end to end through `clickstack_sql`.

Not in this PR:
- Dashboard prompt and schema examples (`prompts/dashboards/content.ts`, `tools/dashboards/schemas.ts`) still hard-code `otel_traces` and `TimestampTime`. Raw SQL tiles can use `$__sourceTable` there, so that's a separate change.
- Adding `sourceId` and `$__sourceTable` to `clickstack_sql` itself. I'll propose that separately.

### How to test on Vercel preview

N/A — non-UI change.

### References

- Linear Issue: HDX-5683
- Related PRs: #3353

🤖 Generated with [Claude Code](https://claude.com/claude-code)
kodiakhq Bot pushed a commit that referenced this pull request Oct 13, 2026
…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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants