From 4182b4e80c49652f7492a54f0522029b78324350 Mon Sep 17 00:00:00 2001 From: Karl Power Date: Tue, 20 Oct 2026 14:22:07 +0200 Subject: [PATCH 1/6] docs: Document PromQL dashboard tiles in the external API spec Add PromQL variants for each tile display type to the OpenAPI schemas, and correct the PromqlSource description: a PromQL source can read a ClickHouse TimeSeries table, not only a Prometheus endpoint. --- packages/api/openapi.json | 552 +++++++++++++++++- .../src/routers/external-api/v2/dashboards.ts | 413 ++++++++++++- .../src/routers/external-api/v2/sources.ts | 8 +- 3 files changed, 934 insertions(+), 39 deletions(-) diff --git a/packages/api/openapi.json b/packages/api/openapi.json index de21409f23..967fd47119 100644 --- a/packages/api/openapi.json +++ b/packages/api/openapi.json @@ -2446,13 +2446,16 @@ } }, "HeatmapChartConfig": { - "description": "Heatmap tile. Heatmap is builder-only (no Raw SQL variant). Omit heatmapMode (or set it to \"distribution\") for the distribution variant; set heatmapMode to \"series\" for the series variant.\n", + "description": "Heatmap tile. There is no Raw SQL variant. For the builder variant, omit heatmapMode (or set it to \"distribution\") for the distribution heatmap, or set it to \"series\" for the series heatmap. Set configType to \"promql\" for the PromQL variant.\n", "oneOf": [ { "$ref": "#/components/schemas/HeatmapDistributionChartConfig" }, { "$ref": "#/components/schemas/HeatmapSeriesChartConfig" + }, + { + "$ref": "#/components/schemas/HeatmapPromqlChartConfig" } ] }, @@ -2845,54 +2848,547 @@ } ] }, + "PromqlRangeExpression": { + "type": "object", + "required": [ + "expression" + ], + "description": "A PromQL expression evaluated over the dashboard time range.", + "properties": { + "expression": { + "type": "string", + "maxLength": 10000, + "description": "PromQL expression. Supports dashboard variables and the $__interval, $__rate_interval, and $__range macros.\n", + "example": "sum by (job) (rate(http_requests_total[$__rate_interval]))" + }, + "alias": { + "type": "string", + "maxLength": 10000, + "description": "Prefixed to every series name this expression produces.", + "example": "Requests" + } + } + }, + "PromqlInstantExpression": { + "description": "A PromQL expression on a table, number, pie, or bar tile, which can be evaluated at a single instant instead of over a range.\n", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlRangeExpression" + }, + { + "type": "object", + "properties": { + "queryType": { + "type": "string", + "enum": [ + "range", + "instant" + ], + "description": "Whether to evaluate over the time range or at its end. Defaults to \"range\" when omitted.\n", + "example": "instant" + } + } + } + ] + }, + "PromqlReducibleExpression": { + "description": "A PromQL expression on a number, pie, or bar tile, which reduces each series of a range query to a single value.\n", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlInstantExpression" + }, + { + "type": "object", + "properties": { + "reducer": { + "type": "string", + "enum": [ + "lastNotNull", + "min", + "max", + "mean", + "sum", + "count" + ], + "description": "How a range query's samples are reduced to one value. Only used when queryType is \"range\". Defaults to \"lastNotNull\" when omitted.\n", + "example": "max" + } + } + } + ] + }, + "PromqlChartConfigBase": { + "type": "object", + "required": [ + "configType", + "sourceId" + ], + "description": "Shared fields for PromQL chart configs. Set configType to \"promql\" and provide sourceId + expressions. The connection is read from the source.\n", + "properties": { + "configType": { + "type": "string", + "enum": [ + "promql" + ], + "description": "Must be \"promql\" to use the PromQL chart config variant.", + "example": "promql" + }, + "sourceId": { + "type": "string", + "description": "ID of the PromQL source to query. Must be a source of kind \"promql\".", + "example": "65f5e4a3b9e77c001a333333" + }, + "granularity": { + "type": "string", + "pattern": "^(\\d+ (second|minute|hour|day)|auto)$", + "description": "Resolution of range queries, used as the Prometheus step and the $__interval macro. Defaults to \"auto\", which picks one from the time range.\n", + "example": "5 minute" + }, + "numberFormat": { + "$ref": "#/components/schemas/NumberFormat", + "description": "Number formatting options for displayed values." + } + } + }, + "PromqlTimeChartConfigBase": { + "description": "Shared fields for PromQL time-series chart configs.", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlChartConfigBase" + }, + { + "type": "object", + "required": [ + "expressions" + ], + "properties": { + "expressions": { + "type": "array", + "minItems": 1, + "maxItems": 10, + "description": "PromQL expressions to plot.", + "items": { + "$ref": "#/components/schemas/PromqlRangeExpression" + } + }, + "legendTemplate": { + "type": "string", + "maxLength": 1024, + "description": "Template for series names, using the series' Prometheus labels in double braces.\n", + "example": "{{job}} - {{instance}}" + }, + "fillNulls": { + "type": "boolean", + "description": "Fill missing time buckets with zero instead of leaving gaps.", + "default": true + }, + "alignDateRangeToGranularity": { + "type": "boolean", + "description": "Expand date range boundaries to the query granularity interval.", + "default": true + }, + "seriesLimit": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of series rendered (top-N by value). Omit to use the default render cap, set 0 for unlimited, or a positive N to keep the top N series.\n", + "example": 5 + } + } + } + ] + }, + "LinePromqlChartConfig": { + "description": "PromQL configuration for a line time-series chart.", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlTimeChartConfigBase" + }, + { + "type": "object", + "required": [ + "displayType" + ], + "properties": { + "displayType": { + "type": "string", + "enum": [ + "line" + ], + "description": "Display as a line time-series chart.", + "example": "line" + }, + "compareToPreviousPeriod": { + "type": "boolean", + "description": "Overlay the equivalent previous time period for comparison.", + "default": false + }, + "lineInterpolation": { + "type": "string", + "enum": [ + "smooth", + "linear", + "step" + ], + "example": "step", + "description": "How points are connected. Defaults to \"smooth\" when omitted.\n" + } + } + } + ] + }, + "BarPromqlChartConfig": { + "description": "PromQL configuration for a stacked-bar time-series chart.", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlTimeChartConfigBase" + }, + { + "type": "object", + "required": [ + "displayType" + ], + "properties": { + "displayType": { + "type": "string", + "enum": [ + "stacked_bar" + ], + "description": "Display as a stacked-bar time-series chart.", + "example": "stacked_bar" + } + } + } + ] + }, + "StackedLinePromqlChartConfig": { + "description": "PromQL configuration for a stacked-line time-series chart.", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlTimeChartConfigBase" + }, + { + "type": "object", + "required": [ + "displayType" + ], + "properties": { + "displayType": { + "type": "string", + "enum": [ + "stacked_line" + ], + "description": "Display as a stacked-line time-series chart.", + "example": "stacked_line" + }, + "lineInterpolation": { + "type": "string", + "enum": [ + "smooth", + "linear", + "step" + ], + "example": "step", + "description": "How points are connected. Defaults to \"linear\" when omitted.\n" + } + } + } + ] + }, + "TablePromqlChartConfig": { + "description": "PromQL configuration for a table chart, with one row per series and one column per label.\n", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlChartConfigBase" + }, + { + "type": "object", + "required": [ + "displayType", + "expressions" + ], + "properties": { + "displayType": { + "type": "string", + "enum": [ + "table" + ], + "description": "Display as a table chart.", + "example": "table" + }, + "expressions": { + "type": "array", + "minItems": 1, + "maxItems": 10, + "description": "PromQL expressions to tabulate.", + "items": { + "$ref": "#/components/schemas/PromqlInstantExpression" + } + } + } + } + ] + }, + "NumberPromqlChartConfig": { + "description": "PromQL configuration for a single big-number chart.", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlChartConfigBase" + }, + { + "type": "object", + "required": [ + "displayType", + "expressions" + ], + "properties": { + "displayType": { + "type": "string", + "enum": [ + "number" + ], + "description": "Display as a single big-number chart.", + "example": "number" + }, + "expressions": { + "type": "array", + "minItems": 1, + "maxItems": 10, + "description": "PromQL expressions. The tile displays the first value.", + "items": { + "$ref": "#/components/schemas/PromqlReducibleExpression" + } + }, + "color": { + "$ref": "#/components/schemas/ChartPaletteToken", + "description": "Optional static color applied to the displayed number." + }, + "colorRules": { + "type": "array", + "maxItems": 10, + "description": "Ordered conditional color rules evaluated against the displayed value (last match wins). Falls back to color, then the default text color when no rule matches.\n", + "items": { + "$ref": "#/components/schemas/NumberTileColorCondition" + } + }, + "backgroundChart": { + "$ref": "#/components/schemas/BackgroundChart", + "description": "Optional trend sparkline drawn behind the number. Only rendered when the expression uses a range query.\n" + } + } + } + ] + }, + "PiePromqlChartConfig": { + "description": "PromQL configuration for a pie chart, with one slice per series.", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlChartConfigBase" + }, + { + "type": "object", + "required": [ + "displayType", + "expressions" + ], + "properties": { + "displayType": { + "type": "string", + "enum": [ + "pie" + ], + "description": "Display as a pie chart.", + "example": "pie" + }, + "expressions": { + "type": "array", + "minItems": 1, + "maxItems": 10, + "description": "PromQL expressions to plot.", + "items": { + "$ref": "#/components/schemas/PromqlReducibleExpression" + } + }, + "legendTemplate": { + "type": "string", + "maxLength": 1024, + "description": "Template for slice names, using the series' Prometheus labels in double braces.\n", + "example": "{{job}}" + }, + "limit": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of slices (top-N by value). Omit to use the default cap, set 0 for unlimited, or a positive N to keep the top N.\n", + "example": 10 + } + } + } + ] + }, + "CategoricalBarPromqlChartConfig": { + "description": "PromQL configuration for a categorical bar chart, with one bar per series.", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlChartConfigBase" + }, + { + "type": "object", + "required": [ + "displayType", + "expressions" + ], + "properties": { + "displayType": { + "type": "string", + "enum": [ + "bar" + ], + "description": "Display as a categorical bar chart.", + "example": "bar" + }, + "expressions": { + "type": "array", + "minItems": 1, + "maxItems": 10, + "description": "PromQL expressions to plot.", + "items": { + "$ref": "#/components/schemas/PromqlReducibleExpression" + } + }, + "legendTemplate": { + "type": "string", + "maxLength": 1024, + "description": "Template for bar names, using the series' Prometheus labels in double braces.\n", + "example": "{{job}}" + }, + "limit": { + "type": "integer", + "minimum": 0, + "description": "Maximum number of bars (top-N by value). Omit to use the default cap, set 0 for unlimited, or a positive N to keep the top N.\n", + "example": 10 + } + } + } + ] + }, + "HeatmapPromqlChartConfig": { + "description": "PromQL configuration for a heatmap.", + "allOf": [ + { + "$ref": "#/components/schemas/PromqlChartConfigBase" + }, + { + "type": "object", + "required": [ + "displayType", + "expressions" + ], + "properties": { + "displayType": { + "type": "string", + "enum": [ + "heatmap" + ], + "description": "Display as a heatmap.", + "example": "heatmap" + }, + "expressions": { + "type": "array", + "minItems": 1, + "maxItems": 10, + "description": "PromQL expressions to plot.", + "items": { + "$ref": "#/components/schemas/PromqlRangeExpression" + } + }, + "heatmapMode": { + "type": "string", + "enum": [ + "distribution", + "series", + "histogram" + ], + "description": "\"distribution\" buckets the values of all series over time, \"series\" draws one row per series, and \"histogram\" draws one row per Prometheus histogram bucket (series need an \"le\" label). Defaults to \"distribution\" when omitted.\n", + "example": "histogram" + }, + "heatmapScaleType": { + "type": "string", + "enum": [ + "log", + "linear" + ], + "description": "Y-axis scale of a distribution heatmap.", + "example": "log" + }, + "legendTemplate": { + "type": "string", + "maxLength": 1024, + "description": "Template for row names of a series heatmap, using the series' Prometheus labels in double braces.\n", + "example": "{{job}}" + } + } + } + ] + }, "LineChartConfig": { - "description": "Line chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n", + "description": "Line chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate), or to \"promql\" for the PromQL variant (requires sourceId and expressions).\n", "oneOf": [ { "$ref": "#/components/schemas/LineBuilderChartConfig" }, { "$ref": "#/components/schemas/LineRawSqlChartConfig" + }, + { + "$ref": "#/components/schemas/LinePromqlChartConfig" } ], "discriminator": { "propertyName": "configType", "mapping": { - "sql": "#/components/schemas/LineRawSqlChartConfig" + "sql": "#/components/schemas/LineRawSqlChartConfig", + "promql": "#/components/schemas/LinePromqlChartConfig" } } }, "BarChartConfig": { - "description": "Stacked-bar chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n", + "description": "Stacked-bar chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate), or to \"promql\" for the PromQL variant (requires sourceId and expressions).\n", "oneOf": [ { "$ref": "#/components/schemas/BarBuilderChartConfig" }, { "$ref": "#/components/schemas/BarRawSqlChartConfig" + }, + { + "$ref": "#/components/schemas/BarPromqlChartConfig" } ], "discriminator": { "propertyName": "configType", "mapping": { - "sql": "#/components/schemas/BarRawSqlChartConfig" + "sql": "#/components/schemas/BarRawSqlChartConfig", + "promql": "#/components/schemas/BarPromqlChartConfig" } } }, "StackedLineChartConfig": { - "description": "Stacked-line chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n", + "description": "Stacked-line chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate), or to \"promql\" for the PromQL variant (requires sourceId and expressions).\n", "oneOf": [ { "$ref": "#/components/schemas/StackedLineBuilderChartConfig" }, { "$ref": "#/components/schemas/StackedLineRawSqlChartConfig" + }, + { + "$ref": "#/components/schemas/StackedLinePromqlChartConfig" } ], "discriminator": { "propertyName": "configType", "mapping": { - "sql": "#/components/schemas/StackedLineRawSqlChartConfig" + "sql": "#/components/schemas/StackedLineRawSqlChartConfig", + "promql": "#/components/schemas/StackedLinePromqlChartConfig" } } }, @@ -3103,75 +3599,91 @@ } }, "TableChartConfig": { - "description": "Table chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n", + "description": "Table chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate), or to \"promql\" for the PromQL variant (requires sourceId and expressions).\n", "oneOf": [ { "$ref": "#/components/schemas/TableBuilderChartConfig" }, { "$ref": "#/components/schemas/TableRawSqlChartConfig" + }, + { + "$ref": "#/components/schemas/TablePromqlChartConfig" } ], "discriminator": { "propertyName": "configType", "mapping": { - "sql": "#/components/schemas/TableRawSqlChartConfig" + "sql": "#/components/schemas/TableRawSqlChartConfig", + "promql": "#/components/schemas/TablePromqlChartConfig" } } }, "NumberChartConfig": { - "description": "Single big-number chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n", + "description": "Single big-number chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate), or to \"promql\" for the PromQL variant (requires sourceId and expressions).\n", "oneOf": [ { "$ref": "#/components/schemas/NumberBuilderChartConfig" }, { "$ref": "#/components/schemas/NumberRawSqlChartConfig" + }, + { + "$ref": "#/components/schemas/NumberPromqlChartConfig" } ], "discriminator": { "propertyName": "configType", "mapping": { - "sql": "#/components/schemas/NumberRawSqlChartConfig" + "sql": "#/components/schemas/NumberRawSqlChartConfig", + "promql": "#/components/schemas/NumberPromqlChartConfig" } } }, "PieChartConfig": { - "description": "Pie chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n", + "description": "Pie chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate), or to \"promql\" for the PromQL variant (requires sourceId and expressions).\n", "oneOf": [ { "$ref": "#/components/schemas/PieBuilderChartConfig" }, { "$ref": "#/components/schemas/PieRawSqlChartConfig" + }, + { + "$ref": "#/components/schemas/PiePromqlChartConfig" } ], "discriminator": { "propertyName": "configType", "mapping": { - "sql": "#/components/schemas/PieRawSqlChartConfig" + "sql": "#/components/schemas/PieRawSqlChartConfig", + "promql": "#/components/schemas/PiePromqlChartConfig" } } }, "CategoricalBarChartConfig": { - "description": "Categorical bar chart (one bar per group value; not a time series). Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n", + "description": "Categorical bar chart (one bar per group value; not a time series). Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate), or to \"promql\" for the PromQL variant (requires sourceId and expressions).\n", "oneOf": [ { "$ref": "#/components/schemas/CategoricalBarBuilderChartConfig" }, { "$ref": "#/components/schemas/CategoricalBarRawSqlChartConfig" + }, + { + "$ref": "#/components/schemas/CategoricalBarPromqlChartConfig" } ], "discriminator": { "propertyName": "configType", "mapping": { - "sql": "#/components/schemas/CategoricalBarRawSqlChartConfig" + "sql": "#/components/schemas/CategoricalBarRawSqlChartConfig", + "promql": "#/components/schemas/CategoricalBarPromqlChartConfig" } } }, "TileConfig": { - "description": "Tile chart configuration. displayType is the primary discriminant and determines which variant group applies. For displayTypes that support both builder and Raw SQL modes (line, stacked_bar, stacked_line, table, number, pie, bar), configType is the secondary discriminant: omit it for the builder variant or set it to \"sql\" for the Raw SQL variant. The heatmap, search, event_patterns, and markdown displayTypes only have a builder variant.\n", + "description": "Tile chart configuration. displayType is the primary discriminant and determines which variant group applies. configType is the secondary discriminant: omit it for the builder variant, set it to \"sql\" for the Raw SQL variant, or set it to \"promql\" for the PromQL variant. Line, stacked_bar, stacked_line, table, number, pie, and bar support all three. Heatmap supports builder and PromQL. Search, event_patterns, and markdown only have a builder variant.\n", "oneOf": [ { "$ref": "#/components/schemas/LineChartConfig" @@ -5157,7 +5669,7 @@ }, "PromqlSource": { "type": "object", - "description": "A source backed by a Prometheus-compatible endpoint, queried with PromQL. The referenced connection should be a Prometheus connection (isPrometheusEndpoint set to true).", + "description": "A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true).", "required": [ "name", "kind", @@ -5199,12 +5711,12 @@ }, "connection": { "type": "string", - "description": "ID of the connection used by this source. Should reference a Prometheus-compatible connection.", + "description": "ID of the connection used by this source. Either a ClickHouse connection holding the TimeSeries table, or a Prometheus-compatible connection.", "example": "507f1f77bcf86cd799439012" }, "from": { "$ref": "#/components/schemas/SourceFrom", - "description": "Required by the API for all source kinds; not used when querying a Prometheus endpoint (empty strings are not accepted — use placeholder values such as \"default\")." + "description": "The database and TimeSeries table to query on a ClickHouse connection. Not used for a Prometheus-compatible connection, but still required (empty strings are not accepted — use placeholder values such as \"default\")." }, "querySettings": { "type": "array", @@ -5216,7 +5728,7 @@ }, "timestampValueExpression": { "type": "string", - "description": "Required by the API for all source kinds; not used when querying a Prometheus endpoint.", + "description": "Required by the API for all source kinds; not used by PromQL queries.", "example": "timestamp" } } diff --git a/packages/api/src/routers/external-api/v2/dashboards.ts b/packages/api/src/routers/external-api/v2/dashboards.ts index 276c28c59e..a8ebfb6f2a 100644 --- a/packages/api/src/routers/external-api/v2/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/dashboards.ts @@ -1235,12 +1235,14 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * * HeatmapChartConfig: * description: > - * Heatmap tile. Heatmap is builder-only (no Raw SQL variant). Omit - * heatmapMode (or set it to "distribution") for the distribution - * variant; set heatmapMode to "series" for the series variant. + * Heatmap tile. There is no Raw SQL variant. For the builder variant, + * omit heatmapMode (or set it to "distribution") for the distribution + * heatmap, or set it to "series" for the series heatmap. Set + * configType to "promql" for the PromQL variant. * oneOf: * - $ref: '#/components/schemas/HeatmapDistributionChartConfig' * - $ref: '#/components/schemas/HeatmapSeriesChartConfig' + * - $ref: '#/components/schemas/HeatmapPromqlChartConfig' * * SearchChartConfig: * type: object @@ -1514,44 +1516,412 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * description: Display as a categorical bar chart. * example: "bar" * + * PromqlRangeExpression: + * type: object + * required: + * - expression + * description: A PromQL expression evaluated over the dashboard time range. + * properties: + * expression: + * type: string + * maxLength: 10000 + * description: > + * PromQL expression. Supports dashboard variables and the + * $__interval, $__rate_interval, and $__range macros. + * example: "sum by (job) (rate(http_requests_total[$__rate_interval]))" + * alias: + * type: string + * maxLength: 10000 + * description: Prefixed to every series name this expression produces. + * example: "Requests" + * + * PromqlInstantExpression: + * description: > + * A PromQL expression on a table, number, pie, or bar tile, which can be + * evaluated at a single instant instead of over a range. + * allOf: + * - $ref: '#/components/schemas/PromqlRangeExpression' + * - type: object + * properties: + * queryType: + * type: string + * enum: [range, instant] + * description: > + * Whether to evaluate over the time range or at its end. + * Defaults to "range" when omitted. + * example: "instant" + * + * PromqlReducibleExpression: + * description: > + * A PromQL expression on a number, pie, or bar tile, which reduces each + * series of a range query to a single value. + * allOf: + * - $ref: '#/components/schemas/PromqlInstantExpression' + * - type: object + * properties: + * reducer: + * type: string + * enum: [lastNotNull, min, max, mean, sum, count] + * description: > + * How a range query's samples are reduced to one value. Only + * used when queryType is "range". Defaults to "lastNotNull" + * when omitted. + * example: "max" + * + * PromqlChartConfigBase: + * type: object + * required: + * - configType + * - sourceId + * description: > + * Shared fields for PromQL chart configs. Set configType to "promql" and + * provide sourceId + expressions. The connection is read from the source. + * properties: + * configType: + * type: string + * enum: [promql] + * description: Must be "promql" to use the PromQL chart config variant. + * example: "promql" + * sourceId: + * type: string + * description: ID of the PromQL source to query. Must be a source of kind "promql". + * example: "65f5e4a3b9e77c001a333333" + * granularity: + * type: string + * pattern: '^(\d+ (second|minute|hour|day)|auto)$' + * description: > + * Resolution of range queries, used as the Prometheus step and the + * $__interval macro. Defaults to "auto", which picks one from the + * time range. + * example: "5 minute" + * numberFormat: + * $ref: '#/components/schemas/NumberFormat' + * description: Number formatting options for displayed values. + * + * PromqlTimeChartConfigBase: + * description: Shared fields for PromQL time-series chart configs. + * allOf: + * - $ref: '#/components/schemas/PromqlChartConfigBase' + * - type: object + * required: + * - expressions + * properties: + * expressions: + * type: array + * minItems: 1 + * maxItems: 10 + * description: PromQL expressions to plot. + * items: + * $ref: '#/components/schemas/PromqlRangeExpression' + * legendTemplate: + * type: string + * maxLength: 1024 + * description: > + * Template for series names, using the series' Prometheus labels + * in double braces. + * example: "{{job}} - {{instance}}" + * fillNulls: + * type: boolean + * description: Fill missing time buckets with zero instead of leaving gaps. + * default: true + * alignDateRangeToGranularity: + * type: boolean + * description: Expand date range boundaries to the query granularity interval. + * default: true + * seriesLimit: + * type: integer + * minimum: 0 + * description: > + * Maximum number of series rendered (top-N by value). Omit to use + * the default render cap, set 0 for unlimited, or a positive N to + * keep the top N series. + * example: 5 + * + * LinePromqlChartConfig: + * description: PromQL configuration for a line time-series chart. + * allOf: + * - $ref: '#/components/schemas/PromqlTimeChartConfigBase' + * - type: object + * required: + * - displayType + * properties: + * displayType: + * type: string + * enum: [line] + * description: Display as a line time-series chart. + * example: "line" + * compareToPreviousPeriod: + * type: boolean + * description: Overlay the equivalent previous time period for comparison. + * default: false + * lineInterpolation: + * type: string + * enum: [smooth, linear, step] + * example: "step" + * description: > + * How points are connected. Defaults to "smooth" when omitted. + * + * BarPromqlChartConfig: + * description: PromQL configuration for a stacked-bar time-series chart. + * allOf: + * - $ref: '#/components/schemas/PromqlTimeChartConfigBase' + * - type: object + * required: + * - displayType + * properties: + * displayType: + * type: string + * enum: [stacked_bar] + * description: Display as a stacked-bar time-series chart. + * example: "stacked_bar" + * + * StackedLinePromqlChartConfig: + * description: PromQL configuration for a stacked-line time-series chart. + * allOf: + * - $ref: '#/components/schemas/PromqlTimeChartConfigBase' + * - type: object + * required: + * - displayType + * properties: + * displayType: + * type: string + * enum: [stacked_line] + * description: Display as a stacked-line time-series chart. + * example: "stacked_line" + * lineInterpolation: + * type: string + * enum: [smooth, linear, step] + * example: "step" + * description: > + * How points are connected. Defaults to "linear" when omitted. + * + * TablePromqlChartConfig: + * description: > + * PromQL configuration for a table chart, with one row per series and + * one column per label. + * allOf: + * - $ref: '#/components/schemas/PromqlChartConfigBase' + * - type: object + * required: + * - displayType + * - expressions + * properties: + * displayType: + * type: string + * enum: [table] + * description: Display as a table chart. + * example: "table" + * expressions: + * type: array + * minItems: 1 + * maxItems: 10 + * description: PromQL expressions to tabulate. + * items: + * $ref: '#/components/schemas/PromqlInstantExpression' + * + * NumberPromqlChartConfig: + * description: PromQL configuration for a single big-number chart. + * allOf: + * - $ref: '#/components/schemas/PromqlChartConfigBase' + * - type: object + * required: + * - displayType + * - expressions + * properties: + * displayType: + * type: string + * enum: [number] + * description: Display as a single big-number chart. + * example: "number" + * expressions: + * type: array + * minItems: 1 + * maxItems: 10 + * description: PromQL expressions. The tile displays the first value. + * items: + * $ref: '#/components/schemas/PromqlReducibleExpression' + * color: + * $ref: '#/components/schemas/ChartPaletteToken' + * description: Optional static color applied to the displayed number. + * colorRules: + * type: array + * maxItems: 10 + * description: > + * Ordered conditional color rules evaluated against the displayed + * value (last match wins). Falls back to color, then the default + * text color when no rule matches. + * items: + * $ref: '#/components/schemas/NumberTileColorCondition' + * backgroundChart: + * $ref: '#/components/schemas/BackgroundChart' + * description: > + * Optional trend sparkline drawn behind the number. Only rendered + * when the expression uses a range query. + * + * PiePromqlChartConfig: + * description: PromQL configuration for a pie chart, with one slice per series. + * allOf: + * - $ref: '#/components/schemas/PromqlChartConfigBase' + * - type: object + * required: + * - displayType + * - expressions + * properties: + * displayType: + * type: string + * enum: [pie] + * description: Display as a pie chart. + * example: "pie" + * expressions: + * type: array + * minItems: 1 + * maxItems: 10 + * description: PromQL expressions to plot. + * items: + * $ref: '#/components/schemas/PromqlReducibleExpression' + * legendTemplate: + * type: string + * maxLength: 1024 + * description: > + * Template for slice names, using the series' Prometheus labels + * in double braces. + * example: "{{job}}" + * limit: + * type: integer + * minimum: 0 + * description: > + * Maximum number of slices (top-N by value). Omit to use the + * default cap, set 0 for unlimited, or a positive N to keep the + * top N. + * example: 10 + * + * CategoricalBarPromqlChartConfig: + * description: PromQL configuration for a categorical bar chart, with one bar per series. + * allOf: + * - $ref: '#/components/schemas/PromqlChartConfigBase' + * - type: object + * required: + * - displayType + * - expressions + * properties: + * displayType: + * type: string + * enum: [bar] + * description: Display as a categorical bar chart. + * example: "bar" + * expressions: + * type: array + * minItems: 1 + * maxItems: 10 + * description: PromQL expressions to plot. + * items: + * $ref: '#/components/schemas/PromqlReducibleExpression' + * legendTemplate: + * type: string + * maxLength: 1024 + * description: > + * Template for bar names, using the series' Prometheus labels in + * double braces. + * example: "{{job}}" + * limit: + * type: integer + * minimum: 0 + * description: > + * Maximum number of bars (top-N by value). Omit to use the + * default cap, set 0 for unlimited, or a positive N to keep the + * top N. + * example: 10 + * + * HeatmapPromqlChartConfig: + * description: PromQL configuration for a heatmap. + * allOf: + * - $ref: '#/components/schemas/PromqlChartConfigBase' + * - type: object + * required: + * - displayType + * - expressions + * properties: + * displayType: + * type: string + * enum: [heatmap] + * description: Display as a heatmap. + * example: "heatmap" + * expressions: + * type: array + * minItems: 1 + * maxItems: 10 + * description: PromQL expressions to plot. + * items: + * $ref: '#/components/schemas/PromqlRangeExpression' + * heatmapMode: + * type: string + * enum: [distribution, series, histogram] + * description: > + * "distribution" buckets the values of all series over time, + * "series" draws one row per series, and "histogram" draws one + * row per Prometheus histogram bucket (series need an "le" + * label). Defaults to "distribution" when omitted. + * example: "histogram" + * heatmapScaleType: + * type: string + * enum: [log, linear] + * description: Y-axis scale of a distribution heatmap. + * example: "log" + * legendTemplate: + * type: string + * maxLength: 1024 + * description: > + * Template for row names of a series heatmap, using the series' + * Prometheus labels in double braces. + * example: "{{job}}" + * * LineChartConfig: * description: > * Line chart. Omit configType for the builder variant (requires sourceId * and select). Set configType to "sql" for the Raw SQL variant (requires - * connectionId and sqlTemplate). + * connectionId and sqlTemplate), or to "promql" for the PromQL variant + * (requires sourceId and expressions). * oneOf: * - $ref: '#/components/schemas/LineBuilderChartConfig' * - $ref: '#/components/schemas/LineRawSqlChartConfig' + * - $ref: '#/components/schemas/LinePromqlChartConfig' * discriminator: * propertyName: configType * mapping: * sql: '#/components/schemas/LineRawSqlChartConfig' + * promql: '#/components/schemas/LinePromqlChartConfig' * * BarChartConfig: * description: > * Stacked-bar chart. Omit configType for the builder variant (requires * sourceId and select). Set configType to "sql" for the Raw SQL variant - * (requires connectionId and sqlTemplate). + * (requires connectionId and sqlTemplate), or to "promql" for the PromQL + * variant (requires sourceId and expressions). * oneOf: * - $ref: '#/components/schemas/BarBuilderChartConfig' * - $ref: '#/components/schemas/BarRawSqlChartConfig' + * - $ref: '#/components/schemas/BarPromqlChartConfig' * discriminator: * propertyName: configType * mapping: * sql: '#/components/schemas/BarRawSqlChartConfig' + * promql: '#/components/schemas/BarPromqlChartConfig' * * StackedLineChartConfig: * description: > * Stacked-line chart. Omit configType for the builder variant (requires * sourceId and select). Set configType to "sql" for the Raw SQL variant - * (requires connectionId and sqlTemplate). + * (requires connectionId and sqlTemplate), or to "promql" for the PromQL + * variant (requires sourceId and expressions). * oneOf: * - $ref: '#/components/schemas/StackedLineBuilderChartConfig' * - $ref: '#/components/schemas/StackedLineRawSqlChartConfig' + * - $ref: '#/components/schemas/StackedLinePromqlChartConfig' * discriminator: * propertyName: configType * mapping: * sql: '#/components/schemas/StackedLineRawSqlChartConfig' + * promql: '#/components/schemas/StackedLinePromqlChartConfig' * * OnClickFilterTemplate: * type: object @@ -1710,63 +2080,76 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * description: > * Table chart. Omit configType for the builder variant (requires sourceId * and select). Set configType to "sql" for the Raw SQL variant (requires - * connectionId and sqlTemplate). + * connectionId and sqlTemplate), or to "promql" for the PromQL variant + * (requires sourceId and expressions). * oneOf: * - $ref: '#/components/schemas/TableBuilderChartConfig' * - $ref: '#/components/schemas/TableRawSqlChartConfig' + * - $ref: '#/components/schemas/TablePromqlChartConfig' * discriminator: * propertyName: configType * mapping: * sql: '#/components/schemas/TableRawSqlChartConfig' + * promql: '#/components/schemas/TablePromqlChartConfig' * * NumberChartConfig: * description: > * Single big-number chart. Omit configType for the builder variant * (requires sourceId and select). Set configType to "sql" for the Raw - * SQL variant (requires connectionId and sqlTemplate). + * SQL variant (requires connectionId and sqlTemplate), or to "promql" + * for the PromQL variant (requires sourceId and expressions). * oneOf: * - $ref: '#/components/schemas/NumberBuilderChartConfig' * - $ref: '#/components/schemas/NumberRawSqlChartConfig' + * - $ref: '#/components/schemas/NumberPromqlChartConfig' * discriminator: * propertyName: configType * mapping: * sql: '#/components/schemas/NumberRawSqlChartConfig' + * promql: '#/components/schemas/NumberPromqlChartConfig' * * PieChartConfig: * description: > * Pie chart. Omit configType for the builder variant (requires sourceId * and select). Set configType to "sql" for the Raw SQL variant (requires - * connectionId and sqlTemplate). + * connectionId and sqlTemplate), or to "promql" for the PromQL variant + * (requires sourceId and expressions). * oneOf: * - $ref: '#/components/schemas/PieBuilderChartConfig' * - $ref: '#/components/schemas/PieRawSqlChartConfig' + * - $ref: '#/components/schemas/PiePromqlChartConfig' * discriminator: * propertyName: configType * mapping: * sql: '#/components/schemas/PieRawSqlChartConfig' + * promql: '#/components/schemas/PiePromqlChartConfig' * * CategoricalBarChartConfig: * description: > * Categorical bar chart (one bar per group value; not a time series). * Omit configType for the builder variant (requires sourceId and * select). Set configType to "sql" for the Raw SQL variant (requires - * connectionId and sqlTemplate). + * connectionId and sqlTemplate), or to "promql" for the PromQL variant + * (requires sourceId and expressions). * oneOf: * - $ref: '#/components/schemas/CategoricalBarBuilderChartConfig' * - $ref: '#/components/schemas/CategoricalBarRawSqlChartConfig' + * - $ref: '#/components/schemas/CategoricalBarPromqlChartConfig' * discriminator: * propertyName: configType * mapping: * sql: '#/components/schemas/CategoricalBarRawSqlChartConfig' + * promql: '#/components/schemas/CategoricalBarPromqlChartConfig' * * TileConfig: * description: > * Tile chart configuration. displayType is the primary discriminant and - * determines which variant group applies. For displayTypes that support - * both builder and Raw SQL modes (line, stacked_bar, stacked_line, table, - * number, pie, bar), configType is the secondary discriminant: omit it for - * the builder variant or set it to "sql" for the Raw SQL variant. The heatmap, - * search, event_patterns, and markdown displayTypes only have a builder variant. + * determines which variant group applies. configType is the secondary + * discriminant: omit it for the builder variant, set it to "sql" for the + * Raw SQL variant, or set it to "promql" for the PromQL variant. Line, + * stacked_bar, stacked_line, table, number, pie, and bar support all + * three. Heatmap supports builder and PromQL. Search, event_patterns, + * and markdown only have a builder variant. * oneOf: * - $ref: '#/components/schemas/LineChartConfig' * - $ref: '#/components/schemas/BarChartConfig' diff --git a/packages/api/src/routers/external-api/v2/sources.ts b/packages/api/src/routers/external-api/v2/sources.ts index 38c9d2b2f5..ba765e0a2e 100644 --- a/packages/api/src/routers/external-api/v2/sources.ts +++ b/packages/api/src/routers/external-api/v2/sources.ts @@ -847,7 +847,7 @@ function formatExternalSource(source: SourceDocument) { * example: ResourceAttributes * PromqlSource: * type: object - * description: A source backed by a Prometheus-compatible endpoint, queried with PromQL. The referenced connection should be a Prometheus connection (isPrometheusEndpoint set to true). + * description: A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true). * required: * - name * - kind @@ -881,11 +881,11 @@ function formatExternalSource(source: SourceDocument) { * example: promql * connection: * type: string - * description: ID of the connection used by this source. Should reference a Prometheus-compatible connection. + * description: ID of the connection used by this source. Either a ClickHouse connection holding the TimeSeries table, or a Prometheus-compatible connection. * example: 507f1f77bcf86cd799439012 * from: * $ref: '#/components/schemas/SourceFrom' - * description: Required by the API for all source kinds; not used when querying a Prometheus endpoint (empty strings are not accepted — use placeholder values such as "default"). + * description: The database and TimeSeries table to query on a ClickHouse connection. Not used for a Prometheus-compatible connection, but still required (empty strings are not accepted — use placeholder values such as "default"). * querySettings: * type: array * description: Optional ClickHouse query settings applied when querying this source. @@ -894,7 +894,7 @@ function formatExternalSource(source: SourceDocument) { * nullable: true * timestampValueExpression: * type: string - * description: Required by the API for all source kinds; not used when querying a Prometheus endpoint. + * description: Required by the API for all source kinds; not used by PromQL queries. * example: timestamp * Source: * oneOf: From fd664b3ee82d7e886b06beece84ef97c9e304956 Mon Sep 17 00:00:00 2001 From: Karl Power Date: Tue, 20 Oct 2026 16:40:28 +0200 Subject: [PATCH 2/6] docs: Correct PromQL tile expression, table, and reducer descriptions Only line and stacked tiles query every expression; other display types query the first. Tables have one row per sample, and reducers also apply to instant queries. --- packages/api/openapi.json | 14 ++++---- .../src/routers/external-api/v2/dashboards.ts | 33 +++++++++++++------ 2 files changed, 30 insertions(+), 17 deletions(-) diff --git a/packages/api/openapi.json b/packages/api/openapi.json index 967fd47119..876ca2c4b9 100644 --- a/packages/api/openapi.json +++ b/packages/api/openapi.json @@ -2910,7 +2910,7 @@ "sum", "count" ], - "description": "How a range query's samples are reduced to one value. Only used when queryType is \"range\". Defaults to \"lastNotNull\" when omitted.\n", + "description": "How each series' samples are reduced to one value. Defaults to \"lastNotNull\" when omitted. It also applies to instant queries, where each series has a single sample, so e.g. \"count\" turns every value into 1.\n", "example": "max" } } @@ -3095,7 +3095,7 @@ ] }, "TablePromqlChartConfig": { - "description": "PromQL configuration for a table chart, with one row per series and one column per label.\n", + "description": "PromQL configuration for a table chart, with one row per sample: a column per label, a Value column, and a Timestamp column when the expression is a range query. An instant query gives one row per series.\n", "allOf": [ { "$ref": "#/components/schemas/PromqlChartConfigBase" @@ -3119,7 +3119,7 @@ "type": "array", "minItems": 1, "maxItems": 10, - "description": "PromQL expressions to tabulate.", + "description": "PromQL expressions. Only the first is queried; the rest are kept but ignored.\n", "items": { "$ref": "#/components/schemas/PromqlInstantExpression" } @@ -3153,7 +3153,7 @@ "type": "array", "minItems": 1, "maxItems": 10, - "description": "PromQL expressions. The tile displays the first value.", + "description": "PromQL expressions. Only the first is queried; the rest are kept but ignored. The tile displays the first value.\n", "items": { "$ref": "#/components/schemas/PromqlReducibleExpression" } @@ -3203,7 +3203,7 @@ "type": "array", "minItems": 1, "maxItems": 10, - "description": "PromQL expressions to plot.", + "description": "PromQL expressions. Only the first is queried; the rest are kept but ignored.\n", "items": { "$ref": "#/components/schemas/PromqlReducibleExpression" } @@ -3249,7 +3249,7 @@ "type": "array", "minItems": 1, "maxItems": 10, - "description": "PromQL expressions to plot.", + "description": "PromQL expressions. Only the first is queried; the rest are kept but ignored.\n", "items": { "$ref": "#/components/schemas/PromqlReducibleExpression" } @@ -3295,7 +3295,7 @@ "type": "array", "minItems": 1, "maxItems": 10, - "description": "PromQL expressions to plot.", + "description": "PromQL expressions. Only the first is queried; the rest are kept but ignored.\n", "items": { "$ref": "#/components/schemas/PromqlRangeExpression" } diff --git a/packages/api/src/routers/external-api/v2/dashboards.ts b/packages/api/src/routers/external-api/v2/dashboards.ts index a8ebfb6f2a..2619009ba3 100644 --- a/packages/api/src/routers/external-api/v2/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/dashboards.ts @@ -1563,9 +1563,10 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * type: string * enum: [lastNotNull, min, max, mean, sum, count] * description: > - * How a range query's samples are reduced to one value. Only - * used when queryType is "range". Defaults to "lastNotNull" - * when omitted. + * How each series' samples are reduced to one value. Defaults + * to "lastNotNull" when omitted. It also applies to instant + * queries, where each series has a single sample, so e.g. + * "count" turns every value into 1. * example: "max" * * PromqlChartConfigBase: @@ -1697,8 +1698,10 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * * TablePromqlChartConfig: * description: > - * PromQL configuration for a table chart, with one row per series and - * one column per label. + * PromQL configuration for a table chart, with one row per sample: a + * column per label, a Value column, and a Timestamp column when the + * expression is a range query. An instant query gives one row per + * series. * allOf: * - $ref: '#/components/schemas/PromqlChartConfigBase' * - type: object @@ -1715,7 +1718,9 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * type: array * minItems: 1 * maxItems: 10 - * description: PromQL expressions to tabulate. + * description: > + * PromQL expressions. Only the first is queried; the rest are + * kept but ignored. * items: * $ref: '#/components/schemas/PromqlInstantExpression' * @@ -1737,7 +1742,9 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * type: array * minItems: 1 * maxItems: 10 - * description: PromQL expressions. The tile displays the first value. + * description: > + * PromQL expressions. Only the first is queried; the rest are + * kept but ignored. The tile displays the first value. * items: * $ref: '#/components/schemas/PromqlReducibleExpression' * color: @@ -1776,7 +1783,9 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * type: array * minItems: 1 * maxItems: 10 - * description: PromQL expressions to plot. + * description: > + * PromQL expressions. Only the first is queried; the rest are + * kept but ignored. * items: * $ref: '#/components/schemas/PromqlReducibleExpression' * legendTemplate: @@ -1813,7 +1822,9 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * type: array * minItems: 1 * maxItems: 10 - * description: PromQL expressions to plot. + * description: > + * PromQL expressions. Only the first is queried; the rest are + * kept but ignored. * items: * $ref: '#/components/schemas/PromqlReducibleExpression' * legendTemplate: @@ -1850,7 +1861,9 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * type: array * minItems: 1 * maxItems: 10 - * description: PromQL expressions to plot. + * description: > + * PromQL expressions. Only the first is queried; the rest are + * kept but ignored. * items: * $ref: '#/components/schemas/PromqlRangeExpression' * heatmapMode: From db1bc796a84591a576bc167fcb9a1a5f368fd345 Mon Sep 17 00:00:00 2001 From: Karl Power Date: Tue, 20 Oct 2026 17:08:36 +0200 Subject: [PATCH 3/6] docs: Document the 500-entry cap on PromQL pie and bar limits --- packages/api/openapi.json | 4 ++-- packages/api/src/routers/external-api/v2/dashboards.ts | 10 ++++------ 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/packages/api/openapi.json b/packages/api/openapi.json index 876ca2c4b9..14d41bfc8e 100644 --- a/packages/api/openapi.json +++ b/packages/api/openapi.json @@ -3217,7 +3217,7 @@ "limit": { "type": "integer", "minimum": 0, - "description": "Maximum number of slices (top-N by value). Omit to use the default cap, set 0 for unlimited, or a positive N to keep the top N.\n", + "description": "Maximum number of slices (top-N by value), at most 500. Omit or set 0 to show up to 500.\n", "example": 10 } } @@ -3263,7 +3263,7 @@ "limit": { "type": "integer", "minimum": 0, - "description": "Maximum number of bars (top-N by value). Omit to use the default cap, set 0 for unlimited, or a positive N to keep the top N.\n", + "description": "Maximum number of bars (top-N by value), at most 500. Omit or set 0 to show up to 500.\n", "example": 10 } } diff --git a/packages/api/src/routers/external-api/v2/dashboards.ts b/packages/api/src/routers/external-api/v2/dashboards.ts index 2619009ba3..f52189540f 100644 --- a/packages/api/src/routers/external-api/v2/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/dashboards.ts @@ -1799,9 +1799,8 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * type: integer * minimum: 0 * description: > - * Maximum number of slices (top-N by value). Omit to use the - * default cap, set 0 for unlimited, or a positive N to keep the - * top N. + * Maximum number of slices (top-N by value), at most 500. Omit + * or set 0 to show up to 500. * example: 10 * * CategoricalBarPromqlChartConfig: @@ -1838,9 +1837,8 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * type: integer * minimum: 0 * description: > - * Maximum number of bars (top-N by value). Omit to use the - * default cap, set 0 for unlimited, or a positive N to keep the - * top N. + * Maximum number of bars (top-N by value), at most 500. Omit or + * set 0 to show up to 500. * example: 10 * * HeatmapPromqlChartConfig: From 774b13b9617da015aecd2279a1d06a67c508f695 Mon Sep 17 00:00:00 2001 From: Karl Power Date: Wed, 21 Oct 2026 09:12:13 +0200 Subject: [PATCH 4/6] docs: Add a configType discriminator to the heatmap tile schema --- packages/api/openapi.json | 8 +++++++- packages/api/src/routers/external-api/v2/dashboards.ts | 4 ++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/packages/api/openapi.json b/packages/api/openapi.json index 14d41bfc8e..63e1af054e 100644 --- a/packages/api/openapi.json +++ b/packages/api/openapi.json @@ -2457,7 +2457,13 @@ { "$ref": "#/components/schemas/HeatmapPromqlChartConfig" } - ] + ], + "discriminator": { + "propertyName": "configType", + "mapping": { + "promql": "#/components/schemas/HeatmapPromqlChartConfig" + } + } }, "SearchChartConfig": { "type": "object", diff --git a/packages/api/src/routers/external-api/v2/dashboards.ts b/packages/api/src/routers/external-api/v2/dashboards.ts index f52189540f..a696eb84ff 100644 --- a/packages/api/src/routers/external-api/v2/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/dashboards.ts @@ -1243,6 +1243,10 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * - $ref: '#/components/schemas/HeatmapDistributionChartConfig' * - $ref: '#/components/schemas/HeatmapSeriesChartConfig' * - $ref: '#/components/schemas/HeatmapPromqlChartConfig' + * discriminator: + * propertyName: configType + * mapping: + * promql: '#/components/schemas/HeatmapPromqlChartConfig' * * SearchChartConfig: * type: object From 361ab469ceb71a1a66ff8bec583701d435e844b1 Mon Sep 17 00:00:00 2001 From: Karl Power Date: Thu, 22 Oct 2026 14:23:34 +0200 Subject: [PATCH 5/6] docs: Note that PromQL sources, tiles and filters are a preview feature --- packages/api/openapi.json | 6 +++--- packages/api/src/routers/external-api/v2/dashboards.ts | 6 +++++- packages/api/src/routers/external-api/v2/sources.ts | 2 +- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/packages/api/openapi.json b/packages/api/openapi.json index 63e1af054e..dda1820d3b 100644 --- a/packages/api/openapi.json +++ b/packages/api/openapi.json @@ -2929,7 +2929,7 @@ "configType", "sourceId" ], - "description": "Shared fields for PromQL chart configs. Set configType to \"promql\" and provide sourceId + expressions. The connection is read from the source.\n", + "description": "Shared fields for PromQL chart configs. Set configType to \"promql\" and provide sourceId + expressions. The connection is read from the source. PromQL is a preview feature and must be enabled on the deployment (ENABLE_PROMQL) before PromQL tiles can be queried.\n", "properties": { "configType": { "type": "string", @@ -4171,7 +4171,7 @@ }, "PrometheusLabelFilterInput": { "type": "object", - "description": "A filter whose dropdown lists the values for a Prometheus label,\nread from a PromQL source over the dashboard's time range.\nSupports variable mode only.\n", + "description": "A filter whose dropdown lists the values for a Prometheus label,\nread from a PromQL source over the dashboard's time range.\nSupports variable mode only. PromQL is a preview feature and must be\nenabled on the deployment (ENABLE_PROMQL) before these filters can\nlist values.\n", "required": [ "type", "name", @@ -5675,7 +5675,7 @@ }, "PromqlSource": { "type": "object", - "description": "A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true).", + "description": "A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true). PromQL is a preview feature and must be enabled on the deployment (ENABLE_PROMQL) before PromQL sources can be queried.", "required": [ "name", "kind", diff --git a/packages/api/src/routers/external-api/v2/dashboards.ts b/packages/api/src/routers/external-api/v2/dashboards.ts index a696eb84ff..77d3b31361 100644 --- a/packages/api/src/routers/external-api/v2/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/dashboards.ts @@ -1581,6 +1581,8 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * description: > * Shared fields for PromQL chart configs. Set configType to "promql" and * provide sourceId + expressions. The connection is read from the source. + * PromQL is a preview feature and must be enabled on the deployment + * (ENABLE_PROMQL) before PromQL tiles can be queried. * properties: * configType: * type: string @@ -2590,7 +2592,9 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * description: | * A filter whose dropdown lists the values for a Prometheus label, * read from a PromQL source over the dashboard's time range. - * Supports variable mode only. + * Supports variable mode only. PromQL is a preview feature and must be + * enabled on the deployment (ENABLE_PROMQL) before these filters can + * list values. * required: * - type * - name diff --git a/packages/api/src/routers/external-api/v2/sources.ts b/packages/api/src/routers/external-api/v2/sources.ts index ba765e0a2e..1692a1916c 100644 --- a/packages/api/src/routers/external-api/v2/sources.ts +++ b/packages/api/src/routers/external-api/v2/sources.ts @@ -847,7 +847,7 @@ function formatExternalSource(source: SourceDocument) { * example: ResourceAttributes * PromqlSource: * type: object - * description: A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true). + * description: A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true). PromQL is a preview feature and must be enabled on the deployment (ENABLE_PROMQL) before PromQL sources can be queried. * required: * - name * - kind From 72f7e7c75baa0da76adc5ff2b4626754f46f8366 Mon Sep 17 00:00:00 2001 From: Karl Power Date: Thu, 22 Oct 2026 14:27:27 +0200 Subject: [PATCH 6/6] fix: Reject PromQL sources in the external API when PromQL is disabled --- .changeset/external-api-promql-source-gate.md | 7 +++ packages/api/openapi.json | 2 +- .../__tests__/sources-crud.int.test.ts | 49 +++++++++++++++++++ .../src/routers/external-api/v2/sources.ts | 20 +++++++- 4 files changed, 76 insertions(+), 2 deletions(-) create mode 100644 .changeset/external-api-promql-source-gate.md diff --git a/.changeset/external-api-promql-source-gate.md b/.changeset/external-api-promql-source-gate.md new file mode 100644 index 0000000000..c721f79d70 --- /dev/null +++ b/.changeset/external-api-promql-source-gate.md @@ -0,0 +1,7 @@ +--- +'@hyperdx/api': patch +--- + +fix: Reject creating or updating PromQL sources through the external API when PromQL is not enabled + +`POST` and `PUT /api/v2/sources` now return a 400 for `kind: "promql"` unless `ENABLE_PROMQL` is set, since PromQL sources cannot be queried without it. diff --git a/packages/api/openapi.json b/packages/api/openapi.json index dda1820d3b..f6ea5912f6 100644 --- a/packages/api/openapi.json +++ b/packages/api/openapi.json @@ -5675,7 +5675,7 @@ }, "PromqlSource": { "type": "object", - "description": "A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true). PromQL is a preview feature and must be enabled on the deployment (ENABLE_PROMQL) before PromQL sources can be queried.", + "description": "A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true). PromQL is a preview feature, so creating or updating a PromQL source is rejected unless it is enabled on the deployment (ENABLE_PROMQL).", "required": [ "name", "kind", diff --git a/packages/api/src/routers/external-api/__tests__/sources-crud.int.test.ts b/packages/api/src/routers/external-api/__tests__/sources-crud.int.test.ts index 360eedb232..f7286a13c2 100644 --- a/packages/api/src/routers/external-api/__tests__/sources-crud.int.test.ts +++ b/packages/api/src/routers/external-api/__tests__/sources-crud.int.test.ts @@ -285,6 +285,55 @@ describe('External API v2 Sources CRUD', () => { }); }); + describe('PromQL sources with PromQL disabled', () => { + const promqlSourceBody = () => ({ + kind: SourceKind.Promql, + name: 'Prometheus Metrics', + from: { databaseName: 'default', tableName: 'default' }, + timestampValueExpression: 'timestamp', + connection: connection._id.toString(), + }); + + beforeEach(() => { + jest.replaceProperty(config, 'IS_PROMQL_ENABLED', false); + }); + + afterEach(() => { + jest.restoreAllMocks(); + }); + + it('rejects creating a PromQL source', async () => { + const response = await authRequest('post', BASE_URL) + .send(promqlSourceBody()) + .expect(400); + + expect(response.body.message).toBe( + 'PromQL is not enabled on this deployment', + ); + expect(await Source.findOne({ team: team._id })).toBeNull(); + }); + + it('rejects updating a source to PromQL', async () => { + const logSource = await LogSource.create({ + ...logSourceBody(), + team: team._id, + }); + + const response = await authRequest('put', `${BASE_URL}/${logSource._id}`) + .send(promqlSourceBody()) + .expect(400); + + expect(response.body.message).toBe( + 'PromQL is not enabled on this deployment', + ); + expect((await Source.findById(logSource._id))!.kind).toBe(SourceKind.Log); + }); + + it('still creates other source kinds', async () => { + await authRequest('post', BASE_URL).send(logSourceBody()).expect(200); + }); + }); + describe('PUT /api/v2/sources/:id', () => { it('should return 401 when user is not authenticated', async () => { await request(server.getHttpServer()) diff --git a/packages/api/src/routers/external-api/v2/sources.ts b/packages/api/src/routers/external-api/v2/sources.ts index 1692a1916c..fb66b16915 100644 --- a/packages/api/src/routers/external-api/v2/sources.ts +++ b/packages/api/src/routers/external-api/v2/sources.ts @@ -7,6 +7,7 @@ import { import express from 'express'; import { z } from 'zod'; +import * as config from '@/config'; import { validateConnectionId } from '@/controllers/connection'; import { createSource, @@ -111,6 +112,21 @@ async function requireValidConnectionId( } } +// PromQL is a preview feature: without it enabled, a PromQL source cannot be +// queried. Runs after body validation so req.body is the parsed shape. +function rejectPromqlSourceWhenDisabled( + req: express.Request, + res: express.Response, + next: express.NextFunction, +) { + if (req.body?.kind === SourceKind.Promql && !config.IS_PROMQL_ENABLED) { + return res + .status(400) + .json({ message: 'PromQL is not enabled on this deployment' }); + } + next(); +} + function mapSourceToExternalSource(source: TSource): TSource { if (!('materializedViews' in source)) return source; @@ -847,7 +863,7 @@ function formatExternalSource(source: SourceDocument) { * example: ResourceAttributes * PromqlSource: * type: object - * description: A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true). PromQL is a preview feature and must be enabled on the deployment (ENABLE_PROMQL) before PromQL sources can be queried. + * description: A source queried with PromQL. It reads either a ClickHouse TimeSeries table (through a ClickHouse connection) or a Prometheus-compatible endpoint (through a connection with isPrometheusEndpoint set to true). PromQL is a preview feature, so creating or updating a PromQL source is rejected unless it is enabled on the deployment (ENABLE_PROMQL). * required: * - name * - kind @@ -1115,6 +1131,7 @@ router.post( validateRequest({ body: SourceSchemaNoId, }), + rejectPromqlSourceWhenDisabled, requireValidConnectionId, async (req, res, next) => { try { @@ -1220,6 +1237,7 @@ router.put( }), body: SourceSchemaNoId, }), + rejectPromqlSourceWhenDisabled, requireValidConnectionId, async (req, res, next) => { try {