Skip to content

Commit acfcd09

Browse files
committed
feat: Support single-select dashboard filters
1 parent bd0da16 commit acfcd09

27 files changed

Lines changed: 578 additions & 38 deletions
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@hyperdx/common-utils': patch
3+
'@hyperdx/api': patch
4+
'@hyperdx/app': patch
5+
---
6+
7+
feat: Allow configuring dashboard filters as single-select

‎packages/api/openapi.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3287,6 +3287,14 @@
32873287
"default": false,
32883288
"description": "Widens a required filter's block to every tile on the dashboard. False\n(the default) blocks only the tiles that read the filter: those\nreferencing its variableName, and those its broadcast applies to.\nIgnored unless minSelections is 1.\n",
32893289
"example": true
3290+
},
3291+
"maxSelections": {
3292+
"type": "integer",
3293+
"enum": [
3294+
1
3295+
],
3296+
"description": "Maximum number of values that can be selected at once. Set to 1 to make\nthe filter single-select. Omit the field for the default multi-select\nbehavior.\n",
3297+
"example": 1
32903298
}
32913299
}
32923300
},
@@ -3369,6 +3377,14 @@
33693377
"default": false,
33703378
"description": "Widens a required filter's block to every tile on the dashboard. False\n(the default) blocks only the tiles that read the filter: those\nreferencing its variableName, and those its broadcast applies to.\nIgnored unless minSelections is 1.\n",
33713379
"example": true
3380+
},
3381+
"maxSelections": {
3382+
"type": "integer",
3383+
"enum": [
3384+
1
3385+
],
3386+
"description": "Maximum number of values that can be selected at once. Set to 1 to make\nthe filter single-select. Omit the field for the default multi-select\nbehavior.\n",
3387+
"example": 1
33723388
}
33733389
}
33743390
},
@@ -3454,6 +3470,14 @@
34543470
"default": false,
34553471
"description": "Widens a required filter's block to every tile on the dashboard. False\n(the default) blocks only the tiles that read the filter: those\nreferencing its variableName, and those its broadcast applies to.\nIgnored unless minSelections is 1.\n",
34563472
"example": true
3473+
},
3474+
"maxSelections": {
3475+
"type": "integer",
3476+
"enum": [
3477+
1
3478+
],
3479+
"description": "Maximum number of values that can be selected at once. Set to 1 to make\nthe filter single-select. Omit the field for the default multi-select\nbehavior.\n",
3480+
"example": 1
34573481
}
34583482
}
34593483
},

‎packages/api/src/mcp/__tests__/dashboards/saveDashboard.int.test.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2661,6 +2661,47 @@ describe('MCP Dashboard Tools - clickstack_save_dashboard', () => {
26612661
}
26622662
});
26632663

2664+
it('round-trips a single-select filter through create and get', async () => {
2665+
const sourceId = ctx.traceSource._id.toString();
2666+
const createResult = await callTool(
2667+
ctx.client!,
2668+
'clickstack_save_dashboard',
2669+
{
2670+
name: 'Single-select filter',
2671+
tiles: [traceTile(sourceId)],
2672+
filters: [queryFilter({ maxSelections: 1 })],
2673+
},
2674+
);
2675+
expect(createResult.isError).toBeFalsy();
2676+
const created = JSON.parse(getFirstText(createResult));
2677+
expect(created.filters[0].maxSelections).toBe(1);
2678+
2679+
const getResult = await callTool(
2680+
ctx.client!,
2681+
'clickstack_get_dashboard',
2682+
{ id: created.id },
2683+
);
2684+
expect(
2685+
JSON.parse(getFirstText(getResult)).filters[0].maxSelections,
2686+
).toBe(1);
2687+
});
2688+
2689+
it.each([0, 2])('rejects maxSelections %s', async value => {
2690+
const sourceId = ctx.traceSource._id.toString();
2691+
const result = await callTool(
2692+
ctx.client!,
2693+
'clickstack_save_dashboard',
2694+
{
2695+
name: 'Bad maxSelections',
2696+
tiles: [traceTile(sourceId)],
2697+
filters: [queryFilter({ maxSelections: value })],
2698+
},
2699+
);
2700+
2701+
expect(result.isError).toBe(true);
2702+
expect(getFirstText(result)).toContain('maxSelections');
2703+
});
2704+
26642705
it.each([2, -1, 1.5])('rejects minSelections %s', async value => {
26652706
const sourceId = ctx.traceSource._id.toString();
26662707
const result = await callTool(

‎packages/api/src/mcp/__tests__/dashboards/variables.test.ts‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,35 @@ describe('resolveDashboardVariables', () => {
128128
expect(resolved.error).toContain('Available variables: (none)');
129129
});
130130

131+
it('rejects several values for a single-select variable', () => {
132+
const resolved = resolveDashboardVariables(
133+
[staticFilter({ maxSelections: 1 })],
134+
[{ name: 'env', values: ['prod', 'staging'] }],
135+
);
136+
137+
if (!('error' in resolved)) throw new Error('expected an error');
138+
expect(resolved.error).toContain('"env"');
139+
expect(resolved.error).toContain('single-select');
140+
});
141+
142+
it('applies one value to a single-select variable', () => {
143+
expect(
144+
resolveDashboardVariables(
145+
[staticFilter({ maxSelections: 1 })],
146+
[{ name: 'env', values: ['prod'] }],
147+
),
148+
).toEqual({
149+
variables: [
150+
{
151+
name: 'env',
152+
expression: undefined,
153+
values: ['prod'],
154+
maxSelections: 1,
155+
},
156+
],
157+
});
158+
});
159+
131160
it('declares a variable for a static filter', () => {
132161
expect(resolveDashboardVariables([staticFilter()], undefined)).toEqual({
133162
variables: [{ name: 'env', expression: undefined, values: [] }],

‎packages/api/src/mcp/prompts/dashboards/content.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,8 @@ Apply these before calling clickstack_save_dashboard. Each rule is enforced by t
116116
117117
9e. MAKE A FILTER REQUIRED ONLY WHEN AN UNSCOPED VIEW IS MEANINGLESS. minSelections: 1 blocks the tiles that read the filter - the ones referencing its $variableName, and the ones its broadcast applies to - until the user picks a value. isGlobalRequirement: true widens that to every tile on the dashboard. Consider pairing either form with savedFilterValues so the dashboard opens on a sensible default rather than blocked.
118118
119+
9f. MAKE A FILTER SINGLE-SELECT WHEN A TILE ONLY MAKES SENSE FOR ONE VALUE. maxSelections: 1 limits the dropdown to one value at a time, for example a host picker feeding a per-host detail view.
120+
119121
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.
120122
121123
11. GROUP RELATED TILES INTO CONTAINERS. REQUIRED at five or more tiles, no exceptions. An ungrouped wall of nine or ten tiles is a readability failure even when each tile is correct in isolation. Containers are the right way to introduce structure; markdown tiles for section labels are not.

‎packages/api/src/mcp/tools/dashboards/schemas.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1247,6 +1247,16 @@ const mcpDashboardFilterBaseShape = {
12471247
'Widens a REQUIRED filter (minSelections: 1) to block EVERY tile on the dashboard, ' +
12481248
'not just the ones that read it. Ignored unless minSelections is 1.',
12491249
),
1250+
maxSelections: z
1251+
.number()
1252+
.int()
1253+
.min(1)
1254+
.max(1)
1255+
.optional()
1256+
.describe(
1257+
'Set to 1 to make this filter SINGLE-SELECT: the user can pick at most one ' +
1258+
'value. Omit for the normal multi-select behavior.',
1259+
),
12501260
};
12511261

12521262
const mcpQueryExpressionFilterSchema = z

‎packages/api/src/mcp/tools/dashboards/variables.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import {
22
getDashboardVariableDeclarations,
33
getDashboardVariableFilters,
44
getFilterVariableName,
5+
isFilterSingleSelect,
56
isFilterVariableEnabled,
67
isStaticListFilter,
78
} from '@hyperdx/common-utils/dist/filters';
@@ -101,6 +102,23 @@ export function resolveDashboardVariables(
101102
return { error: optionErrors.join('\n') };
102103
}
103104

105+
// The dashboard can never hold several values for a single-select variable.
106+
const singleSelectNames = new Set(
107+
variables.filter(isFilterSingleSelect).map(variable => variable.name),
108+
);
109+
const singleSelectErrors = variableValues
110+
.filter(
111+
({ name, values }) => values.length > 1 && singleSelectNames.has(name),
112+
)
113+
.map(
114+
({ name }) =>
115+
`Variable "${name}" belongs to a single-select filter (maxSelections: 1) ` +
116+
'and accepts at most one value.',
117+
);
118+
if (singleSelectErrors.length > 0) {
119+
return { error: singleSelectErrors.join('\n') };
120+
}
121+
104122
// Override the default empty selection with the given variableValues
105123
for (const { name, values } of variableValues) {
106124
byName.get(name)!.values = values;

‎packages/api/src/routers/api/__tests__/dashboard.int.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1210,6 +1210,27 @@ describe('dashboard router', () => {
12101210
.expect(400);
12111211
});
12121212

1213+
it('persists maxSelections on create', async () => {
1214+
const filter = makeFilter({ maxSelections: 1 });
1215+
1216+
const created = await agent
1217+
.post('/dashboards')
1218+
.send({ ...MOCK_DASHBOARD, filters: [filter] })
1219+
.expect(200);
1220+
1221+
expect(created.body.filters).toEqual([filter]);
1222+
});
1223+
1224+
it.each([0, 2, 1.5, '1'])('rejects maxSelections %s', async value => {
1225+
await agent
1226+
.post('/dashboards')
1227+
.send({
1228+
...MOCK_DASHBOARD,
1229+
filters: [makeFilter({ maxSelections: value })],
1230+
})
1231+
.expect(400);
1232+
});
1233+
12131234
it('persists a dashboard-wide requirement', async () => {
12141235
const filter = makeFilter({
12151236
minSelections: 1,

‎packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5732,6 +5732,37 @@ describe('External API v2 Dashboards - new format', () => {
57325732
});
57335733
});
57345734

5735+
describe('single-select filters', () => {
5736+
const variants = [
5737+
['QUERY_EXPRESSION', filterInput],
5738+
['STATIC_LIST', staticFilterInput],
5739+
['PROMETHEUS_LABEL', promqlFilterInput],
5740+
] as const;
5741+
5742+
it.each(variants)(
5743+
'accepts a single-select %s filter',
5744+
async (_type, makeFilter) => {
5745+
const response = await sendFilters([
5746+
makeFilter({ maxSelections: 1 }),
5747+
]);
5748+
expect(response.status).toBe(200);
5749+
expect(response.body.data.filters[0].maxSelections).toBe(1);
5750+
},
5751+
);
5752+
5753+
it('omits the key from responses for a multi-select filter', async () => {
5754+
const response = await sendFilters([filterInput()]);
5755+
expect(response.status).toBe(200);
5756+
expect(response.body.data.filters[0]).not.toHaveProperty(
5757+
'maxSelections',
5758+
);
5759+
});
5760+
5761+
it.each([0, 2, 1.5, '1'])('rejects maxSelections %s', async value => {
5762+
await expectFilters([filterInput({ maxSelections: value })], 400);
5763+
});
5764+
});
5765+
57355766
describe('static-list filters', () => {
57365767
it('accepts a static-list filter and round-trips it through GET', async () => {
57375768
const response = await sendFilters([staticFilterInput()]);

‎packages/api/src/routers/external-api/v2/dashboards.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1891,6 +1891,14 @@ const EXTERNAL_DASHBOARD_PROJECTION = {
18911891
* referencing its variableName, and those its broadcast applies to.
18921892
* Ignored unless minSelections is 1.
18931893
* example: true
1894+
* maxSelections:
1895+
* type: integer
1896+
* enum: [1]
1897+
* description: |
1898+
* Maximum number of values that can be selected at once. Set to 1 to make
1899+
* the filter single-select. Omit the field for the default multi-select
1900+
* behavior.
1901+
* example: 1
18941902
*
18951903
* StaticListFilterInput:
18961904
* type: object
@@ -1977,6 +1985,14 @@ const EXTERNAL_DASHBOARD_PROJECTION = {
19771985
* referencing its variableName, and those its broadcast applies to.
19781986
* Ignored unless minSelections is 1.
19791987
* example: true
1988+
* maxSelections:
1989+
* type: integer
1990+
* enum: [1]
1991+
* description: |
1992+
* Maximum number of values that can be selected at once. Set to 1 to make
1993+
* the filter single-select. Omit the field for the default multi-select
1994+
* behavior.
1995+
* example: 1
19801996
*
19811997
* PrometheusLabelFilterInput:
19821998
* type: object
@@ -2064,6 +2080,14 @@ const EXTERNAL_DASHBOARD_PROJECTION = {
20642080
* referencing its variableName, and those its broadcast applies to.
20652081
* Ignored unless minSelections is 1.
20662082
* example: true
2083+
* maxSelections:
2084+
* type: integer
2085+
* enum: [1]
2086+
* description: |
2087+
* Maximum number of values that can be selected at once. Set to 1 to make
2088+
* the filter single-select. Omit the field for the default multi-select
2089+
* behavior.
2090+
* example: 1
20672091
*
20682092
* Filter:
20692093
* allOf:

0 commit comments

Comments
 (0)