diff --git a/.changeset/percentile-aggfn-quantile.md b/.changeset/percentile-aggfn-quantile.md new file mode 100644 index 0000000000..5650a22184 --- /dev/null +++ b/.changeset/percentile-aggfn-quantile.md @@ -0,0 +1,11 @@ +--- +'@hyperdx/common-utils': patch +'@hyperdx/api': patch +'@hyperdx/app': patch +--- + +fix: render percentile aggregations (`p50`, `p90`, `p95`, `p99`) as `quantile` +at the matching level. A chart config with `aggFn: 'p95'` rendered as the +nonexistent ClickHouse function `p95If`. The AI assistant now returns +percentiles with a level instead of a bare `quantile` (median), and v1 metric +chart conversion keeps the percentile level. diff --git a/packages/api/src/controllers/__tests__/ai.test.ts b/packages/api/src/controllers/__tests__/ai.test.ts index 2f7d3a048f..34387aa3ba 100644 --- a/packages/api/src/controllers/__tests__/ai.test.ts +++ b/packages/api/src/controllers/__tests__/ai.test.ts @@ -48,7 +48,10 @@ function setConfig(overrides: Record) { Object.assign(mockConfig, overrides); } -import { getAIModel } from '@/controllers/ai'; +import { DisplayType, SourceKind } from '@hyperdx/common-utils/dist/types'; + +import { getAIModel, getChartConfigFromResolvedConfig } from '@/controllers/ai'; +import type { ISource } from '@/models/source'; beforeEach(() => { setConfig({}); @@ -252,3 +255,44 @@ describe('openai provider', () => { }); }); }); + +describe('getChartConfigFromResolvedConfig', () => { + // @ts-expect-error mock source only has the fields getChartConfigFromResolvedConfig reads + const source: ISource = { + id: 'source-id', + kind: SourceKind.Trace, + connection: 'connection-id', + from: { databaseName: 'default', tableName: 'otel_traces' }, + timestampValueExpression: 'Timestamp', + }; + + it('maps percentile aggregations to quantile with a level', () => { + const result = getChartConfigFromResolvedConfig( + { + displayType: DisplayType.Table, + select: [ + { aggregationFunction: 'max', property: 'Duration' }, + { + aggregationFunction: 'p95', + property: 'Duration', + condition: "ServiceName = 'api'", + }, + ], + groupBy: 'SpanName', + timeRange: 'Past 1h', + }, + source, + ); + + expect(result.select).toEqual([ + { aggFn: 'max', valueExpression: 'Duration' }, + { + aggFn: 'quantile', + level: 0.95, + valueExpression: 'Duration', + aggCondition: "ServiceName = 'api'", + aggConditionLanguage: 'sql', + }, + ]); + }); +}); diff --git a/packages/api/src/controllers/ai.ts b/packages/api/src/controllers/ai.ts index eeaeae13bc..90b201cea5 100644 --- a/packages/api/src/controllers/ai.ts +++ b/packages/api/src/controllers/ai.ts @@ -5,6 +5,7 @@ import { TableMetadata, tcFromSource, } from '@hyperdx/common-utils/dist/core/metadata'; +import { resolvePercentileAggFn } from '@hyperdx/common-utils/dist/core/utils'; import { AILineTableResponse, AssistantLineTableConfigSchema, @@ -257,16 +258,18 @@ export function getChartConfigFromResolvedConfig( return { displayType: resObject.displayType, - select: resObject.select.map(s => ({ - aggFn: s.aggregationFunction, - valueExpression: s.property, - ...(s.condition - ? { - aggCondition: s.condition, - aggConditionLanguage: 'sql', - } - : {}), - })), + select: resObject.select.map(s => + resolvePercentileAggFn({ + aggFn: s.aggregationFunction, + valueExpression: s.property, + ...(s.condition + ? { + aggCondition: s.condition, + aggConditionLanguage: 'sql', + } + : {}), + }), + ), from: { tableName: source.from.tableName, databaseName: source.from.databaseName, diff --git a/packages/api/src/routers/api/ai.ts b/packages/api/src/routers/api/ai.ts index 5f55fbd61f..789bab236a 100644 --- a/packages/api/src/routers/api/ai.ts +++ b/packages/api/src/routers/api/ai.ts @@ -56,7 +56,7 @@ Generate a visualization or search that matches their request. The chart should Here are some guidelines: - Use appropriate display types: 'line' for time series, 'table' for tabular data -- Use appropriate aggregate functions depending on user's request: 'count', 'sum', 'avg', 'min', 'max', 'count_distinct' +- Use appropriate aggregate functions depending on user's request: 'count', 'sum', 'avg', 'min', 'max', 'count_distinct', and 'p50', 'p90', 'p95', 'p99' for percentiles - If the user is requesting for a specific set of data (ex. "frontend service", filter the condition by the appropriate property based on the below properties ex. \`ServiceName = 'frontend'\`) - Pick an appropriate time range based on the user's request if one can be inferred from the request. diff --git a/packages/app/src/ChartUtils.tsx b/packages/app/src/ChartUtils.tsx index 10346ad7e0..0cac259521 100644 --- a/packages/app/src/ChartUtils.tsx +++ b/packages/app/src/ChartUtils.tsx @@ -23,6 +23,7 @@ import { convertToNumberChartConfig, convertToTableChartConfig, getAlignedDateRange, + getPercentileAggFnLevel, Granularity, hasPositiveSeriesLimit, TIME_SERIES_DISPLAY_TYPE_BY_NAME, @@ -1111,16 +1112,11 @@ const mapV1AggFnToV2 = (aggFn?: AggFn): AggFnV2 | undefined => { } // Map rate-based aggregations to their base aggregation if (aggFn.endsWith('_rate')) { - return mapV1AggFnToV2(aggFn.replace('_rate', '') as AggFn); + return mapV1AggFnToV2(aggFn.replace(/_rate$/, '') as AggFn); } // Map percentiles to quantile - if ( - aggFn === 'p50' || - aggFn === 'p90' || - aggFn === 'p95' || - aggFn === 'p99' - ) { + if (getPercentileAggFnLevel(aggFn) != null) { return 'quantile'; } @@ -1218,8 +1214,12 @@ export const convertV1ChartConfigToV2 = ( const metricDataType = z .nativeEnum(MetricsDataTypeV2) .parse(rawMetricDataType?.toLowerCase()); + const percentileLevel = getPercentileAggFnLevel( + s.aggFn?.replace(/_rate$/, ''), + ); return { aggFn: mapV1AggFnToV2(s.aggFn), + ...(percentileLevel != null ? { level: percentileLevel } : {}), metricType: metricDataType, valueExpression: field, metricName, diff --git a/packages/app/src/__tests__/ChartUtils.test.ts b/packages/app/src/__tests__/ChartUtils.test.ts index 80f90cc490..89ad6d1488 100644 --- a/packages/app/src/__tests__/ChartUtils.test.ts +++ b/packages/app/src/__tests__/ChartUtils.test.ts @@ -15,6 +15,7 @@ import { convertToReducedPromqlChartConfig, convertToTableChartConfig, convertToTimeChartConfig, + convertV1ChartConfigToV2, findNearestSeriesKey, formatResponseForCategoricalChart, formatResponseForTimeChart, @@ -1878,3 +1879,56 @@ describe('getSeriesColorForGroup', () => { expect(getSeriesColorForGroup(lineData, 'api')).toBe('#solid'); }); }); + +describe('convertV1ChartConfigToV2', () => { + const metricSource = { + id: 'metric-source', + kind: SourceKind.Metric, + connection: 'connection-id', + from: { databaseName: 'default', tableName: '' }, + timestampValueExpression: 'TimeUnix', + resourceAttributesExpression: 'ResourceAttributes', + metricTables: { + gauge: 'otel_metrics_gauge', + histogram: 'otel_metrics_histogram', + sum: 'otel_metrics_sum', + }, + } as unknown as Parameters[1]['metric']; + + const convertMetricSeries = (aggFn: 'p95' | 'p99_rate' | 'avg') => + convertV1ChartConfigToV2( + { + series: [ + { + type: 'time', + table: 'metrics', + aggFn, + field: 'http.server.duration - Gauge', + where: '', + groupBy: [], + }, + ], + dateRange: [new Date('2025-02-12'), new Date('2025-02-14')], + seriesReturnType: 'column', + }, + { metric: metricSource }, + ).select; + + it('converts a percentile to quantile with its level', () => { + expect(convertMetricSeries('p95')).toEqual([ + expect.objectContaining({ aggFn: 'quantile', level: 0.95 }), + ]); + }); + + it('converts a percentile rate to quantile with its level', () => { + expect(convertMetricSeries('p99_rate')).toEqual([ + expect.objectContaining({ aggFn: 'quantile', level: 0.99 }), + ]); + }); + + it('sets no level for other aggregations', () => { + const [select] = convertMetricSeries('avg'); + expect(select).toEqual(expect.objectContaining({ aggFn: 'avg' })); + expect(select).not.toHaveProperty('level'); + }); +}); diff --git a/packages/app/src/components/AggFnSelect.tsx b/packages/app/src/components/AggFnSelect.tsx index 3b6d0a5dbc..fc8b839d3c 100644 --- a/packages/app/src/components/AggFnSelect.tsx +++ b/packages/app/src/components/AggFnSelect.tsx @@ -1,5 +1,6 @@ import { useCallback, useMemo } from 'react'; import { useController, UseControllerProps } from 'react-hook-form'; +import { getPercentileAggFnLevel } from '@hyperdx/common-utils/dist/core/utils'; import { MetricsDataType } from '@hyperdx/common-utils/dist/types'; import { Select } from '@mantine/core'; @@ -64,13 +65,11 @@ function AggFnSelect({ }) { const _onChange = useCallback( (value: string | null) => { + const percentileLevel = getPercentileAggFnLevel(value ?? undefined); if (value == null) { onChange({}); - } else if (['p50', 'p90', 'p95', 'p99'].includes(value)) { - onChange({ - aggFn: 'quantile', - level: Number.parseFloat(value.replace('p', '0.')), - }); + } else if (percentileLevel != null) { + onChange({ aggFn: 'quantile', level: percentileLevel }); } else { // @ts-expect-error Mantine Select passes a string; onChange expects a narrowed AggFn union onChange({ aggFn: value }); diff --git a/packages/common-utils/src/__tests__/renderChartConfig.test.ts b/packages/common-utils/src/__tests__/renderChartConfig.test.ts index 6e6dd139a7..41aea39ed9 100644 --- a/packages/common-utils/src/__tests__/renderChartConfig.test.ts +++ b/packages/common-utils/src/__tests__/renderChartConfig.test.ts @@ -3712,6 +3712,66 @@ describe('renderChartConfig', () => { expect(sql).toContain("hasToken(lower(Body), lower('denied'))"); }); + describe('percentile shorthand aggFn', () => { + const baseTraceConfig: ChartConfigWithOptDateRange = { + displayType: DisplayType.Table, + connection: 'test-connection', + from: { + databaseName: 'default', + tableName: 'otel_traces', + }, + select: [], + where: '', + whereLanguage: 'sql', + timestampValueExpression: 'Timestamp', + dateRange: [new Date('2025-02-12'), new Date('2025-02-14')], + }; + + it('renders p95 as quantile at level 0.95', async () => { + const config: ChartConfigWithOptDateRange = { + ...baseTraceConfig, + select: [ + { + aggFn: 'p95', + valueExpression: 'Duration', + aggCondition: "ServiceName = 'api'", + aggConditionLanguage: 'sql', + }, + ], + }; + + const actual = parameterizedQueryToSql( + await renderChartConfig(config, mockMetadata, querySettings), + ); + expect(actual).toContain( + 'quantileIf(0.95)(toFloat64OrDefault(toString(Duration))', + ); + expect(actual).not.toContain('p95'); + }); + + it('renders p99 as sample-weighted quantile at level 0.99', async () => { + const config: ChartConfigWithOptDateRange = { + ...baseTraceConfig, + sampleWeightExpression: 'SampleRate', + select: [ + { + aggFn: 'p99', + valueExpression: 'Duration', + aggCondition: '', + }, + ], + }; + + const actual = parameterizedQueryToSql( + await renderChartConfig(config, mockMetadata, querySettings), + ); + expect(actual).toContain( + 'quantileTDigestWeighted(0.99)(toFloat64OrDefault(toString(Duration))', + ); + expect(actual).not.toContain('p99'); + }); + }); + describe('sample-weighted aggregations', () => { const baseSampledConfig: ChartConfigWithOptDateRange = { displayType: DisplayType.Table, diff --git a/packages/common-utils/src/__tests__/utils.test.ts b/packages/common-utils/src/__tests__/utils.test.ts index 99945eceaa..fca664ed9a 100644 --- a/packages/common-utils/src/__tests__/utils.test.ts +++ b/packages/common-utils/src/__tests__/utils.test.ts @@ -13,6 +13,7 @@ import { getAlignedDateRange, getDistributedTableArgs, getFirstOrderingItem, + getPercentileAggFnLevel, hasNonEmptyOrderBy, hasPositiveSeriesLimit, isFirstOrderByAscending, @@ -25,6 +26,7 @@ import { parseToStartOfFunction, pickBucketTimestampColumn, replaceJsonExpressions, + resolvePercentileAggFn, splitAndTrimCSV, splitAndTrimWithBracket, } from '@/core/utils'; @@ -3500,4 +3502,44 @@ describe('utils', () => { ).toBe('30 second'); }); }); + + describe('getPercentileAggFnLevel', () => { + it.each([ + ['p50', 0.5], + ['p90', 0.9], + ['p95', 0.95], + ['p99', 0.99], + ])('returns the level of %s', (aggFn, level) => { + expect(getPercentileAggFnLevel(aggFn)).toBe(level); + }); + + it.each(['quantile', 'avg', 'p75', 'toString', undefined])( + 'returns undefined for %s', + aggFn => { + expect(getPercentileAggFnLevel(aggFn)).toBeUndefined(); + }, + ); + }); + + describe('resolvePercentileAggFn', () => { + it('rewrites a percentile shorthand as quantile with its level', () => { + expect( + resolvePercentileAggFn({ + aggFn: 'p95', + valueExpression: 'Duration', + aggCondition: "ServiceName = 'api'", + }), + ).toEqual({ + aggFn: 'quantile', + level: 0.95, + valueExpression: 'Duration', + aggCondition: "ServiceName = 'api'", + }); + }); + + it('returns other select items unchanged', () => { + const select = { aggFn: 'quantile', level: 0.5, valueExpression: 'x' }; + expect(resolvePercentileAggFn(select)).toBe(select); + }); + }); }); diff --git a/packages/common-utils/src/core/renderChartConfig.ts b/packages/common-utils/src/core/renderChartConfig.ts index db9835ea61..28e6c6985a 100644 --- a/packages/common-utils/src/core/renderChartConfig.ts +++ b/packages/common-utils/src/core/renderChartConfig.ts @@ -22,6 +22,7 @@ import { optimizeTimestampValueExpression, parseToStartOfFunction, pickBucketTimestampColumn, + resolvePercentileAggFn, splitAndTrimWithBracket, } from '@/core/utils'; import { isPromqlChartConfig, isRawSqlChartConfig } from '@/guards'; @@ -3276,7 +3277,18 @@ export async function renderChartConfig( // Expand dashboard variables before anything reads the config's expressions, // so metric translation and the CTEs it builds all see final SQL fragments. - const substitutedChartConfig = substituteChartConfigVariables(rawChartConfig); + const variableSubstitutedChartConfig = + substituteChartConfigVariables(rawChartConfig); + const substitutedChartConfig = Array.isArray( + variableSubstitutedChartConfig.select, + ) + ? { + ...variableSubstitutedChartConfig, + select: variableSubstitutedChartConfig.select.map( + resolvePercentileAggFn, + ), + } + : variableSubstitutedChartConfig; // A metric chart with multiple series composes one query per series into a // single UNION ALL + pivot statement (each metric type needs its own CTE diff --git a/packages/common-utils/src/core/utils.ts b/packages/common-utils/src/core/utils.ts index 4440a21fe8..e249239c9c 100644 --- a/packages/common-utils/src/core/utils.ts +++ b/packages/common-utils/src/core/utils.ts @@ -33,6 +33,8 @@ import { DashboardTemplateSchema, DashboardWithoutId, DisplayType, + PERCENTILE_AGG_FN_LEVELS, + PercentileAggregateFunctionSchema, QuerySettings, RawSqlChartConfig, SavedChartConfig, @@ -49,6 +51,35 @@ import { SkipIndexMetadata, TableMetadata } from './metadata'; /** The default maximum number of buckets setting when determining a bucket duration for 'auto' granularity */ export const DEFAULT_AUTO_GRANULARITY_MAX_BUCKETS = 60; +/** + * Returns the quantile level of a percentile shorthand aggFn (`p95` -> 0.95), + * or undefined for any other aggFn. + */ +export function getPercentileAggFnLevel( + aggFn: string | undefined, +): number | undefined { + const parsed = PercentileAggregateFunctionSchema.safeParse(aggFn); + return parsed.success ? PERCENTILE_AGG_FN_LEVELS[parsed.data] : undefined; +} + +/** A select item rewritten by `resolvePercentileAggFn` as `quantile` at a level. */ +export type QuantileResolvedSelect = Omit & { + aggFn: 'quantile'; + level: number; +}; + +/** + * Rewrites a select item with a percentile shorthand aggFn (`p50`, `p90`, + * `p95`, `p99`) as `quantile` with the matching level. Any other select item + * is returned unchanged. + */ +export function resolvePercentileAggFn( + select: T, +): T | QuantileResolvedSelect { + const level = getPercentileAggFnLevel(select.aggFn); + return level == null ? select : { ...select, aggFn: 'quantile', level }; +} + /** * Whether a tile's `seriesLimit` should apply an actual limit. Per the schema * (SharedChartSettingsSchema.seriesLimit): a positive integer caps the series; diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index c0e963be44..814f70bb3e 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -184,6 +184,23 @@ export const AggregateFunctionWithCombinatorsSchema = z .string() .regex(/^(\w+)If(State|Merge)$/); +// Percentile shorthands for `quantile` at a fixed level. +export const PercentileAggregateFunctionSchema = z.enum([ + 'p50', + 'p90', + 'p95', + 'p99', +]); +export const PERCENTILE_AGG_FN_LEVELS = { + p50: 0.5, + p90: 0.9, + p95: 0.95, + p99: 0.99, +} as const satisfies Record< + z.infer, + number +>; + // 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 RootValueExpressionSchema = z @@ -2805,10 +2822,11 @@ export const AssistantLineTableConfigSchema = z.object({ select: z .array( z.object({ - // TODO: Change percentile to fixed functions - aggregationFunction: AggregateFunctionSchema.describe( - 'SQL-like function to aggregate the property by', - ), + aggregationFunction: AggregateFunctionSchema.exclude(['quantile']) + .or(PercentileAggregateFunctionSchema) + .describe( + 'SQL-like function to aggregate the property by. Percentiles are p50, p90, p95 and p99', + ), property: z .string() .describe('Property or column to be aggregated (ex. Duration)'),