Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/source-vars-5.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
'@hyperdx/app': minor
'@hyperdx/api': minor
'@hyperdx/common-utils': minor
---

feat: add connection variables for raw SQL tiles, SQL query filters, and
connection-scoped data source variables
4 changes: 2 additions & 2 deletions packages/api/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -4151,7 +4151,7 @@
},
"ConnectionFilterInput": {
"type": "object",
"description": "A variable whose single, required value is a connection. Raw SQL tiles\nreference it as `$variableName` in their connectionId, and data source\nvariables in theirs. Tiles that use it do not load until a connection is\nselected, and cannot have alerts.\n",
"description": "A variable whose single, required value is a connection. Raw SQL tiles\nreference it as `$variableName` in their connectionId, and data source\nvariables and SQL query filters in theirs. Tiles that use it do not load\nuntil a connection is selected, and cannot have alerts.\n",
"required": [
"type",
"name"
Expand Down Expand Up @@ -4548,7 +4548,7 @@
},
"connectionId": {
"type": "string",
"description": "ID of the ClickHouse connection the query runs on.",
"description": "ClickHouse connection the query runs on: a connection ID, or\n`$name` of a CONNECTION filter on the dashboard.\n",
"example": "65f5e4a3b9e77c001a567890"
},
"sqlTemplate": {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4189,6 +4189,26 @@ describe('MCP Dashboard Tools - clickstack_save_dashboard', () => {
]);
});

it('saves a SQL query filter that runs on a connection variable', async () => {
const sqlFilter = {
type: 'SQL_QUERY',
name: 'Environment',
variableName: 'env',
connectionId: '$conn',
sqlTemplate: 'SELECT DISTINCT env FROM envs',
};
const result = await callTool(ctx.client!, 'clickstack_save_dashboard', {
name: 'Variable dashboard',
tiles: [],
filters: [filters[0], sqlFilter],
});

expect(result.isError).toBeFalsy();
expect(JSON.parse(getFirstText(result)).filters[1]).toMatchObject(
sqlFilter,
);
});

it('rejects a tile referencing an undeclared variable', async () => {
const result = await callTool(ctx.client!, 'clickstack_save_dashboard', {
name: 'Variable dashboard',
Expand Down
2 changes: 1 addition & 1 deletion packages/api/src/mcp/prompts/dashboards/content.ts
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ Apply these before calling clickstack_save_dashboard. Each rule is enforced by t

9h. USE AN ADHOC FILTER TO LET THE USER BUILD FREE-FORM CONDITIONS. filters: [{ type: "ADHOC", name, sourceType: "sql", sources: ["<log, trace, or session source id>"], variableName? }] adds an input where the user picks any column or map key, an operator, and a value; clicking a value in a tile adds a condition too. Every condition is ANDed onto the tiles of its sources (or of appliesToSourceIds) with no per-tile wiring. It is never a variable: its variableName only names the entry its conditions are saved under. Seed conditions with savedFilterValues: [{ type: "adhoc", name: "<variableName>", conditions: [{ key: "ServiceName", operator: "IN", value: "api" }] }]; IN conditions on the same key are ORed. Declare at most one ad hoc filter per source, since a click updates every ad hoc filter on the clicked tile's source.

9i. TO LET VIEWERS SWITCH THE SOURCE OR CONNECTION, USE A DATA_SOURCE OR CONNECTION FILTER. filters: [{ type: "DATA_SOURCE", name: "Logs source", variableName: "logs", allowedSourceKinds: ["log"] }] adds a required source picker; tiles then set sourceId: "$logs" (filters may use it in sourceId or appliesToSourceIds). A CONNECTION filter does the same for raw SQL tiles' connectionId, and a DATA_SOURCE filter's optional connectionId limits its sources to one connection. Keep allowedSourceKinds to kinds charts treat alike (log + trace, or one kind). Tiles that use either cannot have alerts, and clickstack_query_tile needs a selection for the variable (variableValues or the dashboard's saved value).
9i. TO LET VIEWERS SWITCH THE SOURCE OR CONNECTION, USE A DATA_SOURCE OR CONNECTION FILTER. filters: [{ type: "DATA_SOURCE", name: "Logs source", variableName: "logs", allowedSourceKinds: ["log"] }] adds a required source picker; tiles then set sourceId: "$logs" (filters may use it in sourceId or appliesToSourceIds). A CONNECTION filter does the same for raw SQL tiles' and SQL_QUERY filters' connectionId, and a DATA_SOURCE filter's optional connectionId limits its sources to one connection. Keep allowedSourceKinds to kinds charts treat alike (log + trace, or one kind). Tiles that use either cannot have alerts, and clickstack_query_tile needs a selection for the variable (variableValues or the dashboard's saved value).

10. UPDATE IS REPLACE, NOT MERGE. clickstack_save_dashboard with an id overwrites tiles, containers, and filters in their entirety. Call clickstack_get_dashboard first when you only want to add or rename one entry; do not send a partial set or you will silently drop everything you omitted.

Expand Down
8 changes: 5 additions & 3 deletions packages/api/src/mcp/tools/dashboards/schemas.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1794,8 +1794,9 @@ const mcpSqlQueryFilterSchema = z
.describe(
'Filter type discriminator for a filter whose dropdown values come from a ClickHouse SQL query.',
),
connectionId: objectIdSchema.describe(
'ClickHouse connection the query runs on. Get IDs from clickstack_list_sources.',
connectionId: objectIdOrVariableReferenceSchema.describe(
'ClickHouse connection the query runs on: a connection ID from ' +
'clickstack_list_sources, or `$name` of a CONNECTION filter on this dashboard.',
),
sqlTemplate: SqlQueryDashboardFilterSchema.shape.sqlTemplate.describe(
'ClickHouse SELECT whose FIRST column becomes the dropdown values (cast to ' +
Expand Down Expand Up @@ -1968,7 +1969,8 @@ const mcpConnectionFilterSchema = z
})
.describe(
'A variable whose single, required value is a connection. Raw SQL tiles reference ' +
'it as `$variableName` in connectionId, and DATA_SOURCE filters in connectionId.',
'it as `$variableName` in connectionId, and DATA_SOURCE and SQL_QUERY filters in ' +
'connectionId.',
);

const mcpDashboardFilterSchema = z
Expand Down
36 changes: 36 additions & 0 deletions packages/api/src/routers/api/__tests__/dashboard.int.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2145,6 +2145,42 @@ describe('dashboard router', () => {

expect(updated.body.filters).toEqual([moved]);
});

const connectionFilter = {
id: new Types.ObjectId().toString(),
type: 'CONNECTION' as const,
name: 'Connection',
variableName: 'conn',
minSelections: 1,
maxSelections: 1,
isBroadcastEnabled: false,
isVariableEnabled: true,
};

it('accepts a connection variable as the connection', async () => {
const filter = makeSqlFilter({ connection: '$conn' });

const created = await agent
.post('/dashboards')
.send({ ...MOCK_DASHBOARD, filters: [connectionFilter, filter] })
.expect(200);

expect(created.body.filters).toEqual([connectionFilter, filter]);
});

it('rejects a reference that names no connection variable', async () => {
const response = await agent
.post('/dashboards')
.send({
...MOCK_DASHBOARD,
filters: [makeSqlFilter({ connection: '$conn' })],
})
.expect(400);

expect(response.body.message).toMatch(
/does not name a connection variable/,
);
});
});

describe('ad hoc filters', () => {
Expand Down
8 changes: 6 additions & 2 deletions packages/api/src/routers/api/dashboards.ts
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,8 @@ async function validateFilterSources(
/**
* Rejects SQL_QUERY filters whose connection doesn't belong to the team. As in
* `validateFilterSources`, a connection the stored filter with the same ID
* already used is skipped. Returns an error message, or null.
* already used is skipped, and so is a variable reference. Returns an error
* message, or null.
*/
async function validateFilterConnections(
teamId: ObjectId,
Expand All @@ -106,7 +107,10 @@ async function validateFilterConnections(
filters
.filter(isSqlQueryFilter)
.filter(
filter => existingConnectionById.get(filter.id) !== filter.connection,
filter =>
// Variable references are checked by validateDashboardVariableReferences
parseVariableReference(filter.connection) == null &&
existingConnectionById.get(filter.id) !== filter.connection,
)
.map(filter => filter.connection),
);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6329,6 +6329,35 @@ describe('External API v2 Dashboards - new format', () => {
expect(response.body.message).toContain(connectionId);
});

it('accepts a connection variable as the connection', async () => {
const response = await sendFilters([
{
id: new ObjectId().toString(),
type: 'CONNECTION',
name: 'Connection',
variableName: 'conn',
},
sqlFilterInput({ connectionId: '$conn' }),
]);

expect(response.status).toBe(200);
expect(response.body.data.filters[1]).toMatchObject({
type: 'SQL_QUERY',
connectionId: '$conn',
});
});

it('rejects a reference that names no connection variable', async () => {
const response = await sendFilters([
sqlFilterInput({ connectionId: '$conn' }),
]);

expect(response.status).toBe(400);
expect(response.body.message).toMatch(
/does not name a connection variable/,
);
});

it.each([
['broadcast enabled', { isBroadcastEnabled: true }],
['not variable-enabled', { isVariableEnabled: false }],
Expand Down
8 changes: 5 additions & 3 deletions packages/api/src/routers/external-api/v2/dashboards.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2518,8 +2518,8 @@ const EXTERNAL_DASHBOARD_PROJECTION = {
* description: |
* A variable whose single, required value is a connection. Raw SQL tiles
* reference it as `$variableName` in their connectionId, and data source
* variables in theirs. Tiles that use it do not load until a connection is
* selected, and cannot have alerts.
* variables and SQL query filters in theirs. Tiles that use it do not load
* until a connection is selected, and cannot have alerts.
* required:
* - type
* - name
Expand Down Expand Up @@ -2905,7 +2905,9 @@ const EXTERNAL_DASHBOARD_PROJECTION = {
* example: "Environment"
* connectionId:
* type: string
* description: ID of the ClickHouse connection the query runs on.
* description: |
* ClickHouse connection the query runs on: a connection ID, or
* `$name` of a CONNECTION filter on the dashboard.
* example: "65f5e4a3b9e77c001a567890"
* sqlTemplate:
* type: string
Expand Down
2 changes: 1 addition & 1 deletion packages/api/src/utils/zod.ts
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,7 @@ const externalPromqlLabelFilterShape = PromqlLabelDashboardFilterSchema.omit({
const externalSqlQueryFilterShape = SqlQueryDashboardFilterSchema.omit({
connection: true,
}).extend({
connectionId: objectIdSchema,
connectionId: objectIdOrVariableReferenceSchema,
isBroadcastEnabled: z.literal(false).default(false),
isVariableEnabled: z.literal(true).default(true),
});
Expand Down
Loading
Loading