Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(metrics): substitute dashboard variables in metrics queries (#118633)

Frank Hamand503b8d2962f6
diff --git a/frontend/src/queries/schema.json b/frontend/src/queries/schema.json
index 016a1609f0f3..191e52fa28d0 100644
--- a/frontend/src/queries/schema.json
+++ b/frontend/src/queries/schema.json
@@ -18746,6 +18746,20 @@
],
"description": "Metric label matchers ANDed into every metrics tile. Other tiles ignore them."
},
+ "metricVariables": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/definitions/MetricsDashboardVariable"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Variables that metrics tiles refer to as `$name`. Other tiles ignore them."
+ },
"properties": {
"anyOf": [
{
@@ -38947,6 +38961,89 @@
"enum": ["linear", "log"],
"type": "string"
},
+ "MetricsDashboardVariable": {
+ "additionalProperties": false,
+ "description": "A Grafana-style dashboard variable. Metrics tiles refer to it as `$name`, `${name}` or `${name:format}`.",
+ "properties": {
+ "allValue": {
+ "description": "The text that All puts in a PromQL query. `.*` when it is empty.",
+ "type": ["string", "null"]
+ },
+ "current": {
+ "anyOf": [
+ {
+ "$ref": "#/definitions/MetricsDashboardVariableSelection"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "customValues": {
+ "anyOf": [
+ {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The options when `source` is `custom`."
+ },
+ "includeAll": {
+ "type": ["boolean", "null"]
+ },
+ "label": {
+ "description": "Shown in the dashboard filter bar. The name is shown when it is empty.",
+ "type": ["string", "null"]
+ },
+ "multi": {
+ "type": ["boolean", "null"]
+ },
+ "name": {
+ "description": "Letters, digits and underscores. Tiles refer to it as `$name`.",
+ "type": "string"
+ },
+ "query": {
+ "description": "The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column.",
+ "type": ["string", "null"]
+ },
+ "regex": {
+ "description": "RE2 pattern that options must match. When it has a capture group, the option is the first group.",
+ "type": ["string", "null"]
+ },
+ "source": {
+ "$ref": "#/definitions/MetricsDashboardVariableSource"
+ }
+ },
+ "required": ["name", "source"],
+ "type": "object"
+ },
+ "MetricsDashboardVariableSelection": {
+ "additionalProperties": false,
+ "properties": {
+ "all": {
+ "type": "boolean"
+ },
+ "values": {
+ "description": "The selected values. Empty when `all` is true: All stands for every option of the variable.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": ["values"],
+ "type": "object"
+ },
+ "MetricsDashboardVariableSource": {
+ "description": "Where a metrics dashboard variable gets its options.",
+ "enum": ["custom", "promql", "sql", "textbox"],
+ "type": "string"
+ },
"MetricsDisplaySettings": {
"additionalProperties": false,
"description": "Presentation only. The query engine never reads this, and it's stripped from the result cache key, so changing any of it re-renders without re-running the query.",
@@ -39053,6 +39150,13 @@
"description": "UCUM unit for the y-axis bounds, e.g. \"s\", \"ms\". Presentation only.",
"type": "string"
},
+ "variables": {
+ "additionalProperties": {
+ "$ref": "#/definitions/MetricsVariableValue"
+ },
+ "description": "Values of the dashboard variables that the filters refer to as `$name`.",
+ "type": "object"
+ },
"version": {
"description": "version of the node, used for schema migrations",
"type": "number"
@@ -39207,6 +39311,13 @@
"tags": {
"$ref": "#/definitions/QueryLogTags"
},
+ "variables": {
+ "additionalProperties": {
+ "$ref": "#/definitions/MetricsVariableValue"
+ },
+ "description": "Values of the dashboard variables that the PromQL, SQL or filters refer to as `$name`.",
+ "type": "object"
+ },
"version": {
"description": "version of the node, used for schema migrations",
"type": "number"
@@ -39437,6 +39548,27 @@
"required": ["value", "color"],
"type": "object"
},
+ "MetricsVariableValue": {
+ "additionalProperties": false,
+ "description": "The value of one variable in a metrics query, set from the dashboard that shows the query.",
+ "properties": {
+ "all": {
+ "description": "True when the variable is set to All. PromQL gets `allValue` or `.*`, builder filters drop the filter, and SQL gets `values`.",
+ "type": "boolean"
+ },
+ "allValue": {
+ "type": ["string", "null"]
+ },
+ "values": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": ["values"],
+ "type": "object"
+ },
"MetricsYAxisSettings": {
"additionalProperties": false,
"properties": {
diff --git a/frontend/src/queries/schema/schema-general.ts b/frontend/src/queries/schema/schema-general.ts
index f1b8500458cd..cc7a094e88cb 100644
--- a/frontend/src/queries/schema/schema-general.ts
+++ b/frontend/src/queries/schema/schema-general.ts
@@ -4895,6 +4895,46 @@ export interface MetricsQueryFilter {
scope?: MetricsAttributeScope
}
+/** Where a metrics dashboard variable gets its options. */
+export type MetricsDashboardVariableSource = 'custom' | 'promql' | 'sql' | 'textbox'
+
+export interface MetricsDashboardVariableSelection {
+ /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
+ values: string[]
+ all?: boolean
+}
+
+/** The value of one variable in a metrics query, set from the dashboard that shows the query. */
+export interface MetricsVariableValue {
+ values: string[]
+ /** True when the variable is set to All. PromQL gets `allValue` or `.*`, builder filters drop the
+ * filter, and SQL gets `values`. */
+ all?: boolean
+ allValue?: string | null
+}
+
+/** A Grafana-style dashboard variable. Metrics tiles refer to it as `$name`, `${name}` or `${name:format}`. */
+export interface MetricsDashboardVariable {
+ /** Letters, digits and underscores. Tiles refer to it as `$name`. */
+ name: string
+ /** Shown in the dashboard filter bar. The name is shown when it is empty. */
+ label?: string | null
+ source: MetricsDashboardVariableSource
+ /** The options when `source` is `custom`. */
+ customValues?: string[] | null
+ /** The options query when `source` is `promql` or `sql`. It can refer to other variables.
+ * PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`,
+ * `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
+ query?: string | null
+ /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
+ regex?: string | null
+ multi?: boolean | null
+ includeAll?: boolean | null
+ /** The text that All puts in a PromQL query. `.*` when it is empty. */
+ allValue?: string | null
+ current?: MetricsDashboardVariableSelection | null
+}
+
export interface MetricsQueryGroupBy {
key: string
scope?: MetricsAttributeScope
@@ -4956,6 +4996,8 @@ export interface MetricsHistogramQuery extends DataNode<MetricsHistogramQueryRes
interval?: string
/** UCUM unit for the y-axis bounds, e.g. "s", "ms". Presentation only. */
unit?: string
+ /** Values of the dashboard variables that the filters refer to as `$name`. */
+ variables?: Record<string, MetricsVariableValue>
}
export interface MetricsHistogramQueryResponse extends AnalyticsQueryResponseBase {
@@ -5057,6 +5099,8 @@ export interface MetricsQuery extends DataNode<MetricsQueryResponse> {
formula?: string
/** Chart presentation. A node without it renders as a line chart. */
display?: MetricsDisplaySettings
+ /** Values of the dashboard variables that the PromQL, SQL or filters refer to as `$name`. */
+ variables?: Record<string, MetricsVariableValue>
}
export interface SessionEventsItem {
@@ -6839,6 +6883,8 @@ export interface DashboardFilter {
compareFilter?: CompareFilter | null
/** Metric label matchers ANDed into every metrics tile. Other tiles ignore them. */
metricFilters?: MetricsQueryFilter[] | null
+ /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
+ metricVariables?: MetricsDashboardVariable[] | null
}
export interface TileFilters {
diff --git a/posthog/schema.py b/posthog/schema.py
index cdf83e7ad33b..d58b15a2541c 100644
--- a/posthog/schema.py
+++ b/posthog/schema.py
@@ -214,6 +214,7 @@ from posthog.schema_enums import (
MetricsAggregation as MetricsAggregation,
MetricsAttributeScope as MetricsAttributeScope,
MetricsAxisScale as MetricsAxisScale,
+ MetricsDashboardVariableSource as MetricsDashboardVariableSource,
MetricsDisplayType as MetricsDisplayType,
MetricsFilterOp as MetricsFilterOp,
MetricsNullMode as MetricsNullMode,
@@ -2705,6 +2706,17 @@ class MetricsAlertConfig(BaseModel):
type: Literal["MetricsAlertConfig"] = "MetricsAlertConfig"
+class MetricsDashboardVariableSelection(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ all: bool | None = None
+ values: list[str] = Field(
+ ...,
+ description=("The selected values. Empty when `all` is true: All stands for every option of the variable."),
+ )
+
+
class MetricsQueryFilter(BaseModel):
model_config = ConfigDict(
extra="forbid",
@@ -2772,6 +2784,21 @@ class MetricsThreshold(BaseModel):
)
+class MetricsVariableValue(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ all: bool | None = Field(
+ default=None,
+ description=(
+ "True when the variable is set to All. PromQL gets `allValue` or `.*`,"
+ " builder filters drop the filter, and SQL gets `values`."
+ ),
+ )
+ allValue: str | None = None
+ values: list[str]
+
+
class MetricsYAxisSettings(BaseModel):
model_config = ConfigDict(
extra="forbid",
@@ -7013,6 +7040,44 @@ class MetricPropertyFilter(BaseModel):
value: list[str | float | bool] | str | float | bool | None = None
+class MetricsDashboardVariable(BaseModel):
+ model_config = ConfigDict(
+ extra="forbid",
+ )
+ allValue: str | None = Field(
+ default=None,
+ description="The text that All puts in a PromQL query. `.*` when it is empty.",
+ )
+ current: MetricsDashboardVariableSelection | None = None
+ customValues: list[str] | None = Field(default=None, description="The options when `source` is `custom`.")
+ includeAll: bool | None = None
+ label: str | None = Field(
+ default=None,
+ description=("Shown in the dashboard filter bar. The name is shown when it is empty."),
+ )
+ multi: bool | None = None
+ name: str = Field(
+ ...,
+ description="Letters, digits and underscores. Tiles refer to it as `$name`.",
+ )
+ query: str | None = Field(
+ default=None,
+ description=(
+ "The options query when `source` is `promql` or `sql`. It can refer to"
+ " other variables. PromQL supports `label_values(label)`,"
+ " `label_values(selector, label)`, `label_names()`, `metrics(regex)` and"
+ " `query_result(expr)`. SQL returns the options in its first column."
+ ),
+ )
+ regex: str | None = Field(
+ default=None,
+ description=(
+ "RE2 pattern that options must match. When it has a capture group, the option is the first group."
+ ),
+ )
+ source: MetricsDashboardVariableSource
+
+
class MetricsDisplaySettings(BaseModel):
model_config = ConfigDict(
extra="forbid",
@@ -27633,6 +27698,10 @@ class DashboardFilter(BaseModel):
default=None,
description=("Metric label matchers ANDed into every metrics tile. Other tiles ignore them."),
)
+ metricVariables: list[MetricsDashboardVariable] | None = Field(
+ default=None,
+ description=("Variables that metrics tiles refer to as `$name`. Other tiles ignore them."),
+ )
properties: list[AnyPropertyFilterDiscriminated] | None = None
@@ -29341,6 +29410,10 @@ class MetricsHistogramQuery(BaseModel):
default=None,
description=('UCUM unit for the y-axis bounds, e.g. "s", "ms". Presentation only.'),
)
+ variables: dict[str, MetricsVariableValue] | None = Field(
+ default=None,
+ description=("Values of the dashboard variables that the filters refer to as `$name`."),
+ )
version: float | None = Field(default=None, description="version of the node, used for schema migrations")
@@ -29389,6 +29462,10 @@ class MetricsQuery(BaseModel):
),
)
tags: QueryLogTags | None = None
+ variables: dict[str, MetricsVariableValue] | None = Field(
+ default=None,
+ description=("Values of the dashboard variables that the PromQL, SQL or filters refer to as `$name`."),
+ )
version: float | None = Field(default=None, description="version of the node, used for schema migrations")
diff --git a/posthog/schema_enums.py b/posthog/schema_enums.py
index 08b86b72bdc2..9adcddb9a478 100644
--- a/posthog/schema_enums.py
+++ b/posthog/schema_enums.py
@@ -2226,6 +2226,13 @@ class MetricsAxisScale(StrEnum):
LOG = "log"
+class MetricsDashboardVariableSource(StrEnum):
+ CUSTOM = "custom"
+ PROMQL = "promql"
+ SQL = "sql"
+ TEXTBOX = "textbox"
+
+
class MetricsDisplayType(StrEnum):
LINE = "line"
AREA = "area"
diff --git a/products/customer_analytics/frontend/generated/api.schemas.ts b/products/customer_analytics/frontend/generated/api.schemas.ts
index 55b5138c7a1b..8d174572ed54 100644
--- a/products/customer_analytics/frontend/generated/api.schemas.ts
+++ b/products/customer_analytics/frontend/generated/api.schemas.ts
@@ -2203,6 +2203,41 @@ export interface MetricsQueryFilterApi {
value: string
}
+export interface MetricsDashboardVariableSelectionApi {
+ all?: boolean | null
+ /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
+ values: string[]
+}
+
+export type MetricsDashboardVariableSourceApi =
+ (typeof MetricsDashboardVariableSourceApi)[keyof typeof MetricsDashboardVariableSourceApi]
+
+export const MetricsDashboardVariableSourceApi = {
+ Custom: 'custom',
+ Promql: 'promql',
+ Sql: 'sql',
+ Textbox: 'textbox',
+} as const
+
+export interface MetricsDashboardVariableApi {
+ /** The text that All puts in a PromQL query. `.*` when it is empty. */
+ allValue?: string | null
+ current?: MetricsDashboardVariableSelectionApi | null
+ /** The options when `source` is `custom`. */
+ customValues?: string[] | null
+ includeAll?: boolean | null
+ /** Shown in the dashboard filter bar. The name is shown when it is empty. */
+ label?: string | null
+ multi?: boolean | null
+ /** Letters, digits and underscores. Tiles refer to it as `$name`. */
+ name: string
+ /** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
+ query?: string | null
+ /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
+ regex?: string | null
+ source: MetricsDashboardVariableSourceApi
+}
+
export type PropertyOperatorApi = (typeof PropertyOperatorApi)[keyof typeof PropertyOperatorApi]
export const PropertyOperatorApi = {
@@ -2542,6 +2577,8 @@ export interface DashboardFilterApi {
interval?: IntervalTypeApi | null
/** Metric label matchers ANDed into every metrics tile. Other tiles ignore them. */
metricFilters?: MetricsQueryFilterApi[] | null
+ /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
+ metricVariables?: MetricsDashboardVariableApi[] | null
properties?:
| (
| EventPropertyFilterApi
diff --git a/products/dashboards/frontend/generated/api.schemas.ts b/products/dashboards/frontend/generated/api.schemas.ts
index 37fc14b7daed..e31fb8deced4 100644
--- a/products/dashboards/frontend/generated/api.schemas.ts
+++ b/products/dashboards/frontend/generated/api.schemas.ts
@@ -9764,6 +9764,41 @@ export interface MetricsQueryFilterApi {
value: string
}
+export interface MetricsDashboardVariableSelectionApi {
+ all?: boolean | null
+ /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
+ values: string[]
+}
+
+export type MetricsDashboardVariableSourceApi =
+ (typeof MetricsDashboardVariableSourceApi)[keyof typeof MetricsDashboardVariableSourceApi]
+
+export const MetricsDashboardVariableSourceApi = {
+ Custom: 'custom',
+ Promql: 'promql',
+ Sql: 'sql',
+ Textbox: 'textbox',
+} as const
+
+export interface MetricsDashboardVariableApi {
+ /** The text that All puts in a PromQL query. `.*` when it is empty. */
+ allValue?: string | null
+ current?: MetricsDashboardVariableSelectionApi | null
+ /** The options when `source` is `custom`. */
+ customValues?: string[] | null
+ includeAll?: boolean | null
+ /** Shown in the dashboard filter bar. The name is shown when it is empty. */
+ label?: string | null
+ multi?: boolean | null
+ /** Letters, digits and underscores. Tiles refer to it as `$name`. */
+ name: string
+ /** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
+ query?: string | null
+ /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
+ regex?: string | null
+ source: MetricsDashboardVariableSourceApi
+}
+
export interface DashboardFilterApi {
breakdown_filter?: BreakdownFilterApi | null
/** Period comparison forced onto every insight that supports one. Absent/null = inherit. */
@@ -9777,6 +9812,8 @@ export interface DashboardFilterApi {
interval?: IntervalTypeApi | null
/** Metric label matchers ANDed into every metrics tile. Other tiles ignore them. */
metricFilters?: MetricsQueryFilterApi[] | null
+ /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
+ metricVariables?: MetricsDashboardVariableApi[] | null
properties?:
| (
| EventPropertyFilterApi
diff --git a/products/desktop/packages/api-client/src/generated.ts b/products/desktop/packages/api-client/src/generated.ts
index 457ab7017b85..628d214fbeb3 100644
--- a/products/desktop/packages/api-client/src/generated.ts
+++ b/products/desktop/packages/api-client/src/generated.ts
@@ -6386,6 +6386,33 @@ export namespace Schemas {
scope?: (MetricsAttributeScope | null) | undefined;
value: string;
};
+ export type MetricsDashboardVariableSelection = {
+ all?: (boolean | null) | undefined;
+ /**
+ * The selected values. Empty when `all` is true: All stands for every option of the variable.
+ */
+ values: Array<string>;
+ };
+ export type MetricsDashboardVariableSource =
+ | "custom"
+ | "promql"
+ | "sql"
+ | "textbox";
+ export type MetricsDashboardVariable = {
+ allValue?: (string | null) | undefined;
+ current?: (MetricsDashboardVariableSelection | null) | undefined;
+ customValues?: (Array<string> | null) | undefined;
+ includeAll?: (boolean | null) | undefined;
+ label?: (string | null) | undefined;
+ multi?: (boolean | null) | undefined;
+ /**
+ * Letters, digits and underscores. Tiles refer to it as `$name`.
+ */
+ name: string;
+ query?: (string | null) | undefined;
+ regex?: (string | null) | undefined;
+ source: MetricsDashboardVariableSource;
+ };
export type DashboardFilter = Partial<{
breakdown_filter: BreakdownFilter | null;
compareFilter: CompareFilter | null;
@@ -6395,6 +6422,7 @@ export namespace Schemas {
filterTestAccounts: boolean | null;
interval: IntervalType | null;
metricFilters: Array<MetricsQueryFilter> | null;
+ metricVariables: Array<MetricsDashboardVariable> | null;
properties: Array<
| EventPropertyFilter
| PersonPropertyFilter
diff --git a/products/endpoints/frontend/generated/api.schemas.ts b/products/endpoints/frontend/generated/api.schemas.ts
index d243382914a5..ea7f65658052 100644
--- a/products/endpoints/frontend/generated/api.schemas.ts
+++ b/products/endpoints/frontend/generated/api.schemas.ts
@@ -676,6 +676,41 @@ export interface MetricsQueryFilterApi {
value: string
}
+export interface MetricsDashboardVariableSelectionApi {
+ all?: boolean | null
+ /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
+ values: string[]
+}
+
+export type MetricsDashboardVariableSourceApi =
+ (typeof MetricsDashboardVariableSourceApi)[keyof typeof MetricsDashboardVariableSourceApi]
+
+export const MetricsDashboardVariableSourceApi = {
+ Custom: 'custom',
+ Promql: 'promql',
+ Sql: 'sql',
+ Textbox: 'textbox',
+} as const
+
+export interface MetricsDashboardVariableApi {
+ /** The text that All puts in a PromQL query. `.*` when it is empty. */
+ allValue?: string | null
+ current?: MetricsDashboardVariableSelectionApi | null
+ /** The options when `source` is `custom`. */
+ customValues?: string[] | null
+ includeAll?: boolean | null
+ /** Shown in the dashboard filter bar. The name is shown when it is empty. */
+ label?: string | null
+ multi?: boolean | null
+ /** Letters, digits and underscores. Tiles refer to it as `$name`. */
+ name: string
+ /** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
+ query?: string | null
+ /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
+ regex?: string | null
+ source: MetricsDashboardVariableSourceApi
+}
+
export type PropertyOperatorApi = (typeof PropertyOperatorApi)[keyof typeof PropertyOperatorApi]
export const PropertyOperatorApi = {
@@ -1015,6 +1050,8 @@ export interface DashboardFilterApi {
interval?: IntervalTypeApi | null
/** Metric label matchers ANDed into every metrics tile. Other tiles ignore them. */
metricFilters?: MetricsQueryFilterApi[] | null
+ /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
+ metricVariables?: MetricsDashboardVariableApi[] | null
properties?:
| (
| EventPropertyFilterApi
diff --git a/products/metrics/backend/dashboard_import/promql_text.py b/products/metrics/backend/dashboard_import/promql_text.py
index 48aefbc23ffb..b6abd48baf3e 100644
--- a/products/metrics/backend/dashboard_import/promql_text.py
+++ b/products/metrics/backend/dashboard_import/promql_text.py
@@ -9,6 +9,8 @@ from __future__ import annotations
import re
from typing import Literal
+import re2
+
from posthog.dataclasses import frozen
from products.metrics.backend.promql import CLAUSE_LABEL
@@ -205,8 +207,13 @@ def drop_match_all_matchers(expr: str) -> str:
if len(kept) != len(elements):
inner = ", ".join(expr[element[0].start : element[-1].end] for element in kept)
previous = _previous_significant(tokens, index)
- if not inner and previous is not None and previous.kind == "ident":
+ if not inner and previous is not None and _is_metric_name(previous):
edits.append((token.start, tokens[end].end, ""))
+ elif previous is None or not _is_metric_name(previous):
+ # PromQL rejects a selector without a metric name when every matcher accepts an empty label.
+ if all(_accepts_empty(element) for element in kept):
+ inner = ", ".join(['__name__=~".+"', *([inner] if inner else [])])
+ edits.append((token.end, tokens[end].start, inner))
else:
edits.append((token.end, tokens[end].start, inner))
index = end + 1
@@ -218,6 +225,23 @@ def drop_match_all_matchers(expr: str) -> str:
return rewritten
+def _accepts_empty(element: list[Token]) -> bool:
+ if len(element) != 3 or element[2].kind != "string" or element[1].text not in ("=", "!=", "=~", "!~"):
+ return False
+ value = unquote(element[2].text)
+ if element[1].text in ("=", "!="):
+ return (value == "") == (element[1].text == "=")
+ try:
+ matches_empty = re2.fullmatch(value, "") is not None
+ except re2.error:
+ return False
+ return matches_empty == (element[1].text == "=~")
+
+
+def _is_metric_name(token: Token) -> bool:
+ return token.kind == "ident" and token.text.lower() not in KEYWORDS
+
+
def _previous_significant(tokens: list[Token], index: int) -> Token | None:
for previous in reversed(tokens[:index]):
if previous.kind != "space":
diff --git a/products/metrics/backend/date_range.py b/products/metrics/backend/date_range.py
new file mode 100644
index 000000000000..1b7a8ab00f04
--- /dev/null
+++ b/products/metrics/backend/date_range.py
@@ -0,0 +1,31 @@
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from posthog.schema import DateRange
+
+from posthog.hogql_queries.utils.query_date_range import QueryDateRange
+
+if TYPE_CHECKING:
+ from posthog.models import Team
+
+# Metrics dashboards are usually about "what is happening now", so the
+# node defaults to a tighter window than the analytics-wide -7d.
+DEFAULT_DATE_FROM = "-24h"
+
+
+def metrics_query_date_range(team: "Team", date_range: DateRange | None) -> QueryDateRange:
+ # The facade picks and aligns the bucket interval, so this passes interval=None.
+ # With interval=None, QueryDateRange falls back to day. exact_timerange stops it truncating a
+ # relative date_from to midnight (so "-30M" would read the whole day), and explicitDate stops it
+ # rounding an explicit date_to up to the end of the day.
+ return QueryDateRange(
+ date_range=DateRange(
+ date_from=(date_range.date_from if date_range else None) or DEFAULT_DATE_FROM,
+ date_to=date_range.date_to if date_range else None,
+ explicitDate=True,
+ ),
+ team=team,
+ interval=None,
+ now=datetime.now(),
+ exact_timerange=True,
+ )
diff --git a/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py b/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py
index 42ce0f908933..f1bfcee43a5e 100644
--- a/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py
+++ b/products/metrics/backend/hogql_queries/metrics_histogram_query_runner.py
@@ -28,11 +28,19 @@ from posthog.permissions import posthog_feature_flag_enabled
from posthog.shared_link_user import SharedLinkUser
from products.access_control.backend.facade.user_access_control import UserAccessControl, UserAccessControlError
+from products.metrics.backend.date_range import metrics_query_date_range
from products.metrics.backend.facade.contracts import METRICS_FEATURE_FLAG, MetricFilter
from products.metrics.backend.facade.enums import AttributeScope, FilterOp
-from products.metrics.backend.hogql_queries.metrics_query_runner import metrics_query_date_range
from products.metrics.backend.metric_query_runner import _INTERVAL_LADDER, _QUERY_SETTINGS, _interval_step
from products.metrics.backend.metric_samples_query_runner import build_metric_query_runner
+from products.metrics.backend.variables import (
+ filter_referenced_names,
+ from_dashboard,
+ from_query,
+ substitute_filters,
+ to_query,
+ unresolved_message,
+)
if TYPE_CHECKING:
from posthog.models import User
@@ -101,6 +109,9 @@ class MetricsHistogramQueryRunner(AnalyticsQueryRunner[MetricsHistogramQueryResp
else:
interval = _INTERVAL_LADDER[-1][0]
+ substitution = substitute_filters(self.query.filters, from_query(self.query.variables))
+ if substitution.unresolved:
+ raise ExposedHogQLError(unresolved_message(substitution.unresolved))
filters = tuple(
MetricFilter(
key=f.key,
@@ -108,7 +119,7 @@ class MetricsHistogramQueryRunner(AnalyticsQueryRunner[MetricsHistogramQueryResp
value=f.value,
scope=AttributeScope(f.scope.value) if f.scope is not None else AttributeScope.AUTO,
)
- for f in self.query.filters or []
+ for f in substitution.filters
)
try:
@@ -210,3 +221,9 @@ class MetricsHistogramQueryRunner(AnalyticsQueryRunner[MetricsHistogramQueryResp
)
if dashboard_filter.metricFilters:
self.query.filters = [*(self.query.filters or []), *dashboard_filter.metricFilters]
+ if dashboard_filter.metricVariables:
+ # The values go into the query, so each selection has its own cache entry and reaches the async worker.
+ self.query.variables = (
+ to_query(from_dashboard(dashboard_filter.metricVariables), filter_referenced_names(self.query.filters))
+ or None
+ )
diff --git a/products/metrics/backend/hogql_queries/metrics_query_runner.py b/products/metrics/backend/hogql_queries/metrics_query_runner.py
index a3b54140333d..464eeb25032e 100644
--- a/products/metrics/backend/hogql_queries/metrics_query_runner.py
+++ b/products/metrics/backend/hogql_queries/metrics_query_runner.py
@@ -7,7 +7,6 @@ bypasses the facade, so the viewer, MCP tools, and insights all share one
query path.
"""
-from datetime import datetime
from typing import TYPE_CHECKING, Optional, cast
from posthog.schema import (
@@ -26,11 +25,12 @@ from posthog.hogql.errors import ExposedHogQLError
from posthog.api.snuffle_proxy import SNUFFLE_API_FEATURE_FLAG
from posthog.hogql_queries.query_runner import AnalyticsQueryRunner
-from posthog.hogql_queries.utils.query_date_range import QueryDateRange
from posthog.permissions import posthog_feature_flag_enabled
from posthog.shared_link_user import SharedLinkUser
from products.access_control.backend.facade.user_access_control import UserAccessControl, UserAccessControlError
+from products.metrics.backend.dashboard_import.promql_text import drop_match_all_matchers
+from products.metrics.backend.date_range import metrics_query_date_range
from products.metrics.backend.facade.api import run_metric_query
from products.metrics.backend.facade.contracts import (
METRICS_FEATURE_FLAG,
@@ -49,31 +49,21 @@ from products.metrics.backend.facade.enums import (
)
from products.metrics.backend.promql import run_promql_range
from products.metrics.backend.sql_mode import run_metrics_sql
+from products.metrics.backend.variables import (
+ filter_referenced_names,
+ from_dashboard,
+ from_query,
+ referenced_names,
+ sql_referenced_names,
+ substitute_filters,
+ substitute_promql,
+ substitute_sql,
+ to_query,
+ unresolved_message,
+)
if TYPE_CHECKING:
- from posthog.models import Team, User
-
-# Metrics dashboards are usually about "what is happening now", so the
-# node defaults to a tighter window than the analytics-wide -7d.
-DEFAULT_DATE_FROM = "-24h"
-
-
-def metrics_query_date_range(team: "Team", date_range: DateRange | None) -> QueryDateRange:
- # The facade picks and aligns the bucket interval, so this passes interval=None.
- # With interval=None, QueryDateRange falls back to day. exact_timerange stops it truncating a
- # relative date_from to midnight (so "-30M" would read the whole day), and explicitDate stops it
- # rounding an explicit date_to up to the end of the day.
- return QueryDateRange(
- date_range=DateRange(
- date_from=(date_range.date_from if date_range else None) or DEFAULT_DATE_FROM,
- date_to=date_range.date_to if date_range else None,
- explicitDate=True,
- ),
- team=team,
- interval=None,
- now=datetime.now(),
- exact_timerange=True,
- )
+ from posthog.models import User
class MetricsQueryRunner(AnalyticsQueryRunner[MetricsQueryResponse]):
@@ -181,14 +171,35 @@ class MetricsQueryRunner(AnalyticsQueryRunner[MetricsQueryResponse]):
def _run(self) -> list[MetricSeries]:
language = self.query.language or MetricsQueryLanguage.BUILDER
+ variables = from_query(self.query.variables)
if language == MetricsQueryLanguage.BUILDER:
+ clauses = []
+ for clause in self.query.clauses:
+ substitution = substitute_filters(clause.filters, variables)
+ if substitution.unresolved:
+ raise ValueError(unresolved_message(substitution.unresolved))
+ clauses.append(
+ clause.model_copy(update={"filters": substitution.filters}) if clause.filters else clause
+ )
+ self.query.clauses = clauses
return run_metric_query(team=self.team, request=self._to_request())
date_range = metrics_query_date_range(self.team, self.query.dateRange)
- text = (self.query.promql if language == MetricsQueryLanguage.PROMQL else self.query.sql) or ""
- if not text.strip():
- raise ValueError(f"Write a {'PromQL' if language == MetricsQueryLanguage.PROMQL else 'SQL'} query first.")
- run = run_promql_range if language == MetricsQueryLanguage.PROMQL else run_metrics_sql
- return run(self.team, text, date_range.date_from(), date_range.date_to(), self.query.interval)
+ date_from, date_to = date_range.date_from(), date_range.date_to()
+ if language == MetricsQueryLanguage.PROMQL:
+ if not (self.query.promql or "").strip():
+ raise ValueError("Write a PromQL query first.")
+ promql = substitute_promql(self.query.promql or "", variables)
+ if promql.unresolved:
+ raise ValueError(unresolved_message(promql.unresolved))
+ # A variable set to All writes `label=~".*"`, which matches every series.
+ text = drop_match_all_matchers(promql.text) if promql.text != self.query.promql else promql.text
+ return run_promql_range(self.team, text, date_from, date_to, self.query.interval)
+ if not (self.query.sql or "").strip():
+ raise ValueError("Write a SQL query first.")
+ sql = substitute_sql(self.query.sql or "", variables)
+ if sql.unresolved:
+ raise ValueError(unresolved_message(sql.unresolved))
+ return run_metrics_sql(self.team, sql.sql, date_from, date_to, self.query.interval, sql.placeholders)
def _calculate(self) -> MetricsQueryResponse:
self._enforce_alpha_gates_without_a_request_user()
@@ -214,8 +225,9 @@ class MetricsQueryRunner(AnalyticsQueryRunner[MetricsQueryResponse]):
def apply_dashboard_filters(self, dashboard_filter: DashboardFilter) -> None:
# Metric label predicates are not PostHog property filters, so the dashboard's
- # property filters do not apply. Its date range and label filters do. Label filters
- # reach builder clauses only: PromQL and SQL text is not rewritten.
+ # property filters do not apply. Its date range, variables and label filters do.
+ # Variables reach all three languages. Label filters reach builder clauses only:
+ # PromQL and SQL text is not rewritten for them.
if dashboard_filter.date_from or dashboard_filter.date_to:
self.query.dateRange = DateRange(
date_from=dashboard_filter.date_from,
@@ -226,3 +238,16 @@ class MetricsQueryRunner(AnalyticsQueryRunner[MetricsQueryResponse]):
clause.model_copy(update={"filters": [*(clause.filters or []), *dashboard_filter.metricFilters]})
for clause in self.query.clauses
]
+ if dashboard_filter.metricVariables:
+ self._apply_variables(dashboard_filter)
+
+ def _apply_variables(self, dashboard_filter: DashboardFilter) -> None:
+ # The values go into the query, so each selection has its own cache entry and reaches the async worker.
+ names = dict.fromkeys(
+ [
+ *referenced_names(self.query.promql),
+ *sql_referenced_names(self.query.sql),
+ *(name for clause in self.query.clauses for name in filter_referenced_names(clause.filters)),
+ ]
+ )
+ self.query.variables = to_query(from_dashboard(dashboard_filter.metricVariables), names) or None
diff --git a/products/metrics/backend/series.py b/products/metrics/backend/series.py
index be68d2323ef4..a4d55998d00d 100644
--- a/products/metrics/backend/series.py
+++ b/products/metrics/backend/series.py
@@ -1,8 +1,10 @@
from collections.abc import Sequence
-from products.metrics.backend.facade.api import MAX_SERIES_PER_CLAUSE
from products.metrics.backend.facade.contracts import MAX_CLAUSES_PER_QUERY, MetricPoint, MetricSeries
-from products.metrics.backend.metric_query_runner import _MAX_BUCKET_COUNT
+from products.metrics.backend.metric_query_runner import (
+ _MAX_BUCKET_COUNT,
+ MAX_RAW_SERIES as MAX_SERIES_PER_CLAUSE,
+)
# The most a builder query can return: every clause at its series cap, on the longest bucket grid.
# A PromQL or SQL query chooses its own clauses and times, so these limits bound its output too.
diff --git a/products/metrics/backend/sql_mode.py b/products/metrics/backend/sql_mode.py
index 76643804dd4a..29929d25b90a 100644
--- a/products/metrics/backend/sql_mode.py
+++ b/products/metrics/backend/sql_mode.py
@@ -14,6 +14,7 @@ the bucket interval.
import math
import datetime as dt
+from collections.abc import Mapping
from typing import Any
from posthog.hogql import ast
@@ -113,13 +114,18 @@ def _assert_reads_only_metrics_tables(team: Team, query: ast.SelectQuery | ast.S
)
-def build_metrics_sql_query(
- team: Team, sql: str, date_from: dt.datetime, date_to: dt.datetime, interval: str | None
-) -> ast.SelectQuery:
- """Parse the insight's SQL with the date placeholders filled in, wrapped in the row limit."""
+def _parse_metrics_sql(
+ team: Team,
+ sql: str,
+ date_from: dt.datetime,
+ date_to: dt.datetime,
+ interval: str | None,
+ variables: Mapping[str, ast.Expr] | None,
+) -> ast.SelectQuery | ast.SelectSetQuery:
resolved = _resolve_interval(date_from, date_to, interval)
step = _interval_step(resolved)
placeholders: dict[str, ast.Expr] = {
+ **(variables or {}),
"date_from": ast.Constant(value=_align_to_interval(date_from, resolved, tzinfo=team.timezone_info)),
"date_to": ast.Constant(value=date_to),
"interval": _interval_expr(resolved),
@@ -127,6 +133,19 @@ def build_metrics_sql_query(
}
inner = parse_select(sql, placeholders=placeholders)
_assert_reads_only_metrics_tables(team, inner)
+ return inner
+
+
+def build_metrics_sql_query(
+ team: Team,
+ sql: str,
+ date_from: dt.datetime,
+ date_to: dt.datetime,
+ interval: str | None,
+ variables: Mapping[str, ast.Expr] | None = None,
+) -> ast.SelectQuery:
+ """Parse the insight's SQL with the date and variable placeholders filled in, wrapped in the row limit."""
+ inner = _parse_metrics_sql(team, sql, date_from, date_to, interval, variables)
wrapped = parse_select(
"SELECT * FROM {inner} LIMIT {row_limit}",
placeholders={"inner": inner, "row_limit": ast.Constant(value=_SQL_ROW_LIMIT)},
@@ -170,9 +189,14 @@ def _on_interval_starts(times: list[Any], interval: str, team: Team) -> bool:
def run_metrics_sql(
- team: Team, sql: str, date_from: dt.datetime, date_to: dt.datetime, interval: str | None
+ team: Team,
+ sql: str,
+ date_from: dt.datetime,
+ date_to: dt.datetime,
+ interval: str | None,
+ variables: Mapping[str, ast.Expr] | None = None,
) -> list[MetricSeries]:
- query = build_metrics_sql_query(team, sql, date_from, date_to, interval)
+ query = build_metrics_sql_query(team, sql, date_from, date_to, interval, variables)
response = execute_hogql_query(
query_type="MetricsSQLQuery",
query=query,
diff --git a/products/metrics/backend/tests/test_dashboard_import_parsing.py b/products/metrics/backend/tests/test_dashboard_import_parsing.py
index 4b79c7d93a14..9fff58ebc909 100644
--- a/products/metrics/backend/tests/test_dashboard_import_parsing.py
+++ b/products/metrics/backend/tests/test_dashboard_import_parsing.py
@@ -410,6 +410,10 @@ def test_rewrites_grafana_ranges_to_the_query_step(expr: str, expected: str, cha
('up{job=~".*", env="prod"}', 'up{env="prod"}'),
('up{job=~".*"}', "up"),
('up{job=~".+"}', 'up{job=~".+"}'),
+ ('{__name__=~".*"}', '{__name__=~".+"}'),
+ ('up or {job=~".*"}', 'up or {__name__=~".+"}'),
+ ('{job=~".*", env!="dev"}', '{__name__=~".+", env!="dev"}'),
+ ('{job=~".*", env="prod"}', '{env="prod"}'),
],
)
def test_drops_matchers_that_match_everything(expr: str, expected: str) -> None:
diff --git a/products/metrics/backend/tests/test_metrics_histogram_query_runner.py b/products/metrics/backend/tests/test_metrics_histogram_query_runner.py
index caa5562145f7..fbab7804f3b1 100644
--- a/products/metrics/backend/tests/test_metrics_histogram_query_runner.py
+++ b/products/metrics/backend/tests/test_metrics_histogram_query_runner.py
@@ -171,6 +171,12 @@ class TestMetricsHistogramQueryRunner(ClickhouseTestMixin, APIBaseTest):
first, second = (dt.datetime.fromisoformat(t) for t in response.times[:2])
self.assertEqual(second - first, dt.timedelta(hours=6))
+ def test_unresolved_variable_is_explained_without_a_query(self):
+ with patch("products.metrics.backend.hogql_queries.metrics_histogram_query_runner.execute_hogql_query") as run:
+ with self.assertRaisesRegex(ExposedHogQLError, r"\$job"):
+ self._run(filters=[MetricsQueryFilter(key="job", op="eq", value="$job")])
+ run.assert_not_called()
+
def test_invalid_range_surfaces_as_client_error_not_500(self):
with self.assertRaises(ExposedHogQLError):
self._run(
diff --git a/products/metrics/backend/tests/test_metrics_query_languages.py b/products/metrics/backend/tests/test_metrics_query_languages.py
index a3d26d02e3c8..5f659649ee96 100644
--- a/products/metrics/backend/tests/test_metrics_query_languages.py
+++ b/products/metrics/backend/tests/test_metrics_query_languages.py
@@ -14,7 +14,15 @@ from django.test import override_settings
import requests
from parameterized import parameterized
-from posthog.schema import DateRange, HogQLQuery, MetricsQuery, MetricsQueryClause
+from posthog.schema import (
+ DashboardFilter,
+ DateRange,
+ HogQLQuery,
+ MetricsDashboardVariable,
+ MetricsDashboardVariableSelection,
+ MetricsQuery,
+ MetricsQueryClause,
+)
from posthog.hogql.errors import ExposedHogQLError
@@ -123,6 +131,41 @@ class TestMetricsSqlMode(ClickhouseTestMixin, APIBaseTest):
query = MetricsQuery(dateRange=DATE_RANGE, interval="minute_5", **fields)
return MetricsQueryRunner(query=query, team=self.team).calculate().results
+ @parameterized.expand(
+ [
+ ("one_value", MetricsDashboardVariableSelection(values=["api"]), {"api"}),
+ ("injected_value_is_a_constant", MetricsDashboardVariableSelection(values=["api' OR 1=1 --"]), set()),
+ ]
+ )
+ def test_dashboard_variables_filter_a_sql_query(
+ self, _name: str, selection: MetricsDashboardVariableSelection, expected: set[str]
+ ) -> None:
+ self._seed()
+ sql = (
+ "SELECT toStartOfInterval(timestamp, {interval}) AS time, service_name, count() AS value "
+ "FROM posthog.metrics WHERE service_name IN $service AND timestamp >= {date_from} "
+ "AND timestamp < {date_to} GROUP BY time, service_name"
+ )
+ runner = MetricsQueryRunner(
+ query=MetricsQuery(dateRange=DATE_RANGE, interval="minute_5", clauses=[], language="sql", sql=sql),
+ team=self.team,
+ )
+ runner.apply_dashboard_filters(
+ DashboardFilter(
+ metricVariables=[
+ MetricsDashboardVariable(
+ name="service",
+ source="custom",
+ customValues=["api", "worker"],
+ includeAll=True,
+ current=selection,
+ )
+ ]
+ )
+ )
+
+ assert {series.labels["service_name"] for series in runner.calculate().results} == expected
+
def test_generated_sql_matches_the_builder_engine(self) -> None:
self._seed()
for name, fixture in FIXTURES.items():
@@ -383,6 +426,39 @@ class TestMetricsPromQLMode(APIBaseTest):
assert (series.clause, series.labels) == (clause, labels)
+ def test_dashboard_variables_reach_the_promql_text_and_the_cache_key(self) -> None:
+ def runner_for(job: MetricsDashboardVariableSelection) -> MetricsQueryRunner:
+ runner = self._runner('sum(rate(http_requests_total{job=~"$job", env="${env}"}[$__rate_interval]))')
+ runner.apply_dashboard_filters(
+ DashboardFilter(
+ metricVariables=[
+ MetricsDashboardVariable(name="job", source="custom", includeAll=True, current=job),
+ MetricsDashboardVariable(
+ name="env", source="textbox", current=MetricsDashboardVariableSelection(values=["prod"])
+ ),
+ ]
+ )
+ )
+ return runner
+
+ payload = {"status": "success", "data": {"resultType": "matrix", "result": []}}
+ all_jobs = runner_for(MetricsDashboardVariableSelection(values=["api", "web"], all=True))
+ with patch(
+ "posthog.api.snuffle_proxy.internal_requests.request", return_value=_snuffle_response(200, payload)
+ ) as request:
+ all_jobs.calculate()
+
+ assert (
+ request.call_args.kwargs["data"]["query"] == 'sum(rate(http_requests_total{env="prod"}[$__rate_interval]))'
+ )
+ assert all_jobs.get_cache_key() != runner_for(MetricsDashboardVariableSelection(values=["api"])).get_cache_key()
+
+ def test_unresolved_variable_is_explained_without_a_query(self) -> None:
+ with patch("posthog.api.snuffle_proxy.internal_requests.request") as request:
+ with pytest.raises(ExposedHogQLError, match=r"\$job"):
+ self._runner('up{job="$job"}').calculate()
+ request.assert_not_called()
+
def test_empty_scalar_result_has_no_series(self) -> None:
payload = {"status": "success", "data": {"resultType": "scalar", "result": []}}
with patch("posthog.api.snuffle_proxy.internal_requests.request", return_value=_snuffle_response(200, payload)):
diff --git a/products/metrics/backend/tests/test_metrics_query_runner.py b/products/metrics/backend/tests/test_metrics_query_runner.py
index 572330cf6f2d..b4968a901b00 100644
--- a/products/metrics/backend/tests/test_metrics_query_runner.py
+++ b/products/metrics/backend/tests/test_metrics_query_runner.py
@@ -13,6 +13,8 @@ from posthog.schema import (
DateRange,
EventPropertyFilter,
GoalLine,
+ MetricsDashboardVariable,
+ MetricsDashboardVariableSelection,
MetricsDisplaySettings,
MetricsQuery,
MetricsQueryClause,
@@ -71,6 +73,28 @@ class TestMetricsQueryRunner(ClickhouseTestMixin, APIBaseTest):
assert (request.date_to - request.date_from) == dt.timedelta(hours=1)
@time_machine.travel("2026-09-19T12:00:00Z", tick=False)
+ def test_dashboard_label_filters_can_use_dashboard_variables(self) -> None:
+ runner = MetricsQueryRunner(
+ query=MetricsQuery(clauses=[MetricsQueryClause(name="a", metricName="queue_depth", aggregation="sum")]),
+ team=self.team,
+ )
+
+ runner.apply_dashboard_filters(
+ DashboardFilter(
+ metricFilters=[MetricsQueryFilter(key="job", op="eq", value="$job")],
+ metricVariables=[
+ MetricsDashboardVariable(
+ name="job",
+ source="custom",
+ customValues=["api"],
+ current=MetricsDashboardVariableSelection(values=["api"]),
+ )
+ ],
+ )
+ )
+
+ assert runner.query.variables is not None and runner.query.variables["job"].values == ["api"]
+
def test_default_date_range_is_last_24_hours(self) -> None:
query = MetricsQuery(
clauses=[MetricsQueryClause(name="a", metricName="http_requests_total", aggregation="sum")]
diff --git a/products/metrics/backend/tests/test_variables.py b/products/metrics/backend/tests/test_variables.py
new file mode 100644
index 000000000000..a9b4d6bb065a
--- /dev/null
+++ b/products/metrics/backend/tests/test_variables.py
@@ -0,0 +1,227 @@
+import pytest
+
+from parameterized import parameterized
+
+from posthog.schema import (
+ MetricsDashboardVariable,
+ MetricsDashboardVariableSelection,
+ MetricsDashboardVariableSource,
+ MetricsFilterOp,
+ MetricsQueryFilter,
+)
+
+from posthog.hogql import ast
+
+from products.metrics.backend.variables import (
+ Variable,
+ from_dashboard,
+ sql_referenced_names,
+ substitute_filter,
+ substitute_promql,
+ substitute_sql,
+)
+
+ONE = Variable(values=('pro"d',), is_all=False, all_value=None, options=())
+MANY = Variable(values=("a.b", "c"), is_all=False, all_value=None, options=())
+ALL = Variable(values=("x", "y"), is_all=True, all_value=None, options=())
+ALL_WITH_VALUE = Variable(values=(), is_all=True, all_value="api-.*", options=())
+DOTTED = Variable(values=("10.0.0.1",), is_all=False, all_value=None, options=())
+INJECTED = Variable(values=("' OR 1=1 --",), is_all=False, all_value=None, options=())
+QUOTED = Variable(values=("api'worker\nnext",), is_all=False, all_value=None, options=())
+
+
+ [
+ ("one_value_is_escaped", 'up{env="$env"}', ONE, 'up{env="pro\\"d"}'),
+ ("many_values_are_a_regex", 'up{env=~"$env"}', MANY, 'up{env=~"(a\\\\.b|c)"}'),
+ ("one_value_in_a_regex_matcher_is_escaped", 'up{env=~"$env"}', DOTTED, 'up{env=~"10\\\\.0\\\\.0\\\\.1"}'),
+ ("single_quotes_and_newlines", "up{env='$env'}", QUOTED, "up{env='api\\'worker\\nnext'}"),
+ ("double_quotes_keep_single_quotes", 'up{env="$env"}', QUOTED, 'up{env="api\'worker\\nnext"}'),
+ ("single_quoted_regex_matcher", "up{env=~'$env'}", DOTTED, "up{env=~'10\\\\.0\\\\.0\\\\.1'}"),
+ (
+ "quote_in_a_comment_does_not_change_the_string",
+ 'up{ # don\'t filter\n env="$env"}',
+ ONE,
+ 'up{ # don\'t filter\n env="pro\\"d"}',
+ ),
+ ("reference_in_a_comment_stays", "up # $env\n", ONE, "up # $env\n"),
+ ("csv_format", 'up{env=~"${env:csv}"}', MANY, 'up{env=~"a.b,c"}'),
+ ("csv_format_is_escaped", 'up{env=~"${env:csv}"}', ONE, 'up{env=~"pro\\"d"}'),
+ ("all_matches_everything", 'up{env=~"$env"}', ALL, 'up{env=~".*"}'),
+ ("all_value", 'up{env=~"[[env]]"}', ALL_WITH_VALUE, 'up{env=~"api-.*"}'),
+ (
+ "all_value_as_written",
+ "up{env=~`$env`}",
+ Variable(values=(), is_all=True, all_value="api\\..*", options=(), all_value_as_written=True),
+ "up{env=~`api\\..*`}",
+ ),
+ (
+ "all_value_is_escaped",
+ 'up{env=~"$env"}',
+ Variable(values=(), is_all=True, all_value='api\\."x', options=()),
+ 'up{env=~"api\\\\.\\"x"}',
+ ),
+ (
+ "range_variables_and_regex_groups_stay",
+ 'label_replace(rate(x{env="$env"}[$__rate_interval]), "a", "$1", "b", "(.*)")',
+ ONE,
+ 'label_replace(rate(x{env="pro\\"d"}[$__rate_interval]), "a", "$1", "b", "(.*)")',
+ ),
+ ("escaped_dollar_in_a_matcher", 'up{c=~"\\\\$env", env="$env"}', ONE, 'up{c=~"\\\\$env", env="pro\\"d"}'),
+ ("escaped_backslash_in_an_equality_matcher", 'up{c="C:\\\\$env"}', DOTTED, 'up{c="C:\\\\10.0.0.1"}'),
+ ("escaped_dollar_in_a_raw_string", "up{c=~`\\$env`}", ONE, "up{c=~`\\$env`}"),
+ (
+ "named_regex_groups_stay",
+ 'label_replace(up, "dst", "$name", "src", "(?P<name>.*)")',
+ ONE,
+ 'label_replace(up, "dst", "$name", "src", "(?P<name>.*)")',
+ ),
+ ]
+)
+def test_substitutes_promql(_name: str, expr: str, variable: Variable, expected: str) -> None:
+ substitution = substitute_promql(expr, {"env": variable})
+ assert (substitution.text, substitution.unresolved) == (expected, ())
+
+
+ [
+ ("label_replace_replacement", 'label_replace(up, "dst", "$name", "src", "(?P<name>.*)")', ()),
+ ("label_join_separator", 'label_join(up, "dst", "$separator", "job", "env")', ("separator",)),
+ ("label_replace_regex_escape", 'label_replace(up, "dst", "matched", "src", "prefix\\\\$USD")', ()),
+ ("matcher", 'up{job="$job"}', ("job",)),
+ ]
+)
+def test_only_label_replace_replacements_keep_undefined_names(_name: str, expr: str, unresolved: tuple[str]) -> None:
+ assert substitute_promql(expr, {}).unresolved == unresolved
+
+
+def test_promql_reports_unresolved_variables_and_keeps_the_named_ones() -> None:
+ substitution = substitute_promql('up{env="$env", job="$job", zone="$zone"}', {"env": ONE}, keep={"zone"})
+ assert (substitution.text, substitution.unresolved) == ('up{env="pro\\"d", job="$job", zone="$zone"}', ("job",))
+
+
+ [
+ ("one_value_is_a_constant", "SELECT 1 WHERE env = $env", ONE, ast.Constant(value='pro"d')),
+ ("quoted_reference_is_one_constant", "SELECT 1 WHERE env = '$env'", ONE, ast.Constant(value='pro"d')),
+ (
+ "injected_value_stays_a_constant",
+ "SELECT 1 WHERE env = '${env}'",
+ INJECTED,
+ ast.Constant(value="' OR 1=1 --"),
+ ),
+ (
+ "many_values_are_a_tuple",
+ "SELECT 1 WHERE env IN ${env}",
+ MANY,
+ ast.Tuple(exprs=[ast.Constant(value="a.b"), ast.Constant(value="c")]),
+ ),
+ (
+ "all_is_its_values",
+ "SELECT 1 WHERE env IN $env",
+ ALL,
+ ast.Tuple(exprs=[ast.Constant(value="x"), ast.Constant(value="y")]),
+ ),
+ ]
+)
+def test_sql_references_become_placeholders(_name: str, sql: str, variable: Variable, expected: ast.Expr) -> None:
+ substitution = substitute_sql(sql, {"env": variable})
+ assert substitution.sql.endswith("{metric_variable_env}")
+ assert substitution.placeholders == {"metric_variable_env": expected}
+
+
+ [
+ ("field_names", "SELECT properties.$env, $environment FROM t"),
+ ("comments", "SELECT 1 -- $env\n/* $env */ // $env\n# $env"),
+ ("other_strings", "SELECT '$1', \"$env\""),
+ ("nested_arrays", "SELECT [[env]]"),
+ ]
+)
+def test_sql_text_that_is_not_a_reference_stays(_name: str, sql: str) -> None:
+ substitution = substitute_sql(sql, {"env": ONE})
+ assert (substitution.sql, substitution.placeholders) == (sql, {})
+
+
+def test_sql_references_in_comments_are_not_dependencies() -> None:
+ assert sql_referenced_names("SELECT 1 -- $job\rWHERE env IN $env /* $zone */ AND x = 'a-$region'") == [
+ "env",
+ "region",
+ ]
+
+
+def test_sql_time_aliases_become_the_date_placeholders() -> None:
+ substitution = substitute_sql(
+ "SELECT 1 WHERE t >= $__from AND t < '${__to}' GROUP BY $__interval, $__interval_seconds", {}
+ )
+ assert (substitution.sql, substitution.placeholders, substitution.unresolved) == (
+ "SELECT 1 WHERE t >= {date_from} AND t < {date_to} GROUP BY {interval}, {interval_seconds}",
+ {},
+ (),
+ )
+
+
+def test_sql_quoted_reference_without_a_selection_is_reported() -> None:
+ assert substitute_sql("SELECT 1 WHERE job = '$job'", {"env": ONE}).unresolved == ("job",)
+
+
+def test_sql_reference_inside_a_longer_string_is_rejected() -> None:
+ with pytest.raises(ValueError, match=r"\$env is inside a string"):
+ substitute_sql("SELECT 1 WHERE env = 'prefix-$env'", {"env": INJECTED})
+
+
+ [
+ ("one_value", MetricsFilterOp.EQ, "$env", ONE, (MetricsFilterOp.EQ, 'pro"d')),
+ (
+ "one_value_in_a_regex_filter",
+ MetricsFilterOp.REGEX,
+ "$env",
+ DOTTED,
+ (MetricsFilterOp.REGEX, "^(?:10\\.0\\.0\\.1)$"),
+ ),
+ (
+ "many_values_become_an_anchored_regex",
+ MetricsFilterOp.EQ,
+ "$env",
+ MANY,
+ (MetricsFilterOp.REGEX, "^(?:a\\.b|c)$"),
+ ),
+ ("negated_many_values", MetricsFilterOp.NEQ, "${env}", MANY, (MetricsFilterOp.NOT_REGEX, "^(?:a\\.b|c)$")),
+ ("all_drops_the_filter", MetricsFilterOp.EQ, "$env", ALL, None),
+ ("negated_all_matches_nothing", MetricsFilterOp.NEQ, "$env", ALL, (MetricsFilterOp.NOT_REGEX, ".*")),
+ ("all_value", MetricsFilterOp.EQ, "$env", ALL_WITH_VALUE, (MetricsFilterOp.REGEX, "api-.*")),
+ ("inside_a_regex", MetricsFilterOp.REGEX, "^$env-.*", MANY, (MetricsFilterOp.REGEX, "^(?:a\\.b|c)-.*")),
+ ("all_inside_a_regex", MetricsFilterOp.REGEX, "^$env$", ALL, (MetricsFilterOp.REGEX, "^.*$")),
+ ("whitespace_around_a_reference", MetricsFilterOp.EQ, " $env ", ONE, (MetricsFilterOp.EQ, ' pro"d ')),
+ (
+ "escaped_dollar_in_a_regex",
+ MetricsFilterOp.REGEX,
+ "\\$env-$env",
+ ONE,
+ (MetricsFilterOp.REGEX, '\\$env-(?:pro"d)'),
+ ),
+ ]
+)
+def test_substitutes_builder_filters(
+ _name: str,
+ op: MetricsFilterOp,
+ value: str,
+ variable: Variable,
+ expected: tuple[MetricsFilterOp, str] | None,
+) -> None:
+ substitution = substitute_filter(MetricsQueryFilter(key="env", op=op, value=value), {"env": variable})
+ assert substitution.unresolved == ()
+ result = substitution.filter
+ assert (None if result is None else (result.op, result.value)) == expected
+
+
[email protected]("include_all", [True, False])
+def test_all_needs_include_all(include_all: bool) -> None:
+ definition = MetricsDashboardVariable(
+ name="env",
+ source=MetricsDashboardVariableSource.CUSTOM,
+ includeAll=include_all,
+ current=MetricsDashboardVariableSelection(values=["a"], all=True),
+ )
+ assert from_dashboard([definition])["env"].is_all is include_all
diff --git a/products/metrics/backend/variables.py b/products/metrics/backend/variables.py
new file mode 100644
index 000000000000..c92433f447c6
--- /dev/null
+++ b/products/metrics/backend/variables.py
@@ -0,0 +1,498 @@
+"""Grafana-style variables in metrics queries: `$name`, `${name}`, `${name:format}` and `[[name]]`.
+
+SQL gets HogQL placeholders that hold constants, so a value never becomes SQL text.
+"""
+
+from __future__ import annotations
+
+import re
+import dataclasses
+from collections.abc import Collection, Iterable, Iterator, Mapping
+from typing import Any
+
+from posthog.schema import MetricsDashboardVariable, MetricsFilterOp, MetricsQueryFilter, MetricsVariableValue
+
+from posthog.hogql import ast
+
+from posthog.dataclasses import frozen
+
+REFERENCE = re.compile(
+ r"\$\{(?P<braced>[A-Za-z0-9_]+)(?::(?P<braced_format>[A-Za-z0-9_]+))?\}"
+ r"|\[\[(?P<bracketed>[A-Za-z0-9_]+)(?::(?P<bracketed_format>[A-Za-z0-9_]+))?\]\]"
+ r"|\$(?P<plain>[A-Za-z0-9_]+)"
+)
+# The query step and the dashboard range fill these, so the substitution must leave them in place.
+RANGE_VARIABLES = frozenset({"__rate_interval", "__interval", "__range", "__range_s", "__range_ms", "__auto"})
+VARIABLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+_REGEX_SPECIAL = set("\\^$.|?*+()[]{}")
+_PROMQL_CONTROL_ESCAPES = {"\n": "\\n", "\r": "\\r", "\t": "\\t"}
+_SQL_REFERENCE = re.compile(r"\$\{(?P<braced>[A-Za-z0-9_]+)(?::[A-Za-z0-9_]+)?\}|\$(?P<plain>[A-Za-z0-9_]+)")
+MATCH_ALL = ".*"
+_LINE_END = re.compile(r"[\r\n]")
+_SQL_TIME_PLACEHOLDERS = {
+ "__from": "date_from",
+ "__to": "date_to",
+ "__interval": "interval",
+ "__interval_seconds": "interval_seconds",
+}
+
+
+@frozen
+class Variable:
+ values: tuple[str, ...]
+ is_all: bool
+ all_value: str | None
+ # The options that All expands to when it has no all value. Empty means "match everything".
+ options: tuple[str, ...]
+ # Grafana puts an imported all value into the query as it is written, whatever string holds it.
+ all_value_as_written: bool = False
+
+
+@frozen
+class PromQLStringContext:
+ # The quote of the PromQL string that holds the reference, or None outside a string.
+ quote: str | None
+ in_regex: bool
+ # The replacement argument of label_replace, where `$name` is a named regex group.
+ in_replacement: bool = False
+
+
+@frozen
+class Substitution:
+ text: str
+ unresolved: tuple[str, ...]
+
+
+@frozen
+class SqlSubstitution:
+ sql: str
+ placeholders: dict[str, ast.Expr]
+ unresolved: tuple[str, ...]
+ # References inside longer strings. They are an error when the variable has a value.
+ in_strings: tuple[str, ...] = ()
+
+
+@frozen
+class FilterSubstitution:
+ # None when the filter matches everything, so the query drops it.
+ filter: MetricsQueryFilter | None
+ unresolved: tuple[str, ...]
+
+
+@frozen
+class FiltersSubstitution:
+ filters: list[MetricsQueryFilter]
+ unresolved: tuple[str, ...]
+
+
+def reference_name(match: re.Match[str]) -> str:
+ return match.group("braced") or match.group("bracketed") or match.group("plain")
+
+
+def _is_variable_reference(name: str) -> bool:
+ # A numeric reference such as $1 is a regex group in label_replace, not a variable.
+ return name not in RANGE_VARIABLES and not name.isdigit()
+
+
+def referenced_names(text: str | None) -> list[str]:
+ names = (reference_name(match) for match in REFERENCE.finditer(text or ""))
+ return list(dict.fromkeys(name for name in names if _is_variable_reference(name)))
+
+
+def sql_referenced_names(sql: str | None) -> list[str]:
+ """The variables a SQL query refers to, outside comments. `[[x]]` is a nested array, not a reference."""
+ substitution = substitute_sql(sql or "", {})
+ return list(dict.fromkeys([*substitution.unresolved, *substitution.in_strings]))
+
+
+def _is_sql_reference(name: str) -> bool:
+ return name in _SQL_TIME_PLACEHOLDERS or _is_variable_reference(name)
+
+
+def _backslashes_before(text: str, position: int) -> int:
+ count = 0
+ while position - count > 0 and text[position - count - 1] == "\\":
+ count += 1
+ return count
+
+
+def _is_escaped(text: str, position: int) -> bool:
+ return _backslashes_before(text, position) % 2 == 1
+
+
+def _filter_references(metric_filter: MetricsQueryFilter) -> Iterator[re.Match[str]]:
+ is_regex = metric_filter.op in (MetricsFilterOp.REGEX, MetricsFilterOp.NOT_REGEX)
+ for match in REFERENCE.finditer(metric_filter.value):
+ # In a regex, \$ is a literal dollar sign.
+ if _is_variable_reference(reference_name(match)) and not (
+ is_regex and _is_escaped(metric_filter.value, match.start())
+ ):
+ yield match
+
+
+def filter_referenced_names(filters: Iterable[MetricsQueryFilter] | None) -> list[str]:
+ return list(
+ dict.fromkeys(
+ reference_name(match) for metric_filter in filters or () for match in _filter_references(metric_filter)
+ )
+ )
+
+
+def regex_escape(value: str) -> str:
+ return "".join(f"\\{char}" if char in _REGEX_SPECIAL else char for char in value)
+
+
+def promql_string_escape(value: str, quote: str | None = '"') -> str:
+ if quote is None:
+ return value
+ if quote == "`":
+ # A raw string has no escapes.
+ if "`" in value:
+ raise ValueError("A value inside a backtick string cannot hold a backtick.")
+ return value
+ escaped = value.replace("\\", "\\\\").replace(quote, f"\\{quote}")
+ return "".join(_PROMQL_CONTROL_ESCAPES.get(char, char) for char in escaped)
+
+
[email protected](frozen=False)
+class _PromQLScanner:
+ """Finds the string that holds each reference in one pass, because references come in order."""
+
+ expr: str
+ index: int = 0
+ quote: str | None = None
+ in_regex: bool = False
+ in_replacement: bool = False
+ # The open brackets, each as [bracket, the function name before a parenthesis, the argument index].
+ groups: list[list[Any]] = dataclasses.field(default_factory=list)
+
+ def _function_name(self) -> str:
+ end = self.index
+ while end > 0 and self.expr[end - 1].isspace():
+ end -= 1
+ start = end
+ while start > 0 and (self.expr[start - 1].isalnum() or self.expr[start - 1] in "_:"):
+ start -= 1
+ return self.expr[start:end].lower()
+
+ def context_at(self, position: int) -> PromQLStringContext | None:
+ """None when the position is inside a `#` comment."""
+ expr = self.expr
+ while self.index < position:
+ char = expr[self.index]
+ if self.quote is not None:
+ if char == "\\" and self.quote != "`":
+ self.index += 2
+ continue
+ if char == self.quote:
+ self.quote = None
+ elif char == "#":
+ end = _LINE_END.search(expr, self.index)
+ self.index = len(expr) if end is None else end.start()
+ continue
+ elif char in "({":
+ self.groups.append([char, self._function_name() if char == "(" else "", 0])
+ elif char in ")}":
+ if self.groups and self.groups[-1][0] == ("(" if char == ")" else "{"):
+ self.groups.pop()
+ elif char == ",":
+ if self.groups:
+ self.groups[-1][2] += 1
+ elif char in "\"'`":
+ self.quote = char
+ before = self.index - 1
+ while before >= 0 and expr[before].isspace():
+ before -= 1
+ call = self.groups[-1] if self.groups else None
+ after_matcher = before >= 1 and expr[before] == "~" and expr[before - 1] in "=!"
+ self.in_regex = after_matcher or call == ["(", "label_replace", 4]
+ self.in_replacement = call == ["(", "label_replace", 2]
+ self.index += 1
+ if self.quote is None and self.index > position:
+ return None
+ return PromQLStringContext(
+ quote=self.quote,
+ in_regex=self.quote is not None and self.in_regex,
+ in_replacement=self.quote is not None and self.in_replacement,
+ )
+
+
+def _has_value(variable: Variable | None) -> bool:
+ return variable is not None and (bool(variable.values) or variable.is_all)
+
+
+def from_dashboard(definitions: Iterable[MetricsDashboardVariable] | None) -> dict[str, Variable]:
+ """A variable with no selection is left out."""
+ variables: dict[str, Variable] = {}
+ for definition in definitions or ():
+ current = definition.current
+ if current is None:
+ continue
+ variable = Variable(
+ values=tuple(str(value) for value in current.values),
+ is_all=bool(current.all) and bool(definition.includeAll),
+ all_value=definition.allValue or None,
+ options=(),
+ )
+ if _has_value(variable):
+ variables[definition.name] = variable
+ return variables
+
+
+def from_query(values: Mapping[str, MetricsVariableValue] | None) -> dict[str, Variable]:
+ return {
+ name: Variable(values=tuple(value.values), is_all=bool(value.all), all_value=value.allValue or None, options=())
+ for name, value in (values or {}).items()
+ }
+
+
+def to_query(variables: Mapping[str, Variable], names: Iterable[str]) -> dict[str, MetricsVariableValue]:
+ """The values to set on a metrics query: only the variables it refers to, so the others do not reach its cache key."""
+ return {
+ name: MetricsVariableValue(
+ values=list(variable.values), all=variable.is_all or None, allValue=variable.all_value
+ )
+ for name in names
+ if (variable := variables.get(name)) is not None
+ }
+
+
+def with_values(variable: Variable, values: Iterable[str]) -> Variable:
+ return dataclasses.replace(variable, values=tuple(values))
+
+
+def format_promql(variable: Variable, value_format: str | None, *, context: PromQLStringContext) -> str:
+ if variable.is_all:
+ if variable.all_value is not None:
+ if variable.all_value_as_written:
+ return variable.all_value
+ return promql_string_escape(variable.all_value, context.quote)
+ if not variable.options:
+ return MATCH_ALL
+ values = variable.options
+ value_format = value_format or "regex"
+ else:
+ values = variable.values
+ if value_format in ("raw", "text", "csv"):
+ return promql_string_escape(",".join(values), context.quote)
+ if value_format == "pipe":
+ return promql_string_escape("|".join(values), context.quote)
+ if value_format == "regex" or context.in_regex or len(values) > 1:
+ escaped = [promql_string_escape(regex_escape(value), context.quote) for value in values]
+ return f"({'|'.join(escaped)})" if len(escaped) > 1 else escaped[0]
+ return promql_string_escape(values[0], context.quote)
+
+
+def substitute_promql(expr: str, variables: Mapping[str, Variable], *, keep: Collection[str] = ()) -> Substitution:
+ """References to the names in `keep` stay in the text."""
+ unresolved: list[str] = []
+ scanner = _PromQLScanner(expr)
+
+ def replace(match: re.Match[str]) -> str:
+ name = reference_name(match)
+ if not _is_variable_reference(name) or name in keep:
+ return match.group(0)
+ context = scanner.context_at(match.start())
+ if context is None:
+ return match.group(0)
+ # A regex reads `\$` as a literal dollar sign. A quoted string writes that backslash as `\\`.
+ if context.in_regex:
+ backslashes = _backslashes_before(expr, match.start())
+ if (backslashes if context.quote == "`" else backslashes // 2) % 2 == 1:
+ return match.group(0)
+ variable = variables.get(name)
+ if variable is None and context.in_replacement:
+ return match.group(0)
+ if variable is None or not _has_value(variable):
+ unresolved.append(name)
+ return match.group(0)
+ # In a regex matcher, a dot in a selected value such as an IP address must stay a dot.
+ return format_promql(variable, match.group("braced_format") or match.group("bracketed_format"), context=context)
+
+ return Substitution(text=REFERENCE.sub(replace, expr), unresolved=tuple(dict.fromkeys(unresolved)))
+
+
+def _quoted_end(sql: str, start: int) -> int:
+ """The index after the closing quote of the string or quoted identifier that starts at `start`."""
+ quote = sql[start]
+ index = start + 1
+ while index < len(sql):
+ char = sql[index]
+ if char == "\\":
+ index += 2
+ continue
+ if char == quote:
+ if sql.startswith(quote, index + 1):
+ index += 2
+ continue
+ return index + 1
+ index += 1
+ return len(sql)
+
+
+def _comment_end(sql: str, start: int) -> int | None:
+ # HogQL reads `#` followed by a digit as a token, not as a comment.
+ if sql.startswith(("--", "//"), start) or (sql.startswith("#", start) and not sql[start + 1 : start + 2].isdigit()):
+ line_end = _LINE_END.search(sql, start)
+ return len(sql) if line_end is None else line_end.start()
+ if sql.startswith("/*", start):
+ end = sql.find("*/", start + 2)
+ return len(sql) if end < 0 else end + 2
+ return None
+
+
+def _sql_placeholder(name: str, variable: Variable) -> ast.Expr:
+ if variable.is_all and not variable.values:
+ raise ValueError(f"${name} is set to All, but its values are not known. Select values for ${name}.")
+ if len(variable.values) == 1 and not variable.is_all:
+ return ast.Constant(value=variable.values[0])
+ return ast.Tuple(exprs=[ast.Constant(value=value) for value in variable.values])
+
+
+def substitute_sql(sql: str, variables: Mapping[str, Variable]) -> SqlSubstitution:
+ """Change each variable reference in a SQL query to a HogQL placeholder that holds its value.
+
+ One value becomes a string constant and more than one value, or All, becomes a tuple, so write
+ `job = $job` or `job IN $job`. A string that holds only a reference (`'$job'`) is one value, as in
+ Grafana. A reference inside a longer string is an error, because a value is never SQL text.
+ """
+ parts: list[str] = []
+ placeholders: dict[str, ast.Expr] = {}
+ unresolved: list[str] = []
+ in_strings: list[str] = []
+
+ def placeholder(name: str) -> str:
+ if name in _SQL_TIME_PLACEHOLDERS:
+ return f"{{{_SQL_TIME_PLACEHOLDERS[name]}}}"
+ variable = variables.get(name)
+ if variable is None or not _has_value(variable):
+ unresolved.append(name)
+ return f"${name}"
+ key = f"metric_variable_{name}"
+ placeholders[key] = _sql_placeholder(name, variable)
+ return f"{{{key}}}"
+
+ index = 0
+ while index < len(sql):
+ char = sql[index]
+ if (comment_end := _comment_end(sql, index)) is not None:
+ parts.append(sql[index:comment_end])
+ index = comment_end
+ continue
+ if char in "'\"`":
+ end = _quoted_end(sql, index)
+ literal = sql[index:end]
+ if char == "'":
+ whole = _SQL_REFERENCE.fullmatch(literal[1:-1])
+ if whole is None:
+ in_strings.extend(name for name in referenced_names(literal) if name not in _SQL_TIME_PLACEHOLDERS)
+ names = [name for name in referenced_names(literal) if name in variables]
+ # A string that holds only a reference is a variable, so a missing selection is reported.
+ if whole is not None and _is_sql_reference(whole.group("braced") or whole.group("plain")):
+ parts.append(placeholder(whole.group("braced") or whole.group("plain")))
+ index = end
+ continue
+ if names:
+ raise ValueError(
+ f"${names[0]} is inside a string. Put it outside the quotes, "
+ f"for example concat('prefix-', ${names[0]})."
+ )
+ parts.append(literal)
+ index = end
+ continue
+ match = _SQL_REFERENCE.match(sql, index)
+ previous = sql[index - 1] if index else ""
+ # A reference after a dot or inside a name (properties.$browser) is a field, not a variable.
+ if match is not None and not (previous.isalnum() or previous in "_.$"):
+ name = match.group("braced") or match.group("plain")
+ if _is_sql_reference(name):
+ parts.append(placeholder(name))
+ index = match.end()
+ continue
+ parts.append(char)
+ index += 1
+
+ return SqlSubstitution(
+ sql="".join(parts),
+ placeholders=placeholders,
+ unresolved=tuple(dict.fromkeys(unresolved)),
+ in_strings=tuple(dict.fromkeys(in_strings)),
+ )
+
+
+def _anchored_alternation(values: Iterable[str]) -> str:
+ return f"^(?:{'|'.join(regex_escape(value) for value in values)})$"
+
+
+def substitute_filter(metric_filter: MetricsQueryFilter, variables: Mapping[str, Variable]) -> FilterSubstitution:
+ negated = metric_filter.op in (MetricsFilterOp.NEQ, MetricsFilterOp.NOT_REGEX)
+ is_regex = metric_filter.op in (MetricsFilterOp.REGEX, MetricsFilterOp.NOT_REGEX)
+ match = REFERENCE.fullmatch(metric_filter.value)
+ if match is not None and _is_variable_reference(reference_name(match)):
+ name = reference_name(match)
+ variable = variables.get(name)
+ if variable is None or not _has_value(variable):
+ return FilterSubstitution(filter=metric_filter, unresolved=(name,))
+ regex_op = MetricsFilterOp.NOT_REGEX if negated else MetricsFilterOp.REGEX
+ if variable.is_all:
+ if variable.all_value is not None:
+ return FilterSubstitution(
+ filter=metric_filter.model_copy(update={"op": regex_op, "value": variable.all_value}),
+ unresolved=(),
+ )
+ if not negated:
+ return FilterSubstitution(filter=None, unresolved=())
+ return FilterSubstitution(
+ filter=metric_filter.model_copy(update={"op": regex_op, "value": MATCH_ALL}), unresolved=()
+ )
+ if len(variable.values) == 1 and not is_regex:
+ return FilterSubstitution(
+ filter=metric_filter.model_copy(update={"value": variable.values[0]}), unresolved=()
+ )
+ return FilterSubstitution(
+ filter=metric_filter.model_copy(update={"op": regex_op, "value": _anchored_alternation(variable.values)}),
+ unresolved=(),
+ )
+
+ unresolved: list[str] = []
+ parts: list[str] = []
+ end = 0
+ for inner in _filter_references(metric_filter):
+ name = reference_name(inner)
+ parts.append(metric_filter.value[end : inner.start()])
+ end = inner.end()
+ variable = variables.get(name)
+ if variable is None or not _has_value(variable):
+ unresolved.append(name)
+ parts.append(inner.group(0))
+ elif is_regex and variable.is_all:
+ parts.append(variable.all_value or MATCH_ALL)
+ elif is_regex:
+ parts.append(f"(?:{'|'.join(regex_escape(value) for value in variable.values)})")
+ else:
+ parts.append(",".join(variable.values))
+ value = "".join(parts) + metric_filter.value[end:]
+ return FilterSubstitution(
+ filter=metric_filter.model_copy(update={"value": value}), unresolved=tuple(dict.fromkeys(unresolved))
+ )
+
+
+def substitute_filters(
+ filters: Iterable[MetricsQueryFilter] | None, variables: Mapping[str, Variable]
+) -> FiltersSubstitution:
+ kept: list[MetricsQueryFilter] = []
+ unresolved: list[str] = []
+ for metric_filter in filters or ():
+ substitution = substitute_filter(metric_filter, variables)
+ unresolved.extend(substitution.unresolved)
+ if substitution.filter is not None:
+ kept.append(substitution.filter)
+ return FiltersSubstitution(filters=kept, unresolved=tuple(dict.fromkeys(unresolved)))
+
+
+def unresolved_message(names: Iterable[str]) -> str:
+ listed = ", ".join(f"${name}" for name in names)
+ return (
+ f"The query refers to {listed}, which has no value. "
+ "Open it from a dashboard that defines the variable, or select a value."
+ )
diff --git a/products/product_analytics/frontend/generated/api.schemas.ts b/products/product_analytics/frontend/generated/api.schemas.ts
index 98e605cd8c8a..4aecc3199dc4 100644
--- a/products/product_analytics/frontend/generated/api.schemas.ts
+++ b/products/product_analytics/frontend/generated/api.schemas.ts
@@ -8721,6 +8721,41 @@ export interface MetricsQueryFilterApi {
value: string
}
+export interface MetricsDashboardVariableSelectionApi {
+ all?: boolean | null
+ /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
+ values: string[]
+}
+
+export type MetricsDashboardVariableSourceApi =
+ (typeof MetricsDashboardVariableSourceApi)[keyof typeof MetricsDashboardVariableSourceApi]
+
+export const MetricsDashboardVariableSourceApi = {
+ Custom: 'custom',
+ Promql: 'promql',
+ Sql: 'sql',
+ Textbox: 'textbox',
+} as const
+
+export interface MetricsDashboardVariableApi {
+ /** The text that All puts in a PromQL query. `.*` when it is empty. */
+ allValue?: string | null
+ current?: MetricsDashboardVariableSelectionApi | null
+ /** The options when `source` is `custom`. */
+ customValues?: string[] | null
+ includeAll?: boolean | null
+ /** Shown in the dashboard filter bar. The name is shown when it is empty. */
+ label?: string | null
+ multi?: boolean | null
+ /** Letters, digits and underscores. Tiles refer to it as `$name`. */
+ name: string
+ /** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
+ query?: string | null
+ /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
+ regex?: string | null
+ source: MetricsDashboardVariableSourceApi
+}
+
export interface DashboardFilterApi {
breakdown_filter?: BreakdownFilterApi | null
/** Period comparison forced onto every insight that supports one. Absent/null = inherit. */
@@ -8734,6 +8769,8 @@ export interface DashboardFilterApi {
interval?: IntervalTypeApi | null
/** Metric label matchers ANDed into every metrics tile. Other tiles ignore them. */
metricFilters?: MetricsQueryFilterApi[] | null
+ /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
+ metricVariables?: MetricsDashboardVariableApi[] | null
properties?:
| (
| EventPropertyFilterApi
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 0f3c5792ff2f..6cd49c4bd80b 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -3409,6 +3409,41 @@ export namespace Schemas {
value: string;
}
+ export interface MetricsDashboardVariableSelection {
+ all?: boolean | null;
+ /** The selected values. Empty when `all` is true: All stands for every option of the variable. */
+ values: string[];
+ }
+
+ export type MetricsDashboardVariableSource = typeof MetricsDashboardVariableSource[keyof typeof MetricsDashboardVariableSource];
+
+
+ export const MetricsDashboardVariableSource = {
+ Custom: 'custom',
+ Promql: 'promql',
+ Sql: 'sql',
+ Textbox: 'textbox',
+ } as const;
+
+ export interface MetricsDashboardVariable {
+ /** The text that All puts in a PromQL query. `.*` when it is empty. */
+ allValue?: string | null;
+ current?: MetricsDashboardVariableSelection | null;
+ /** The options when `source` is `custom`. */
+ customValues?: string[] | null;
+ includeAll?: boolean | null;
+ /** Shown in the dashboard filter bar. The name is shown when it is empty. */
+ label?: string | null;
+ multi?: boolean | null;
+ /** Letters, digits and underscores. Tiles refer to it as `$name`. */
+ name: string;
+ /** The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column. */
+ query?: string | null;
+ /** RE2 pattern that options must match. When it has a capture group, the option is the first group. */
+ regex?: string | null;
+ source: MetricsDashboardVariableSource;
+ }
+
export interface EventPropertyFilter {
key: string;
label?: string | null;
@@ -3694,6 +3729,8 @@ export namespace Schemas {
interval?: IntervalType | null;
/** Metric label matchers ANDed into every metrics tile. Other tiles ignore them. */
metricFilters?: MetricsQueryFilter[] | null;
+ /** Variables that metrics tiles refer to as `$name`. Other tiles ignore them. */
+ metricVariables?: MetricsDashboardVariable[] | null;
properties?: (EventPropertyFilter | PersonPropertyFilter | PersonMetadataPropertyFilter | ElementPropertyFilter | EventMetadataPropertyFilter | SessionPropertyFilter | CohortPropertyFilter | RecordingPropertyFilter | LogEntryPropertyFilter | GroupPropertyFilter | FeaturePropertyFilter | FlagPropertyFilter | HogQLPropertyFilter | EmptyPropertyFilter | DataWarehousePropertyFilter | DataWarehousePersonPropertyFilter | ErrorTrackingIssueFilter | LogPropertyFilter | MetricPropertyFilter | SpanPropertyFilter | RevenueAnalyticsPropertyFilter | AccountCustomPropertyFilter | WorkflowVariablePropertyFilter | BehavioralPropertyFilter)[] | null;
}
@@ -58345,6 +58382,18 @@ export namespace Schemas {
warnings?: (DataWarehouseSyncWarning | AccessControlFilterWarning)[] | null;
}
+ export interface MetricsVariableValue {
+ /** True when the variable is set to All. PromQL gets `allValue` or `.*`, builder filters drop the filter, and SQL gets `values`. */
+ all?: boolean | null;
+ allValue?: string | null;
+ values: string[];
+ }
+
+ /**
+ * Values of the dashboard variables that the PromQL, SQL or filters refer to as `$name`.
+ */
+ export type MetricsQueryVariables = {[key: string]: MetricsVariableValue} | null;
+
export interface MetricsQuery {
/** Empty when `language` is `promql` or `sql`. */
clauses: MetricsQueryClause[];
@@ -58367,6 +58416,8 @@ export namespace Schemas {
/** HogQL SELECT over the posthog.metric* tables. Used when `language` is `sql`. It must return a `time` and a `value` column; every other column is a series label. `{date_from}`, `{date_to}`, `{interval}` and `{interval_seconds}` are filled in from the date range and interval. */
sql?: string | null;
tags?: QueryLogTags | null;
+ /** Values of the dashboard variables that the PromQL, SQL or filters refer to as `$name`. */
+ variables?: MetricsQueryVariables;
/** version of the node, used for schema migrations */
version?: number | null;
}
@@ -58399,6 +58450,11 @@ export namespace Schemas {
warnings?: (DataWarehouseSyncWarning | AccessControlFilterWarning)[] | null;
}
+ /**
+ * Values of the dashboard variables that the filters refer to as `$name`.
+ */
+ export type MetricsHistogramQueryVariables = {[key: string]: MetricsVariableValue} | null;
+
export interface MetricsHistogramQuery {
/** Defaults to the last 24 hours when omitted; dashboard date filters override it */
dateRange?: DateRange | null;
@@ -58415,6 +58471,8 @@ export namespace Schemas {
tags?: QueryLogTags | null;
/** UCUM unit for the y-axis bounds, e.g. "s", "ms". Presentation only. */
unit?: string | null;
+ /** Values of the dashboard variables that the filters refer to as `$name`. */
+ variables?: MetricsHistogramQueryVariables;
/** version of the node, used for schema migrations */
version?: number | null;
}
diff --git a/services/mcp/src/generated/endpoints/api.ts b/services/mcp/src/generated/endpoints/api.ts
index d1251fbd3c94..7b24a4bef50b 100644
--- a/services/mcp/src/generated/endpoints/api.ts
+++ b/services/mcp/src/generated/endpoints/api.ts
@@ -475,6 +475,59 @@ export const EndpointsRunCreateBody = () => zod.object({
])
.optional()
.describe('Metric label matchers ANDed into every metrics tile. Other tiles ignore them.'),
+ metricVariables: zod
+ .union([
+ zod.array(
+ zod.object({
+ allValue: zod
+ .union([zod.string(), zod.null()])
+ .optional()
+ .describe('The text that All puts in a PromQL query. `.\*` when it is empty.'),
+ current: zod
+ .union([
+ zod.object({
+ all: zod.union([zod.boolean(), zod.null()]).optional(),
+ values: zod
+ .array(zod.string())
+ .describe(
+ 'The selected values. Empty when `all` is true: All stands for every option of the variable.'
+ ),
+ }),
+ zod.null(),
+ ])
+ .optional(),
+ customValues: zod
+ .union([zod.array(zod.string()), zod.null()])
+ .optional()
+ .describe('The options when `source` is `custom`.'),
+ includeAll: zod.union([zod.boolean(), zod.null()]).optional(),
+ label: zod
+ .union([zod.string(), zod.null()])
+ .optional()
+ .describe('Shown in the dashboard filter bar. The name is shown when it is empty.'),
+ multi: zod.union([zod.boolean(), zod.null()]).optional(),
+ name: zod
+ .string()
+ .describe('Letters, digits and underscores. Tiles refer to it as `$name`.'),
+ query: zod
+ .union([zod.string(), zod.null()])
+ .optional()
+ .describe(
+ 'The options query when `source` is `promql` or `sql`. It can refer to other variables. PromQL supports `label_values(label)`, `label_values(selector, label)`, `label_names()`, `metrics(regex)` and `query_result(expr)`. SQL returns the options in its first column.'
+ ),
+ regex: zod
+ .union([zod.string(), zod.null()])
+ .optional()
+ .describe(
+ 'RE2 pattern that options must match. When it has a capture group, the option is the first group.'
+ ),
+ source: zod.enum(['custom', 'promql', 'sql', 'textbox']),
+ })
+ ),
+ zod.null(),
+ ])
+ .optional()
+ .describe('Variables that metrics tiles refer to as `$name`. Other tiles ignore them.'),
properties: zod
.union([
zod.array(