From c38ffbf01d0879ce5963a7cdaa2a2c57b9efdc1e Mon Sep 17 00:00:00 2001 From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com> Date: Tue, 5 May 2026 07:09:39 +0000 Subject: [PATCH 1/9] feat(schema): add Timeline display type and TimelineSeriesSchema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds `DisplayType.Timeline = 'timeline'` to the shared enum and the accompanying `TimelineSeriesSchema` + `TimelineSeries` type to `SharedChartSettingsSchema`. Updates all exhaustive `Record` maps: - `rawSqlParams.ts`: `QUERY_PARAMS_BY_DISPLAY_TYPE` and `QUERY_PARAM_EXAMPLES` get Timeline SQL-parameter entries and a worked example query. - `ChartEditor/constants.tsx`: `SQL_PLACEHOLDERS` gets a Timeline default query; `DISPLAY_TYPE_INSTRUCTIONS` gets the column-shape documentation (Partial Record, but added here for consistency). - `external-api/v2/utils/dashboards.ts`: two switch fall-throughs route Timeline the same way as Heatmap (unsupported for external API export, logs an error). This is PR A in a three-part chain (schema → renderer → builder). Nothing in the app renders or edits Timeline tiles yet. Co-Authored-By: Claude Opus --- .../external-api/v2/utils/dashboards.ts | 2 + .../src/components/ChartEditor/constants.tsx | 61 +++++++++++++++++++ packages/common-utils/src/rawSqlParams.ts | 16 +++++ packages/common-utils/src/types.ts | 43 +++++++++++++ 4 files changed, 122 insertions(+) diff --git a/packages/api/src/routers/external-api/v2/utils/dashboards.ts b/packages/api/src/routers/external-api/v2/utils/dashboards.ts index 504cf85cbe..e5ea8d2dde 100644 --- a/packages/api/src/routers/external-api/v2/utils/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/utils/dashboards.ts @@ -166,6 +166,7 @@ const convertToExternalTileChartConfig = ( case DisplayType.Search: case DisplayType.Markdown: case DisplayType.Heatmap: + case DisplayType.Timeline: logger.error( { config }, 'Error converting chart config to external chart - unsupported display type for raw SQL config', @@ -268,6 +269,7 @@ const convertToExternalTileChartConfig = ( markdown: stringValueOrDefault(config.markdown, ''), }; case DisplayType.Heatmap: + case DisplayType.Timeline: case undefined: logger.error( { config }, diff --git a/packages/app/src/components/ChartEditor/constants.tsx b/packages/app/src/components/ChartEditor/constants.tsx index 95287b319b..86d213b548 100644 --- a/packages/app/src/components/ChartEditor/constants.tsx +++ b/packages/app/src/components/ChartEditor/constants.tsx @@ -46,6 +46,18 @@ WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) [DisplayType.Search]: '', [DisplayType.Heatmap]: '', [DisplayType.Markdown]: '', + [DisplayType.Timeline]: `SELECT + TimestampTime AS ts, + concat(SeverityText, ': ', Body) AS label, + ServiceName AS \`group\`, + SeverityText AS severity +FROM $__sourceTable +WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) + AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) + AND $__filters + AND SeverityText IN ('ERROR', 'FATAL') +ORDER BY ts ASC +LIMIT 1000`, }; const TIMESERIES_INSTRUCTIONS = ( @@ -141,4 +153,53 @@ export const DISPLAY_TYPE_INSTRUCTIONS: Partial< ), + [DisplayType.Timeline]: ( + <> + + Result columns are rendered as event markers on a time axis: + + + + + ts + + + {' '} + (required) — A DateTime or{' '} + DateTime64 column for the event timestamp. + + + + + label + + + {' '} + (required) — A String column for the marker + label shown in tooltips. + + + + + group + + + {' '} + (optional) — A String column to split events + into separate lanes. + + + + + severity + + + {' '} + (optional) — A String column for severity-based + color mapping. + + + + + ), }; diff --git a/packages/common-utils/src/rawSqlParams.ts b/packages/common-utils/src/rawSqlParams.ts index 1062e2f3f8..ccd137cd97 100644 --- a/packages/common-utils/src/rawSqlParams.ts +++ b/packages/common-utils/src/rawSqlParams.ts @@ -91,6 +91,10 @@ export const QUERY_PARAMS_BY_DISPLAY_TYPE: Record< [DisplayType.Search]: [], [DisplayType.Heatmap]: [], [DisplayType.Markdown]: [], + [DisplayType.Timeline]: [ + QUERY_PARAMS.startDateMilliseconds, + QUERY_PARAMS.endDateMilliseconds, + ], }; const TIME_CHART_EXAMPLE_SQL = `SELECT @@ -116,6 +120,18 @@ export const QUERY_PARAM_EXAMPLES: Record = { [DisplayType.Search]: '', [DisplayType.Heatmap]: '', [DisplayType.Markdown]: '', + [DisplayType.Timeline]: `SELECT + TimestampTime AS ts, + concat(SeverityText, ': ', Body) AS label, + ServiceName AS \`group\`, + SeverityText AS severity +FROM $__sourceTable +WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) + AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) + AND $__filters + AND SeverityText IN ('ERROR', 'FATAL') +ORDER BY ts ASC +LIMIT 1000`, }; export function renderQueryParam(name: keyof typeof QUERY_PARAMS): string { diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index 8f0d2e2956..524aa130d8 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -23,6 +23,7 @@ export enum DisplayType { Search = 'search', Heatmap = 'heatmap', Markdown = 'markdown', + Timeline = 'timeline', } export type KeyValue = { key: Key; value: Value }; @@ -700,6 +701,47 @@ export type OnClick = z.infer; // When making changes here, consider if they need to be made to the external API // schema as well (packages/api/src/utils/zod.ts). + +export const TimelineSeriesSchema = z.object({ + id: z.string(), + label: z.string().min(1), + mode: z.enum(['events', 'value_change']), + source: z.string(), + where: z.string().optional(), + whereLanguage: SearchConditionLanguageSchema, + /** + * Splits the rendered markers into colored lanes by this expression. + * + * - In `events` mode, each distinct value becomes a lane label. + * - In `value_change` mode, this expression is also used as the SQL + * PARTITION BY for the LAG window function — so version history is + * tracked independently per group (e.g. one history per service). + * + * Conceptually: "what do I want one row per?" — typically `ServiceName` + * or another resource attribute that identifies the entity being watched. + */ + groupExpression: z.string().optional(), + // events mode: + labelExpression: z.string().optional(), + /** + * Optional SQL expression that resolves to a severity string per row + * (e.g. `SeverityText` for OTel log sources). When set, individual event + * markers are colored by severity (FATAL/ERROR/WARN/INFO/DEBUG/TRACE) + * rather than by lane. Only applies in `events` mode. + */ + severityExpression: z.string().optional(), + // value_change mode: + /** + * SQL expression that resolves to the value being tracked for changes + * (e.g. `ResourceAttributes['service.version']`). The renderer emits a + * marker each time this expression's value differs from the previous row + * within the same `groupExpression` partition. + */ + trackColumn: z.string().optional(), +}); + +export type TimelineSeries = z.infer; + /** * Schema describing settings which are shared between Raw SQL * chart configs and Structured ChartBuilder chart configs @@ -712,6 +754,7 @@ const SharedChartSettingsSchema = z.object({ fillNulls: z.union([z.number(), z.literal(false)]).optional(), alignDateRangeToGranularity: z.boolean().optional(), onClick: OnClickSchema.optional(), + timelineSeries: z.array(TimelineSeriesSchema).optional(), }); export const _ChartConfigSchema = SharedChartSettingsSchema.extend({ From 717dec32de70e86ac9921e0f54ae34816dde1ed2 Mon Sep 17 00:00:00 2001 From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com> Date: Tue, 5 May 2026 07:31:59 +0000 Subject: [PATCH 2/9] chore: add changeset for Timeline schema addition --- .changeset/timeline-tile-schema.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .changeset/timeline-tile-schema.md diff --git a/.changeset/timeline-tile-schema.md b/.changeset/timeline-tile-schema.md new file mode 100644 index 0000000000..d52cda6c4c --- /dev/null +++ b/.changeset/timeline-tile-schema.md @@ -0,0 +1,13 @@ +--- +'@hyperdx/common-utils': minor +--- + +feat(schema): add Timeline display type and TimelineSeriesSchema + +Adds `DisplayType.Timeline` to the shared enum alongside `TimelineSeriesSchema` +and `TimelineSeries` types. Updates all exhaustive `Record` maps +in `rawSqlParams.ts` and `ChartEditor/constants.tsx`. External API routes Timeline +to the same unsupported-type path as Heatmap. + +This is a schema-only PR. The renderer, builder editor, and dashboard wiring +follow in separate PRs. From ff7be7f6b3e544d8b6dfd0ac9acbcead8b9f0bbf Mon Sep 17 00:00:00 2001 From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com> Date: Tue, 5 May 2026 08:03:48 +0000 Subject: [PATCH 3/9] fix(e2e): exclude Timeline from TileConfig displayType Timeline has no form-based E2E path yet (renderer and editor land in PR B/C). Excluding it from TileConfig keeps the same treatment as Heatmap and unblocks the TypeScript build. Co-Authored-By: Claude Opus --- packages/app/tests/e2e/page-objects/DashboardPage.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/app/tests/e2e/page-objects/DashboardPage.ts b/packages/app/tests/e2e/page-objects/DashboardPage.ts index 5de4dd591f..536484931e 100644 --- a/packages/app/tests/e2e/page-objects/DashboardPage.ts +++ b/packages/app/tests/e2e/page-objects/DashboardPage.ts @@ -14,7 +14,7 @@ import { getSqlEditor } from '../utils/locators'; * Used with verifyTileFormFromConfig */ export type TileConfig = { - displayType: Exclude; + displayType: Exclude; sourceId?: string; select?: | { From 77b24febc9b73c9cc9daf50a38be81f37e9b4a77 Mon Sep 17 00:00:00 2001 From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com> Date: Tue, 5 May 2026 09:05:52 +0000 Subject: [PATCH 4/9] fix(schema): address review feedback on Timeline schema PR - Extract Timeline SQL example to TIMELINE_EXAMPLE_SQL constant in rawSqlParams.ts and import it in ChartEditor/constants.tsx; removes the duplicate inline copy - Add .superRefine() to TimelineSeriesSchema enforcing that events mode requires labelExpression and value_change mode requires trackColumn - Add 4 unit tests covering both valid and invalid cases for the new mode-dependent validation - Fix two em-dashes in TimelineSeriesSchema JSDoc comments Co-Authored-By: Claude Opus --- .../src/components/ChartEditor/constants.tsx | 14 +---- .../common-utils/src/__tests__/types.test.ts | 56 +++++++++++++++++++ packages/common-utils/src/rawSqlParams.ts | 24 ++++---- packages/common-utils/src/types.ts | 19 ++++++- 4 files changed, 88 insertions(+), 25 deletions(-) create mode 100644 packages/common-utils/src/__tests__/types.test.ts diff --git a/packages/app/src/components/ChartEditor/constants.tsx b/packages/app/src/components/ChartEditor/constants.tsx index 86d213b548..ec8c795f56 100644 --- a/packages/app/src/components/ChartEditor/constants.tsx +++ b/packages/app/src/components/ChartEditor/constants.tsx @@ -1,5 +1,6 @@ import { ReactNode } from 'react'; import { DisplayType } from '@hyperdx/common-utils/dist/types'; +import { TIMELINE_EXAMPLE_SQL } from '@hyperdx/common-utils/dist/rawSqlParams'; import { Code, List, Text } from '@mantine/core'; const TIMESERIES_PLACEHOLDER_SQL = `SELECT @@ -46,18 +47,7 @@ WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) [DisplayType.Search]: '', [DisplayType.Heatmap]: '', [DisplayType.Markdown]: '', - [DisplayType.Timeline]: `SELECT - TimestampTime AS ts, - concat(SeverityText, ': ', Body) AS label, - ServiceName AS \`group\`, - SeverityText AS severity -FROM $__sourceTable -WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) - AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) - AND $__filters - AND SeverityText IN ('ERROR', 'FATAL') -ORDER BY ts ASC -LIMIT 1000`, + [DisplayType.Timeline]: TIMELINE_EXAMPLE_SQL, }; const TIMESERIES_INSTRUCTIONS = ( diff --git a/packages/common-utils/src/__tests__/types.test.ts b/packages/common-utils/src/__tests__/types.test.ts new file mode 100644 index 0000000000..ecf3c9c820 --- /dev/null +++ b/packages/common-utils/src/__tests__/types.test.ts @@ -0,0 +1,56 @@ +import { TimelineSeriesSchema } from '../types'; + +const baseValid = { + id: 'series-1', + label: 'My Series', + source: 'logs', + whereLanguage: 'lucene' as const, +}; + +describe('TimelineSeriesSchema', () => { + describe('mode: events', () => { + it('accepts a valid events series with labelExpression', () => { + const result = TimelineSeriesSchema.safeParse({ + ...baseValid, + mode: 'events', + labelExpression: 'Body', + }); + expect(result.success).toBe(true); + }); + + it('rejects an events series missing labelExpression', () => { + const result = TimelineSeriesSchema.safeParse({ + ...baseValid, + mode: 'events', + }); + expect(result.success).toBe(false); + if (!result.success) { + const paths = result.error.issues.map(i => i.path.join('.')); + expect(paths).toContain('labelExpression'); + } + }); + }); + + describe('mode: value_change', () => { + it('accepts a valid value_change series with trackColumn', () => { + const result = TimelineSeriesSchema.safeParse({ + ...baseValid, + mode: 'value_change', + trackColumn: "ResourceAttributes['service.version']", + }); + expect(result.success).toBe(true); + }); + + it('rejects a value_change series missing trackColumn', () => { + const result = TimelineSeriesSchema.safeParse({ + ...baseValid, + mode: 'value_change', + }); + expect(result.success).toBe(false); + if (!result.success) { + const paths = result.error.issues.map(i => i.path.join('.')); + expect(paths).toContain('trackColumn'); + } + }); + }); +}); diff --git a/packages/common-utils/src/rawSqlParams.ts b/packages/common-utils/src/rawSqlParams.ts index ccd137cd97..a074120ac6 100644 --- a/packages/common-utils/src/rawSqlParams.ts +++ b/packages/common-utils/src/rawSqlParams.ts @@ -111,16 +111,7 @@ export const DATE_RANGE_WHERE_EXAMPLE_SQL = `WHERE TimestampTime >= fromUnixTime AND TimestampTime <= fromUnixTimestamp64Milli ({endDateMilliseconds:Int64}) AND $__filters`; -export const QUERY_PARAM_EXAMPLES: Record = { - [DisplayType.Line]: TIME_CHART_EXAMPLE_SQL, - [DisplayType.StackedBar]: TIME_CHART_EXAMPLE_SQL, - [DisplayType.Table]: DATE_RANGE_WHERE_EXAMPLE_SQL, - [DisplayType.Pie]: DATE_RANGE_WHERE_EXAMPLE_SQL, - [DisplayType.Number]: DATE_RANGE_WHERE_EXAMPLE_SQL, - [DisplayType.Search]: '', - [DisplayType.Heatmap]: '', - [DisplayType.Markdown]: '', - [DisplayType.Timeline]: `SELECT +export const TIMELINE_EXAMPLE_SQL = `SELECT TimestampTime AS ts, concat(SeverityText, ': ', Body) AS label, ServiceName AS \`group\`, @@ -131,7 +122,18 @@ WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) AND $__filters AND SeverityText IN ('ERROR', 'FATAL') ORDER BY ts ASC -LIMIT 1000`, +LIMIT 1000`; + +export const QUERY_PARAM_EXAMPLES: Record = { + [DisplayType.Line]: TIME_CHART_EXAMPLE_SQL, + [DisplayType.StackedBar]: TIME_CHART_EXAMPLE_SQL, + [DisplayType.Table]: DATE_RANGE_WHERE_EXAMPLE_SQL, + [DisplayType.Pie]: DATE_RANGE_WHERE_EXAMPLE_SQL, + [DisplayType.Number]: DATE_RANGE_WHERE_EXAMPLE_SQL, + [DisplayType.Search]: '', + [DisplayType.Heatmap]: '', + [DisplayType.Markdown]: '', + [DisplayType.Timeline]: TIMELINE_EXAMPLE_SQL, }; export function renderQueryParam(name: keyof typeof QUERY_PARAMS): string { diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index 524aa130d8..0c68e855d8 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -714,10 +714,10 @@ export const TimelineSeriesSchema = z.object({ * * - In `events` mode, each distinct value becomes a lane label. * - In `value_change` mode, this expression is also used as the SQL - * PARTITION BY for the LAG window function — so version history is + * PARTITION BY for the LAG window function, so version history is * tracked independently per group (e.g. one history per service). * - * Conceptually: "what do I want one row per?" — typically `ServiceName` + * Conceptually: "what do I want one row per?" Typically `ServiceName` * or another resource attribute that identifies the entity being watched. */ groupExpression: z.string().optional(), @@ -738,6 +738,21 @@ export const TimelineSeriesSchema = z.object({ * within the same `groupExpression` partition. */ trackColumn: z.string().optional(), +}).superRefine((val, ctx) => { + if (val.mode === 'events' && !val.labelExpression) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + message: 'labelExpression is required when mode is "events"', + path: ['labelExpression'], + }); + } + if (val.mode === 'value_change' && !val.trackColumn) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + message: 'trackColumn is required when mode is "value_change"', + path: ['trackColumn'], + }); + } }); export type TimelineSeries = z.infer; From a55e933752d54602b1305ac2e87950de9b66adc5 Mon Sep 17 00:00:00 2001 From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com> Date: Tue, 5 May 2026 10:32:26 +0000 Subject: [PATCH 5/9] fix(lint): sort imports in ChartEditor/constants.tsx --- packages/app/src/components/ChartEditor/constants.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/app/src/components/ChartEditor/constants.tsx b/packages/app/src/components/ChartEditor/constants.tsx index ec8c795f56..e131e5a849 100644 --- a/packages/app/src/components/ChartEditor/constants.tsx +++ b/packages/app/src/components/ChartEditor/constants.tsx @@ -1,6 +1,6 @@ import { ReactNode } from 'react'; -import { DisplayType } from '@hyperdx/common-utils/dist/types'; import { TIMELINE_EXAMPLE_SQL } from '@hyperdx/common-utils/dist/rawSqlParams'; +import { DisplayType } from '@hyperdx/common-utils/dist/types'; import { Code, List, Text } from '@mantine/core'; const TIMESERIES_PLACEHOLDER_SQL = `SELECT From 510a4c8fdeecab3179723b7ad9d515eb7739a237 Mon Sep 17 00:00:00 2001 From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com> Date: Tue, 5 May 2026 11:01:41 +0000 Subject: [PATCH 6/9] fix(lint): reformat TimelineSeriesSchema to prettier chaining style Prettier requires the z.object().superRefine() chain to be written as z\n .object()\n .superRefine() when the chain is too long. Reformats the schema to match. Co-Authored-By: Claude Opus --- packages/common-utils/src/types.ts | 106 +++++++++++++++-------------- 1 file changed, 54 insertions(+), 52 deletions(-) diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index 0c68e855d8..400f8b534b 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -702,58 +702,60 @@ export type OnClick = z.infer; // When making changes here, consider if they need to be made to the external API // schema as well (packages/api/src/utils/zod.ts). -export const TimelineSeriesSchema = z.object({ - id: z.string(), - label: z.string().min(1), - mode: z.enum(['events', 'value_change']), - source: z.string(), - where: z.string().optional(), - whereLanguage: SearchConditionLanguageSchema, - /** - * Splits the rendered markers into colored lanes by this expression. - * - * - In `events` mode, each distinct value becomes a lane label. - * - In `value_change` mode, this expression is also used as the SQL - * PARTITION BY for the LAG window function, so version history is - * tracked independently per group (e.g. one history per service). - * - * Conceptually: "what do I want one row per?" Typically `ServiceName` - * or another resource attribute that identifies the entity being watched. - */ - groupExpression: z.string().optional(), - // events mode: - labelExpression: z.string().optional(), - /** - * Optional SQL expression that resolves to a severity string per row - * (e.g. `SeverityText` for OTel log sources). When set, individual event - * markers are colored by severity (FATAL/ERROR/WARN/INFO/DEBUG/TRACE) - * rather than by lane. Only applies in `events` mode. - */ - severityExpression: z.string().optional(), - // value_change mode: - /** - * SQL expression that resolves to the value being tracked for changes - * (e.g. `ResourceAttributes['service.version']`). The renderer emits a - * marker each time this expression's value differs from the previous row - * within the same `groupExpression` partition. - */ - trackColumn: z.string().optional(), -}).superRefine((val, ctx) => { - if (val.mode === 'events' && !val.labelExpression) { - ctx.addIssue({ - code: z.ZodIssueCode.custom, - message: 'labelExpression is required when mode is "events"', - path: ['labelExpression'], - }); - } - if (val.mode === 'value_change' && !val.trackColumn) { - ctx.addIssue({ - code: z.ZodIssueCode.custom, - message: 'trackColumn is required when mode is "value_change"', - path: ['trackColumn'], - }); - } -}); +export const TimelineSeriesSchema = z + .object({ + id: z.string(), + label: z.string().min(1), + mode: z.enum(['events', 'value_change']), + source: z.string(), + where: z.string().optional(), + whereLanguage: SearchConditionLanguageSchema, + /** + * Splits the rendered markers into colored lanes by this expression. + * + * - In `events` mode, each distinct value becomes a lane label. + * - In `value_change` mode, this expression is also used as the SQL + * PARTITION BY for the LAG window function, so version history is + * tracked independently per group (e.g. one history per service). + * + * Conceptually: "what do I want one row per?" Typically `ServiceName` + * or another resource attribute that identifies the entity being watched. + */ + groupExpression: z.string().optional(), + // events mode: + labelExpression: z.string().optional(), + /** + * Optional SQL expression that resolves to a severity string per row + * (e.g. `SeverityText` for OTel log sources). When set, individual event + * markers are colored by severity (FATAL/ERROR/WARN/INFO/DEBUG/TRACE) + * rather than by lane. Only applies in `events` mode. + */ + severityExpression: z.string().optional(), + // value_change mode: + /** + * SQL expression that resolves to the value being tracked for changes + * (e.g. `ResourceAttributes['service.version']`). The renderer emits a + * marker each time this expression's value differs from the previous row + * within the same `groupExpression` partition. + */ + trackColumn: z.string().optional(), + }) + .superRefine((val, ctx) => { + if (val.mode === 'events' && !val.labelExpression) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + message: 'labelExpression is required when mode is "events"', + path: ['labelExpression'], + }); + } + if (val.mode === 'value_change' && !val.trackColumn) { + ctx.addIssue({ + code: z.ZodIssueCode.custom, + message: 'trackColumn is required when mode is "value_change"', + path: ['trackColumn'], + }); + } + }); export type TimelineSeries = z.infer; From 384c81df166dfe48730769ea323a3447430f0f82 Mon Sep 17 00:00:00 2001 From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com> Date: Wed, 6 May 2026 20:03:37 +0000 Subject: [PATCH 7/9] refactor(schema): scope timelineSeries to Builder config timelineSeries is a structured-builder concept (each entry has source, where, whereLanguage, mode, labelExpression/trackColumn). Raw SQL Timeline tiles emit ts/label/group/severity columns directly and do not use these series definitions. Move the field from SharedChartSettingsSchema to _ChartConfigSchema so it sits next to markdown (the existing precedent for tile-type-specific complex fields on the Builder side) instead of leaking onto every Raw SQL chart config. Adds a short comment at the call site explaining the choice. No consumers read timelineSeries today, so this is a pure schema cleanup. --- packages/common-utils/src/types.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index 3d77b7d98a..fa36ae8b58 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -771,7 +771,6 @@ const SharedChartSettingsSchema = z.object({ fillNulls: z.union([z.number(), z.literal(false)]).optional(), alignDateRangeToGranularity: z.boolean().optional(), onClick: OnClickSchema.optional(), - timelineSeries: z.array(TimelineSeriesSchema).optional(), }); export const _ChartConfigSchema = SharedChartSettingsSchema.extend({ @@ -779,6 +778,11 @@ export const _ChartConfigSchema = SharedChartSettingsSchema.extend({ implicitColumnExpression: z.string().optional(), sampleWeightExpression: z.string().optional(), markdown: z.string().optional(), + // Timeline-tile-specific structured-builder series. Lives on the Builder + // config alongside `markdown` rather than on SharedChartSettingsSchema + // because Raw SQL Timeline tiles emit columns directly and do not use + // these series definitions. + timelineSeries: z.array(TimelineSeriesSchema).optional(), filtersLogicalOperator: z.enum(['AND', 'OR']).optional(), filters: z.array(FilterSchema).optional(), connection: z.string(), From c9f2b58a3daa7071a5d0127b70eeb3507a0ea64a Mon Sep 17 00:00:00 2001 From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com> Date: Wed, 6 May 2026 23:37:52 +0000 Subject: [PATCH 8/9] fix(schema): address compound-review P1/P2 on Timeline schema PR MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P1 fixes: - Refactor TimelineSeriesSchema to z.discriminatedUnion('mode', [...]) matching OnClickSchema pattern; removes superRefine and makes mode-required fields (labelExpression, trackColumn) non-optional with z.string().min(1), rejecting empty strings - Trim JSDoc on schema fields to one-line descriptions; remove renderer-mechanics prose that doesn't belong in this PR - Drop TIMELINE_EXAMPLE_SQL and DISPLAY_TYPE_INSTRUCTIONS[Timeline] — both committed to a raw-SQL column contract for a tile users can't select yet; replaced with empty string / omitted from the partial map - Add Timeline placeholder in DBDashboardPage so API-created tiles render a message instead of blank P2 fixes: - Fix Exclude to use enum members so renames don't silently break the exclusion - Add TODO(#2226) comments next to the unsupported Timeline branches in external-api dashboards.ts for coordinated follow-up - Add missing test cases: invalid mode, empty-string labelExpression / trackColumn, optional-fields round-trip on events series Follow-up issue for external-API Timeline support: #2226 --- .../external-api/v2/utils/dashboards.ts | 2 + packages/app/src/DBDashboardPage.tsx | 9 ++ .../src/components/ChartEditor/constants.tsx | 52 +----------- .../tests/e2e/page-objects/DashboardPage.ts | 2 +- .../common-utils/src/__tests__/types.test.ts | 53 ++++++++++-- packages/common-utils/src/rawSqlParams.ts | 15 +--- packages/common-utils/src/types.ts | 82 +++++++------------ 7 files changed, 87 insertions(+), 128 deletions(-) diff --git a/packages/api/src/routers/external-api/v2/utils/dashboards.ts b/packages/api/src/routers/external-api/v2/utils/dashboards.ts index e5ea8d2dde..f0c9facd92 100644 --- a/packages/api/src/routers/external-api/v2/utils/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/utils/dashboards.ts @@ -166,6 +166,7 @@ const convertToExternalTileChartConfig = ( case DisplayType.Search: case DisplayType.Markdown: case DisplayType.Heatmap: + // TODO(#2226): add Timeline raw-SQL external-API support when renderer lands case DisplayType.Timeline: logger.error( { config }, @@ -269,6 +270,7 @@ const convertToExternalTileChartConfig = ( markdown: stringValueOrDefault(config.markdown, ''), }; case DisplayType.Heatmap: + // TODO(#2226): add Timeline builder external-API support when renderer lands case DisplayType.Timeline: case undefined: logger.error( diff --git a/packages/app/src/DBDashboardPage.tsx b/packages/app/src/DBDashboardPage.tsx index e955dba243..4909441655 100644 --- a/packages/app/src/DBDashboardPage.tsx +++ b/packages/app/src/DBDashboardPage.tsx @@ -811,6 +811,15 @@ const Tile = forwardRef( dateRange={dateRange} /> )} + {queriedConfig?.displayType === DisplayType.Timeline && ( + + + + Timeline renderer not yet available. Update your client. + + + + )} {effectiveMarkdownConfig?.displayType === DisplayType.Markdown && 'markdown' in effectiveMarkdownConfig && ( diff --git a/packages/app/src/components/ChartEditor/constants.tsx b/packages/app/src/components/ChartEditor/constants.tsx index e131e5a849..77675dc562 100644 --- a/packages/app/src/components/ChartEditor/constants.tsx +++ b/packages/app/src/components/ChartEditor/constants.tsx @@ -1,5 +1,4 @@ import { ReactNode } from 'react'; -import { TIMELINE_EXAMPLE_SQL } from '@hyperdx/common-utils/dist/rawSqlParams'; import { DisplayType } from '@hyperdx/common-utils/dist/types'; import { Code, List, Text } from '@mantine/core'; @@ -47,7 +46,7 @@ WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) [DisplayType.Search]: '', [DisplayType.Heatmap]: '', [DisplayType.Markdown]: '', - [DisplayType.Timeline]: TIMELINE_EXAMPLE_SQL, + [DisplayType.Timeline]: '', }; const TIMESERIES_INSTRUCTIONS = ( @@ -143,53 +142,4 @@ export const DISPLAY_TYPE_INSTRUCTIONS: Partial< ), - [DisplayType.Timeline]: ( - <> - - Result columns are rendered as event markers on a time axis: - - - - - ts - - - {' '} - (required) — A DateTime or{' '} - DateTime64 column for the event timestamp. - - - - - label - - - {' '} - (required) — A String column for the marker - label shown in tooltips. - - - - - group - - - {' '} - (optional) — A String column to split events - into separate lanes. - - - - - severity - - - {' '} - (optional) — A String column for severity-based - color mapping. - - - - - ), }; diff --git a/packages/app/tests/e2e/page-objects/DashboardPage.ts b/packages/app/tests/e2e/page-objects/DashboardPage.ts index 536484931e..d6e0d9e1c9 100644 --- a/packages/app/tests/e2e/page-objects/DashboardPage.ts +++ b/packages/app/tests/e2e/page-objects/DashboardPage.ts @@ -14,7 +14,7 @@ import { getSqlEditor } from '../utils/locators'; * Used with verifyTileFormFromConfig */ export type TileConfig = { - displayType: Exclude; + displayType: Exclude; sourceId?: string; select?: | { diff --git a/packages/common-utils/src/__tests__/types.test.ts b/packages/common-utils/src/__tests__/types.test.ts index ecf3c9c820..bfa565b2a5 100644 --- a/packages/common-utils/src/__tests__/types.test.ts +++ b/packages/common-utils/src/__tests__/types.test.ts @@ -18,16 +18,37 @@ describe('TimelineSeriesSchema', () => { expect(result.success).toBe(true); }); + it('accepts optional fields on a valid events series', () => { + const result = TimelineSeriesSchema.safeParse({ + ...baseValid, + mode: 'events', + labelExpression: 'Body', + groupExpression: 'ServiceName', + severityExpression: 'SeverityText', + where: 'SeverityText = "ERROR"', + }); + expect(result.success).toBe(true); + if (result.success && result.data.mode === 'events') { + expect(result.data.groupExpression).toBe('ServiceName'); + expect(result.data.severityExpression).toBe('SeverityText'); + } + }); + it('rejects an events series missing labelExpression', () => { const result = TimelineSeriesSchema.safeParse({ ...baseValid, mode: 'events', }); expect(result.success).toBe(false); - if (!result.success) { - const paths = result.error.issues.map(i => i.path.join('.')); - expect(paths).toContain('labelExpression'); - } + }); + + it('rejects an events series with an empty-string labelExpression', () => { + const result = TimelineSeriesSchema.safeParse({ + ...baseValid, + mode: 'events', + labelExpression: '', + }); + expect(result.success).toBe(false); }); }); @@ -47,10 +68,26 @@ describe('TimelineSeriesSchema', () => { mode: 'value_change', }); expect(result.success).toBe(false); - if (!result.success) { - const paths = result.error.issues.map(i => i.path.join('.')); - expect(paths).toContain('trackColumn'); - } + }); + + it('rejects a value_change series with an empty-string trackColumn', () => { + const result = TimelineSeriesSchema.safeParse({ + ...baseValid, + mode: 'value_change', + trackColumn: '', + }); + expect(result.success).toBe(false); + }); + }); + + describe('invalid mode', () => { + it('rejects an unrecognised mode value', () => { + const result = TimelineSeriesSchema.safeParse({ + ...baseValid, + mode: 'unknown_mode', + labelExpression: 'Body', + }); + expect(result.success).toBe(false); }); }); }); diff --git a/packages/common-utils/src/rawSqlParams.ts b/packages/common-utils/src/rawSqlParams.ts index a074120ac6..e59fc79309 100644 --- a/packages/common-utils/src/rawSqlParams.ts +++ b/packages/common-utils/src/rawSqlParams.ts @@ -111,19 +111,6 @@ export const DATE_RANGE_WHERE_EXAMPLE_SQL = `WHERE TimestampTime >= fromUnixTime AND TimestampTime <= fromUnixTimestamp64Milli ({endDateMilliseconds:Int64}) AND $__filters`; -export const TIMELINE_EXAMPLE_SQL = `SELECT - TimestampTime AS ts, - concat(SeverityText, ': ', Body) AS label, - ServiceName AS \`group\`, - SeverityText AS severity -FROM $__sourceTable -WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) - AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64}) - AND $__filters - AND SeverityText IN ('ERROR', 'FATAL') -ORDER BY ts ASC -LIMIT 1000`; - export const QUERY_PARAM_EXAMPLES: Record = { [DisplayType.Line]: TIME_CHART_EXAMPLE_SQL, [DisplayType.StackedBar]: TIME_CHART_EXAMPLE_SQL, @@ -133,7 +120,7 @@ export const QUERY_PARAM_EXAMPLES: Record = { [DisplayType.Search]: '', [DisplayType.Heatmap]: '', [DisplayType.Markdown]: '', - [DisplayType.Timeline]: TIMELINE_EXAMPLE_SQL, + [DisplayType.Timeline]: '', }; export function renderQueryParam(name: keyof typeof QUERY_PARAMS): string { diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index fa36ae8b58..7d5e209e63 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -702,60 +702,34 @@ export type OnClick = z.infer; // When making changes here, consider if they need to be made to the external API // schema as well (packages/api/src/utils/zod.ts). -export const TimelineSeriesSchema = z - .object({ - id: z.string(), - label: z.string().min(1), - mode: z.enum(['events', 'value_change']), - source: z.string(), - where: z.string().optional(), - whereLanguage: SearchConditionLanguageSchema, - /** - * Splits the rendered markers into colored lanes by this expression. - * - * - In `events` mode, each distinct value becomes a lane label. - * - In `value_change` mode, this expression is also used as the SQL - * PARTITION BY for the LAG window function, so version history is - * tracked independently per group (e.g. one history per service). - * - * Conceptually: "what do I want one row per?" Typically `ServiceName` - * or another resource attribute that identifies the entity being watched. - */ - groupExpression: z.string().optional(), - // events mode: - labelExpression: z.string().optional(), - /** - * Optional SQL expression that resolves to a severity string per row - * (e.g. `SeverityText` for OTel log sources). When set, individual event - * markers are colored by severity (FATAL/ERROR/WARN/INFO/DEBUG/TRACE) - * rather than by lane. Only applies in `events` mode. - */ - severityExpression: z.string().optional(), - // value_change mode: - /** - * SQL expression that resolves to the value being tracked for changes - * (e.g. `ResourceAttributes['service.version']`). The renderer emits a - * marker each time this expression's value differs from the previous row - * within the same `groupExpression` partition. - */ - trackColumn: z.string().optional(), - }) - .superRefine((val, ctx) => { - if (val.mode === 'events' && !val.labelExpression) { - ctx.addIssue({ - code: z.ZodIssueCode.custom, - message: 'labelExpression is required when mode is "events"', - path: ['labelExpression'], - }); - } - if (val.mode === 'value_change' && !val.trackColumn) { - ctx.addIssue({ - code: z.ZodIssueCode.custom, - message: 'trackColumn is required when mode is "value_change"', - path: ['trackColumn'], - }); - } - }); +const TimelineSeriesBaseSchema = z.object({ + id: z.string(), + label: z.string().min(1), + source: z.string(), + where: z.string().optional(), + whereLanguage: SearchConditionLanguageSchema, + /** SQL expression whose distinct values split markers into separate lanes. */ + groupExpression: z.string().optional(), +}); + +const TimelineSeriesEventsSchema = TimelineSeriesBaseSchema.extend({ + mode: z.literal('events'), + /** SQL expression that resolves to the marker text shown in tooltips. */ + labelExpression: z.string().min(1), + /** SQL expression that resolves to a severity string per row (e.g. `SeverityText`). Colors markers by severity level. */ + severityExpression: z.string().optional(), +}); + +const TimelineSeriesValueChangeSchema = TimelineSeriesBaseSchema.extend({ + mode: z.literal('value_change'), + /** SQL expression whose value is tracked for changes across rows within each `groupExpression` partition. */ + trackColumn: z.string().min(1), +}); + +export const TimelineSeriesSchema = z.discriminatedUnion('mode', [ + TimelineSeriesEventsSchema, + TimelineSeriesValueChangeSchema, +]); export type TimelineSeries = z.infer; From e962188a784d89c1348c6f4d5c4b601a00cfaa2f Mon Sep 17 00:00:00 2001 From: Alex Fedotyev <61838744+alex-fedotyev@users.noreply.github.com> Date: Thu, 7 May 2026 00:03:21 +0000 Subject: [PATCH 9/9] fix(lint): move TODO comments above case chains to fix no-fallthrough errors ESLint's no-fallthrough rule treats comments between stacked case labels as a break in the fallthrough chain, requiring an explicit break before each subsequent case. Moving the TODO comments above the case group restores the valid empty-fallthrough pattern. --- packages/api/src/routers/external-api/v2/utils/dashboards.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/api/src/routers/external-api/v2/utils/dashboards.ts b/packages/api/src/routers/external-api/v2/utils/dashboards.ts index f0c9facd92..cac8c05f09 100644 --- a/packages/api/src/routers/external-api/v2/utils/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/utils/dashboards.ts @@ -163,10 +163,10 @@ const convertToExternalTileChartConfig = ( sourceId: config.source, numberFormat: config.numberFormat, }; + // TODO(#2226): add Timeline raw-SQL external-API support when renderer lands case DisplayType.Search: case DisplayType.Markdown: case DisplayType.Heatmap: - // TODO(#2226): add Timeline raw-SQL external-API support when renderer lands case DisplayType.Timeline: logger.error( { config }, @@ -269,8 +269,8 @@ const convertToExternalTileChartConfig = ( displayType: config.displayType, markdown: stringValueOrDefault(config.markdown, ''), }; - case DisplayType.Heatmap: // TODO(#2226): add Timeline builder external-API support when renderer lands + case DisplayType.Heatmap: case DisplayType.Timeline: case undefined: logger.error(