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. 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 69e143e950..b779dfe9b4 100644 --- a/packages/api/src/routers/external-api/v2/utils/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/utils/dashboards.ts @@ -414,9 +414,11 @@ export 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: + case DisplayType.Timeline: case DisplayType.EventPatterns: logger.error( { config }, @@ -672,6 +674,8 @@ export const convertToExternalTileChartConfig = ( where: stringValueOrDefault(config.where, ''), whereLanguage: config.whereLanguage ?? 'lucene', }; + // TODO(#2226): add Timeline builder external-API support when renderer lands + case DisplayType.Timeline: case undefined: logger.error( { config }, diff --git a/packages/app/src/DBDashboardPage.tsx b/packages/app/src/DBDashboardPage.tsx index f5000d1a75..8473c48ed3 100644 --- a/packages/app/src/DBDashboardPage.tsx +++ b/packages/app/src/DBDashboardPage.tsx @@ -1378,6 +1378,15 @@ const Tile = ({ dateRange={effectiveDateRange} /> )} + {effectiveQueriedConfig?.displayType === DisplayType.Timeline && ( + + + + Timeline renderer not yet available. Update your client. + + + + )} {effectiveMarkdownConfig?.displayType === DisplayType.Markdown && 'markdown' in effectiveMarkdownConfig && ( = fromUnixTimestamp64Milli({startDateMilliseconds:Int64}) [DisplayType.Search]: '', [DisplayType.Heatmap]: '', [DisplayType.Markdown]: '', + [DisplayType.Timeline]: '', [DisplayType.EventPatterns]: '', }; diff --git a/packages/common-utils/src/__tests__/types.test.ts b/packages/common-utils/src/__tests__/types.test.ts index 1640578a2e..53581ed177 100644 --- a/packages/common-utils/src/__tests__/types.test.ts +++ b/packages/common-utils/src/__tests__/types.test.ts @@ -16,6 +16,7 @@ import { PresetDashboardFilterSchema, PromqlSourceSchema, SavedChartConfigSchema, + TimelineSeriesSchema, } from '@/types'; describe('ColorConditionSchema', () => { @@ -1119,3 +1120,95 @@ describe('PromQL saved chart config source', () => { expect(parsed).not.toHaveProperty('connection'); }); }); + +const timelineBaseValid = { + 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({ + ...timelineBaseValid, + mode: 'events', + labelExpression: 'Body', + }); + expect(result.success).toBe(true); + }); + + it('accepts optional fields on a valid events series', () => { + const result = TimelineSeriesSchema.safeParse({ + ...timelineBaseValid, + 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({ + ...timelineBaseValid, + mode: 'events', + }); + expect(result.success).toBe(false); + }); + + it('rejects an events series with an empty-string labelExpression', () => { + const result = TimelineSeriesSchema.safeParse({ + ...timelineBaseValid, + mode: 'events', + labelExpression: '', + }); + expect(result.success).toBe(false); + }); + }); + + describe('mode: value_change', () => { + it('accepts a valid value_change series with trackColumn', () => { + const result = TimelineSeriesSchema.safeParse({ + ...timelineBaseValid, + mode: 'value_change', + trackColumn: "ResourceAttributes['service.version']", + }); + expect(result.success).toBe(true); + }); + + it('rejects a value_change series missing trackColumn', () => { + const result = TimelineSeriesSchema.safeParse({ + ...timelineBaseValid, + mode: 'value_change', + }); + expect(result.success).toBe(false); + }); + + it('rejects a value_change series with an empty-string trackColumn', () => { + const result = TimelineSeriesSchema.safeParse({ + ...timelineBaseValid, + mode: 'value_change', + trackColumn: '', + }); + expect(result.success).toBe(false); + }); + }); + + describe('invalid mode', () => { + it('rejects an unrecognised mode value', () => { + const result = TimelineSeriesSchema.safeParse({ + ...timelineBaseValid, + 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 91fd1eaf23..abd50572a2 100644 --- a/packages/common-utils/src/rawSqlParams.ts +++ b/packages/common-utils/src/rawSqlParams.ts @@ -97,6 +97,10 @@ export const QUERY_PARAMS_BY_DISPLAY_TYPE: Record< [DisplayType.Search]: [], [DisplayType.Heatmap]: [], [DisplayType.Markdown]: [], + [DisplayType.Timeline]: [ + QUERY_PARAMS.startDateMilliseconds, + QUERY_PARAMS.endDateMilliseconds, + ], [DisplayType.EventPatterns]: [], }; @@ -125,6 +129,7 @@ export const QUERY_PARAM_EXAMPLES: Record = { [DisplayType.Search]: '', [DisplayType.Heatmap]: '', [DisplayType.Markdown]: '', + [DisplayType.Timeline]: '', [DisplayType.EventPatterns]: '', }; diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index d21d64df04..7b232f0683 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -42,6 +42,7 @@ export enum DisplayType { Search = 'search', Heatmap = 'heatmap', Markdown = 'markdown', + Timeline = 'timeline', EventPatterns = 'event_patterns', } @@ -1741,6 +1742,38 @@ export function getDefaultLineInterpolation( // as well: the Zod schema (packages/api/src/utils/zod.ts) and the hand-written // OpenAPI JSDoc (packages/api/src/routers/external-api/v2/dashboards.ts), which // duplicates this shape for the generated spec. + +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; + /** * Schema describing settings which are shared between Raw SQL * chart configs and Structured ChartBuilder chart configs @@ -1836,6 +1869,11 @@ export const _ChartConfigSchema = SharedChartSettingsSchema.extend({ useTextIndexForImplicitColumn: UseTextIndexSchema.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(),