Skip to content
Draft
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
13 changes: 13 additions & 0 deletions .changeset/timeline-tile-schema.md
Original file line number Diff line number Diff line change
@@ -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<DisplayType, ...>` 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.
Original file line number Diff line number Diff line change
Expand Up @@ -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 },
Expand Down Expand Up @@ -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 },
Expand Down
9 changes: 9 additions & 0 deletions packages/app/src/DBDashboardPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -1378,6 +1378,15 @@ const Tile = ({
dateRange={effectiveDateRange}
/>
)}
{effectiveQueriedConfig?.displayType === DisplayType.Timeline && (
<ChartContainer title={title} toolbarItems={toolbar}>
<Flex h="100%" align="center" justify="center">
<Text c="dimmed" size="sm">
Timeline renderer not yet available. Update your client.
</Text>
</Flex>
</ChartContainer>
)}
{effectiveMarkdownConfig?.displayType === DisplayType.Markdown &&
'markdown' in effectiveMarkdownConfig && (
<HDXMarkdownChart
Expand Down
1 change: 1 addition & 0 deletions packages/app/src/components/ChartEditor/constants.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
[DisplayType.Search]: '',
[DisplayType.Heatmap]: '',
[DisplayType.Markdown]: '',
[DisplayType.Timeline]: '',
[DisplayType.EventPatterns]: '',
};

Expand Down
93 changes: 93 additions & 0 deletions packages/common-utils/src/__tests__/types.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ import {
PresetDashboardFilterSchema,
PromqlSourceSchema,
SavedChartConfigSchema,
TimelineSeriesSchema,
} from '@/types';

describe('ColorConditionSchema', () => {
Expand Down Expand Up @@ -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);
});
});
});
5 changes: 5 additions & 0 deletions packages/common-utils/src/rawSqlParams.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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]: [],
};

Expand Down Expand Up @@ -125,6 +129,7 @@ export const QUERY_PARAM_EXAMPLES: Record<DisplayType, string> = {
[DisplayType.Search]: '',
[DisplayType.Heatmap]: '',
[DisplayType.Markdown]: '',
[DisplayType.Timeline]: '',
[DisplayType.EventPatterns]: '',
};

Expand Down
38 changes: 38 additions & 0 deletions packages/common-utils/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ export enum DisplayType {
Search = 'search',
Heatmap = 'heatmap',
Markdown = 'markdown',
Timeline = 'timeline',
EventPatterns = 'event_patterns',
}

Expand Down Expand Up @@ -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<typeof TimelineSeriesSchema>;

/**
* Schema describing settings which are shared between Raw SQL
* chart configs and Structured ChartBuilder chart configs
Expand Down Expand Up @@ -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(),
Expand Down
Loading