Skip to content

feat: add data source and connection variable types to dashboards - #3651

Merged
pulpdrew merged 19 commits into
mainfrom
drew/source-vars-1
Nov 18, 2026
Merged

pulpdrew merged 19 commits into
mainfrom
drew/source-vars-1

Conversation

@pulpdrew

@pulpdrew pulpdrew commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds data source and data connection type variables.

Source and connection variables allow for dashboards variable inputs that define a source or connection queried by a tile or other filters. Selected values are stored in source or connection id slots in the saved chart config, in the $varName format, then converted to source or connection IDs at runtime when there is a selection.

Variables are substituted prior to rendering the dashboard, at the top level, so that components and configs down the stack can just use source and connection IDs like they have been.

Direct $source references are not yet allowed in SQL tiles - the source is selected at the chart level and $__sourceTable can be used to reference it. Connection variables are mostly only useful for (a) raw sql tiles and (b) source variables that can be scoped to a single connection, dynamically.

How to test on Vercel preview

The E2E feature can be tested on PR 5: #3656

References

@vercel

vercel Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Nov 18, 2026 1:08am UTC
hyperdx-storybook Ready Ready Preview Nov 18, 2026 1:08am UTC

Request Review

@changeset-bot

changeset-bot Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 825d764

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

This PR includes changesets to release 4 packages
Name Type
@hyperdx/common-utils Minor
@hyperdx/api Minor
@hyperdx/app Minor
@hyperdx/otel-collector Minor

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

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Duplicate code analysis

3 new clones introduced by this PR.

  • packages/api/src/mcp/tools/dashboards/queryTile.ts:69-87 ↔ packages/api/src/mcp/tools/dashboards/queryTiles.ts:175-193 — 19 lines
  • packages/api/src/utils/zod.ts:572-582 ↔ packages/api/src/utils/zod.ts:583-603 — 11 lines
  • packages/app/src/components/SourceMultiSelect.tsx:52-71 ↔ packages/app/src/components/SourceSelect.tsx:202-221 — 20 lines

If one of these duplicates a helper that already exists, import it instead
of redefining it. If the duplication is deliberate, ignore this comment —
the check is advisory and never fails the build.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 106 in total (1.14%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 472 passed • 1 skipped • 996s

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

Tests ran across 4 shards in parallel.

View full report →

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

🔴 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:

  • Critical-path files (2) — tenancy, public API, or shipped database config:
    • packages/api/src/routers/external-api/v2/dashboards.ts
    • packages/api/src/routers/external-api/v2/utils/dashboards.ts
  • Cross-layer change: touches frontend (packages/app) + backend (packages/api) + shared utils (packages/common-utils)

Additional context: touches background tasks or the delivery pipeline lightly (11 lines, under the 30-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: 50
  • Production lines changed: 4072 (+ 4008 in test files, excluded from tier calculation)
  • Critical-path lines changed: 308
  • Branch: drew/source-vars-1
  • 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.

Comment thread packages/common-utils/src/core/utils.ts Resolved
Comment thread packages/api/src/utils/externalApi.ts Resolved
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

5 finding(s): 🔴 0 critical · 🟠 1 major · 🔵 4 minor

4 posted as inline comment(s) on the changed lines. 1 listed below.

Findings outside the changed lines

1 minor
  • 🔵 packages/common-utils/src/core/utils.ts:10579 — Template export silently drops a data source variable's connection limit when the connection is missing → getConnectionName(filter.connection) || undefined turns an unknown connection ID into no limit, so the imported variable offers sources from every connection with no mapping row to warn the user. SQL_QUERY filters and tiles keep '', which marks the connection as missing. Fix: keep '' (or the raw value) so import asks for a mapping, or have import flag it, rather than widening the variable.

Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

This is a well-constructed, defensively-written, and unusually well-tested PR. Reference tokens are matched against a strict anchored pattern (^[a-zA-Z][a-zA-Z0-9_]*$), reference variables are excluded from raw-SQL macro substitution, and cross-tenant access through a resolved variable is blocked at both the MCP validation layer and the {_id, team} connection/source fetch layer — security found no exploitable path. The findings below are recommendations and nits, not merge blockers.

🟡 P2 — recommended

  • packages/common-utils/src/dashboardValidation.ts:525 — An update's reference validation adds every stored reference to the skip set, so a PATCH can delete a data source/connection variable while tiles still reference it, persisting dangling $var references that only error at view time (the prior-review thread from @jordan-simonovski remains unaddressed).
    • Fix: Skip only references that were already unresolved in the stored dashboard, so deleting a still-referenced variable raises a validation error instead of saving a broken dashboard.
    • correctness, previous-comments
  • packages/common-utils/src/referenceVariables.ts:198 — getConfigReferenceFields accepts NON_PROMQL_SOURCE_KINDS for every non-promql config regardless of display type, so save-validation admits a data source variable whose kinds are invalid for the tile (e.g. a metric-only variable on a Search tile); web resolution then substitutes it with no kind check and renders empty results silently, while MCP rejects the identical config.
    • Fix: Use the display-type-aware getSavedConfigAllowedSourceKinds in both save-validation and config resolution so an incompatible variable is rejected or flagged rather than resolving to silent empty output.
    • adversarial
  • packages/api/src/utils/zod.ts:60 — The v2 external API already accepts the new DATA_SOURCE/CONNECTION filter types and can now return $name tokens in tile sourceId/connectionId and filter source/connection fields, a live request/response contract widening with no version annotation despite the feature being described as deferred.
    • Fix: Document the new filter types and the possibility of $name tokens in ID-shaped response fields, and version/annotate the v2 contract so SDK consumers regenerate models.
    • api-contract
🔵 P3 nitpicks (7)
  • packages/common-utils/src/referenceVariables.ts:368 — resolveFilterReferences calls getFilterReferenceFields(filter) twice (loop at line 351 and keys at line 368), re-evaluating the switch.
    • Fix: Hoist it into one local and reuse it for both the resolve loop and the keys derivation.
  • packages/common-utils/src/dashboardValidation.ts:450 — The occurrence key omits the referenced variable's current type, so deleting a DATA_SOURCE variable and adding a same-named CONNECTION variable leaves a stored source: $foo reference unvalidated, later substituting a connection id as a source id.
    • Fix: Include the variable's current declared type in the occurrence key so a same-name type swap is treated as an added reference and re-validated.
  • packages/common-utils/src/dashboardValidation.ts:480 — External-API variable-reference error paths surface the internal source/connection field names instead of the external sourceId/connectionId the client sent.
    • Fix: Map internal field paths back to their external names when composing external-API error messages.
  • packages/api/src/mcp/tools/dashboards/queryTile.ts:104 — getReferenceTargets (sources + connections fetch) is awaited for every tile query even when no tile references a variable, adding a new failure surface; in queryTiles.ts:238 the shared fetch is a single point of failure ahead of the otherwise per-tile-resilient loop.
    • Fix: Fetch reference targets only when a stored tile actually references a variable, so plain tiles don't gain this dependency.
    • reliability
  • packages/common-utils/src/referenceVariables.ts:323 — The restoreConfigReferences branch where stored holds a reference for a field absent from the resolved config is untested.
    • Fix: Add a round-trip test asserting the absent field is not re-added.
  • packages/common-utils/src/guards.ts:128 — toBuilderHeatmapMode('histogram') → undefined and its fall-through in getAllowedSourceKinds are unexercised.
    • Fix: Add a getAllowedSourceKinds assertion for heatmapMode: 'histogram'.
  • packages/common-utils/src/__tests__/referenceVariables.test.ts:585 — The incompatible-kind refinement suite asserts only issues.length > 0, which would pass even if the issue fired on the wrong path.
    • Fix: Assert the expected issue path/message per case, as sibling tests already do.

Reviewers (11): correctness, adversarial, api-contract, kieran-typescript, reliability, julik-frontend-races, security, testing, maintainability, project-standards, previous-comments.

Testing gaps:

  • No test for a PATCH that deletes an in-use data source/connection variable while a tile/filter still references it (the delete-dangling-reference scenario).
  • No test for saving a display-type-incompatible data source variable (valid under NON_PROMQL_SOURCE_KINDS, invalid for the tile), where web vs. MCP behavior diverges.
  • No test for the same-name DATA_SOURCE↔CONNECTION type-swap PATCH.
  • No external-API round-trip test asserting DATA_SOURCE/CONNECTION filters and $var ID fields serialize losslessly through the projection.

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

Comment thread packages/api/src/utils/externalApi.ts Resolved
@pulpdrew

Copy link
Copy Markdown
Contributor Author

On the P0 - this is intentional, external API / MCP support is in PR 2 in the stack

]),
);
const connectionVariableNames = new Set(getConnectionVariableNames(filters));
const existingKeys = new Set(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Should a PATCH block deleting a variable that tiles still use?

At the moment a PATCH skips every reference the stored dashboard already had. So you can delete a data source variable while tiles still point at it, and those tiles break.

Could it skip only the references that were already broken before the update? Edits to unrelated filters would still save, but deleting a variable that's in use would return a 400. We should probably return a validation message claiming that it's still in use too.

# Conflicts:
#	packages/app/src/components/SourceSelect.tsx
const [id] = selectionByFilterId.get(filterId)?.included ?? [];
return id == null ? undefined : String(id);
};
const connectionValues = new Map(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 minor — A stale connection variable selection is still used, while a stale source variable selection is dropped

Source variable selections are dropped when the variable no longer offers them, but connection selections are not checked. If the URL or saved value holds a deleted or unknown connection ID, ConnectionDashboardFilter shows an empty picker with the required caution. Meanwhile referenceVariableValues still resolves $conn to that ID, unsatisfiedRequiredFilters doesn't block, and raw SQL tiles query a connection that doesn't exist. Pass the team's connections in as well, and call selectionByFilterId.delete for connection variables whose ID isn't among them, the same way the source loop does.

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

{
key: 'source',
target: 'source',
acceptedKinds: isPromql ? [SourceKind.Promql] : NON_PROMQL_SOURCE_KINDS,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 minor — Server-side reference validation accepts every non-PromQL kind for builder tiles, regardless of display type

getConfigReferenceFields gives every non-PromQL tile NON_PROMQL_SOURCE_KINDS. So the API and provisioning accept a search or event_patterns tile on a metric-only variable, or a heatmap on a log-only variable. Those tiles can never run: at runtime getSavedConfigAllowedSourceKinds (guards.ts) rejects every selection, and the editor picker already uses the precise kinds. Use getSavedConfigAllowedSourceKinds(config) for the tile source field so the API matches the runtime and the UI.

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

const keys = getFilterReferenceFields(filter).map(({ key }) => key);
return {
filter: resolved,
unresolvedVariables: getReferencedVariables(filter, keys).filter(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 minor — An unselected variable in only appliesToSourceIds stops the filter's own dropdown from loading

unresolvedVariables counts references in every field, appliesToSourceIds included. Then DashboardFilters drops any filter listed in unresolvedReferenceVariablesByFilterId from queryableFilters. A QUERY_EXPRESSION filter with a fixed source and appliesToSourceIds: ['$logs'] therefore loads no values and shows as pending until $logs is picked, even though it has a source to query. Only count references in the fields the values query reads (source/sources/connection) as unresolved for queryableFilters.

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

if (!savedFilterValues?.length) return [];
const declaredNames = new Set(
getDashboardVariableDeclarations(filters).map(
const declaredNames = new Set([

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 minor — Reference variable names are collected by hand instead of with the existing helper

pairWithVariableNames(filters.filter(f => isReferenceVariableFilterType(f.type))) does the same thing as getReferenceVariableFilters (common-utils/src/referenceVariables.ts), which already accepts external filters. The sibling variables.ts wraps that helper as getReferenceVariableNames too. Use getReferenceVariableFilters(filters).map(({ name }) => name) here, or share the variables.ts helper.

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 fields of a chart config that can hold a reference. */
export function getConfigReferenceFields(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟠 major — Save-time check accepts source variables a tile's chart type can never use

getConfigReferenceFields gives every non-PromQL tile NON_PROMQL_SOURCE_KINDS, so validateDashboardVariableReferences accepts e.g. a Search/Event patterns tile on a [metric]-only variable, or a heatmap on kinds getHeatmapSourceKinds excludes. Every selection then shows the 'can't be used with this chart type' placeholder in DBDashboardPage (and MCP getResolvedSourceError rejects it). The editor picker already refuses these, because useWithSourceVariableItems filters by getAllowedSourceKinds. Fix: have getConfigReferenceFields take its tile acceptedKinds from getSavedConfigAllowedSourceKinds(config) (guards.ts), which already exists in common-utils.

Nothing blocks merge automatically, but a maintainer will expect this fixed if it is a real defect in code this PR changes. If it is about surrounding code, reply and say so instead of patching. Do not widen the PR. How to respond

@@ -101,7 +107,10 @@ async function validateFilterConnections(
filters
.filter(isSqlQueryFilter)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 minor — Internal API never checks a DATA_SOURCE filter's connection ID belongs to the team

validateFilterConnections only collects isSqlQueryFilter connections, so the internal POST/PATCH stores any string as a DATA_SOURCE connection, including an unknown ID or another team's ID. The external API rejects these through getMissingConnections ('connectionId' in filter). Fix: also collect non-reference connection values from isDataSourceFilter filters, skipping unchanged ones the same way.

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

.filter(name => !byName.has(name));
.filter(name => !byName.has(name) && !referenceVariableNames.has(name));
if (unknownVariableValues.length > 0) {
const available =

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 minor — MCP unknown-variable error leaves out the data source and connection variables it accepts

available is built from variables, which comes from getDashboardVariableDeclarations and now excludes reference variables. If an agent mistypes $logs, the error lists only the SQL variables, so it never learns the valid source or connection variable names. Separately, the single-select check skips reference variables, so passing several values for one is accepted silently unless the queried tile reads it. Fix: include referenceVariableNames in the listed names, and apply the values.length > 1 check to reference variables too.

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

details: (
<Stack gap={0}>
{referenceIssues.map(issue => (
<Text key={issue} c="red">

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 minor — New import error list uses raw c="red" instead of the semantic Text variant

The repository conventions ('Semantic component variants') say to use <Text variant="danger"> for status/validation text rather than raw palette colors like c="red". Fix: render each reference issue with <Text variant="danger">.

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

@pulpdrew
pulpdrew merged commit a7744e8 into main Nov 18, 2026
30 checks passed

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 825d7642 Deployed Nov 18, 2026 by vercel[bot]
Preview – hyperdx-storybook — 825d7642 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review/tier-4 Critical — deep review + domain expert sign-off

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants