feat: Support dashboard variables in chart builder tiles

[pulpdrew]

Summary

This PR extends dashboard variable support to Builder charts.

• Variables are substituted in most user-editable chart-builder fields (where, aggCondition, group by, having, order by, etc). This works for both SQL and Lucene. Lucene does not get any macros, and SQL only gets variable-related macros (not the full suite available in Raw SQL charts).
• Variables and (when available) macros are suggested in autocomplete in both SQL and Lucene inputs, when available.
• Warnings are shown on the right side of the input when a variable is referenced but not found (as well as some other validations).

Note that creation of variables is gated behind NEXT_PUBLIC_ENABLE_DASHBOARD_VARIABLES (enabled by default in development locally.

Future work

Future work includes, but is not limited to:

1. Updating the alerts runner to supply a variables context based on the variables configured on the dashboard
2. Supporting dependent variables
3. MCP and external API support
4. Documentation

Screenshots or video

Screen.Recording.2026-08-13.at.12.21.41.PM.mov

How to test locally

1. Clone and restart to ensure NEXT_PUBLIC_ENABLE_DASHBOARD_VARIABLES=true
2. Create a dashboard
3. Add a filter and enable variable mode
4. Add a builder tile and test the replacement, autocomplete, and validation functionality. Try SQL and lucene, bare references and macros, in various inputs (not just WHERE!)

References

• Linear Issue: Closes HDX-5056 HDX-5058
• Related PRs:

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview	Aug 14, 2026 12:22pm
hyperdx-storybook	Ready	Preview	Aug 14, 2026 12:22pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 2e1a153

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

This PR includes changesets to release 4 packages

Name	Type
@hyperdx/app	Patch
@hyperdx/common-utils	Patch
@hyperdx/api	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

[github-actions]

E2E Test Results

✅ All tests passed • 296 passed • 1 skipped • 1108s

Status	Count
✅ Passed	296
❌ Failed	0
⚠️ Flaky	0
⏭️ Skipped	1

Tests ran across 4 shards in parallel.

View full report →

[greptile-apps]

Greptile Summary

This PR extends dashboard-variable support from raw SQL tiles to chart-builder configurations.

• Passes referenced dashboard variables into builder tile query configurations.
• Substitutes variables across builder expressions using SQL- or Lucene-aware formatting.
• Adds variable completion and validation to chart-builder inputs.
• Adds unit and end-to-end coverage for variable rendering and editor behavior.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains in the eligible follow-up-review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/app/src/DBDashboardPage.tsx	Supplies referenced dashboard variables to builder tile query configurations and to the chart editor’s completion context.
packages/common-utils/src/variables.ts	Adds traversal, substitution, reference detection, formatting, and validation support for builder-chart variable templates.
packages/common-utils/src/core/renderChartConfig.ts	Applies dashboard-variable substitution before rendering builder chart configurations into queries.
packages/app/src/components/SQLEditor/variableCompletions.tsx	Centralizes SQL and Lucene variable completion generation and provides dashboard variables through React context.
packages/app/src/components/SQLEditor/variableValidation.tsx	Adds editor-side validation and warning presentation for variable references.
packages/app/src/components/DBEditTimeChartForm/EditTimeChartForm.tsx	Integrates variable-aware preview rendering and validation into the builder chart form.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Filters[Dashboard filters] --> Variables[Chart variables]
  Variables --> Referenced[Referenced-variable filtering]
  Referenced --> TileConfig[Builder tile configuration]
  TileConfig --> Substitute[Language-aware substitution]
  Substitute --> Render[Chart SQL rendering]
  Render --> ClickHouse[(ClickHouse)]
  Variables --> Provider[Editor variable provider]
  Provider --> Inputs[Builder SQL and Lucene inputs]
  Inputs --> Completion[Completion and validation]

Loading

_{Reviews (6): Last reviewed commit: "fix: Fix sample matching events variable..." | Re-trigger Greptile}

[pulpdrew]

This is a no-op (1=1), whereas * is a notEmpty(...)

[pulpdrew]

All this stuff has been moved to packages/app/src/components/SQLEditor/variableCompletions.tsx

[pulpdrew]

Moved to packages/common-utils/src/variables.ts

[github-actions]

🔴 Tier 4 — Critical

Touches authentication, tenancy data models, the public API or shipped database config — or substantially changes the query rendering engine, background tasks, the OTel pipeline, image build, or release CI.

Why this tier:

• Large diff: 1240 production lines changed (threshold: 1000)
• Cross-layer change: touches frontend (packages/app) + shared utils (packages/common-utils)

Additional context: touches the query rendering engine lightly (19 lines, under the 150-line bar for Tier 4)

Review process: Deep review from a domain expert. Synchronous walkthrough may be required.
SLA: Schedule synchronous review within 2 business days.

Stats

• Production files changed: 22
• Production lines changed: 1240 (+ 1619 in test files, excluded from tier calculation)
• Branch: drew/builder-variables
• Author: pulpdrew

To override this classification, remove the review/tier-4 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[github-actions]

Deep Review

✅ No critical issues found. The core template engine (scanTemplateTokens, formatVariableValues, macro expansion) escapes values per output format (escapeSqlString, escapeRegexValue, escapeLuceneValue), is quote- and comment-aware in the top-level scan, and prevents value re-expansion by inserting escaped values rather than re-scanning them. substituteChartConfigVariables drops variables from its result to prevent double-substitution. No P0/P1 ship-blocker is introduced by this diff.

🟡 P2 — recommended

• packages/app/src/components/DBEditTimeChartForm/utils.ts:160 — expandVariablesOrLeaveRaw catches every expansion error and silently returns the unexpanded config, so a malformed reference or a macro naming an undeclared variable makes the sample-events panel build filters from literal $var text with no log or user signal.
  • Fix: Log the swallowed error before falling back so the silent degradation is diagnosable.

🔵 P3 nitpicks (3)

🔵 P3 nitpicks (3)

• packages/common-utils/src/variables.ts:133 — findBalancedParens is quote-aware but not comment-aware, so a macro argument containing a comment with an unbalanced paren such as $__filter(col /* ) */, name) terminates the argument list early and mis-parses.
  • Fix: Skip comment spans inside findBalancedParens the way the top-level scanner already does via findCommentEnd.
• packages/common-utils/src/types.ts:1414 — adding variables to the persisted BuilderChartConfigSchema allows a runtime snapshot of variable definitions to be serialized into a saved builder tile, which would later be consumed and could drift from the dashboard's live variables.
  • Fix: Confirm the save path strips variables before persistence (or omit it from the persisted schema and attach it only to the runtime config).
• packages/common-utils/src/variables.ts:55 — the csv format renders values unescaped (values.join(',')); builder inputs now expose this format to more surfaces, so a value spliced outside a quoted/controlled context is unescaped by design.
  • Fix: Keep the completion help text's "Not SQL-escaped" warning prominent and note the safe usage in variable-format docs.

---

Reviewers (12): correctness, security, adversarial, testing, maintainability, kieran-typescript, api-contract, performance, julik-frontend-races, project-standards, agent-native, learnings-researcher.

Testing gaps: Confirm the expandVariablesOrLeaveRaw catch/fallback branch in DBEditTimeChartForm/utils.ts has a unit test; confirm the Lucene macro-error path and all four formatVariableValues escaping formats (sqlstring/regex/csv/lucene) are covered in variables.test.ts.