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.

fix(insights): let mcp agents save promql and sql metrics insights (#128234)

Frank Hamand1971039a73e0
diff --git a/products/product_analytics/backend/presentation/insight.py b/products/product_analytics/backend/presentation/insight.py
index 5860e8a92765..7b7985a29af5 100644
--- a/products/product_analytics/backend/presentation/insight.py
+++ b/products/product_analytics/backend/presentation/insight.py
@@ -1559,6 +1559,10 @@ class InsightSerializer(InsightBasicSerializer):
return dashboard_tile
+def _pydantic_error_details(exc: PydanticValidationError) -> str:
+ return "; ".join(f"{'.'.join(str(part) for part in e['loc'])}: {e['msg']}" for e in exc.errors())
+
+
class MCPInsightSerializer(InsightSerializer):
"""Serializer for MCP insight create/update requests.
@@ -1623,11 +1627,20 @@ class MCPInsightSerializer(InsightSerializer):
pass
# A metrics insight saves its query bare, as the metrics editor and the metrics dashboard builders do
- for metrics_cls in (schema.MetricsQuery, schema.MetricsHistogramQuery):
+ metrics_classes: dict[str, type[schema.MetricsQuery] | type[schema.MetricsHistogramQuery]] = {
+ "MetricsQuery": schema.MetricsQuery,
+ "MetricsHistogramQuery": schema.MetricsHistogramQuery,
+ }
+ kind = value.get("kind") if value is not None else None
+ metrics_cls = metrics_classes.get(kind) if isinstance(kind, str) else None
+ if value is not None and metrics_cls is not None:
+ if value.get("language") in ("promql", "sql"):
+ # A PromQL or SQL metrics query has no builder clauses, but the schema still requires the field.
+ value = {**value, "clauses": value.get("clauses") or []}
try:
return metrics_cls.model_validate(value).model_dump(exclude_none=True, mode="json", by_alias=True)
- except PydanticValidationError:
- pass
+ except PydanticValidationError as exc:
+ raise serializers.ValidationError(f"This query can't be saved: {_pydantic_error_details(exc)}")
# Raw product analytics query → InsightVizNode
try:
@@ -1635,8 +1648,7 @@ class MCPInsightSerializer(InsightSerializer):
exclude_none=True, mode="json", by_alias=True
)
except PydanticValidationError as exc:
- details = "; ".join(f"{'.'.join(str(part) for part in e['loc'])}: {e['msg']}" for e in exc.errors())
- raise serializers.ValidationError(f"This query can't be saved: {details}")
+ raise serializers.ValidationError(f"This query can't be saved: {_pydantic_error_details(exc)}")
# Insights can be looked up by either the numeric primary key or the 8-character `short_id`
diff --git a/products/product_analytics/backend/tests/api/test_insight_query.py b/products/product_analytics/backend/tests/api/test_insight_query.py
index 3dff00da5361..530f2b48ac19 100644
--- a/products/product_analytics/backend/tests/api/test_insight_query.py
+++ b/products/product_analytics/backend/tests/api/test_insight_query.py
@@ -121,10 +121,30 @@ class TestMCPInsightSerializer(SimpleTestCase):
},
),
("metrics_histogram_query", {"kind": "MetricsHistogramQuery", "metricName": "http_request_duration"}),
+ (
+ "promql_without_clauses",
+ {"kind": "MetricsQuery", "language": "promql", "promql": "sum(rate(http_requests_total[5m]))"},
+ ),
+ (
+ "sql_without_clauses",
+ {"kind": "MetricsQuery", "language": "sql", "sql": "SELECT now() AS time, 1 AS value"},
+ ),
]
)
def test_keeps_metrics_queries_bare(self, _name: str, query: dict[str, Any]) -> None:
- assert MCPInsightSerializer().validate_query(query)["kind"] == query["kind"]
+ normalized_query = MCPInsightSerializer().validate_query(query)
+
+ assert normalized_query["kind"] == query["kind"]
+ assert normalized_query.get("promql") == query.get("promql")
+
+ @parameterized.expand([("list_kind", ["MetricsQuery"]), ("object_kind", {"kind": "MetricsQuery"})])
+ def test_rejects_a_kind_that_is_not_a_string(self, _name: str, kind: Any) -> None:
+ with self.assertRaises(serializers.ValidationError):
+ MCPInsightSerializer().validate_query({"kind": kind})
+
+ def test_explains_an_invalid_metrics_query_in_its_own_terms(self) -> None:
+ with self.assertRaisesRegex(serializers.ValidationError, r"clauses: Field required"):
+ MCPInsightSerializer().validate_query({"kind": "MetricsQuery", "dateRange": {"date_from": "-1h"}})
def test_assistant_schema_accepts_sql_box_plots(self) -> None:
query = schema.AssistantDataVisualizationNode.model_validate(
diff --git a/products/product_analytics/mcp/tools.yaml b/products/product_analytics/mcp/tools.yaml
index db816cc1f2b4..e52bee662371 100644
--- a/products/product_analytics/mcp/tools.yaml
+++ b/products/product_analytics/mcp/tools.yaml
@@ -90,6 +90,18 @@ tools:
`InsightVizNode`.
+ For a PromQL metrics insight, set `language` to `promql`, put the expression in `promql`, and send `clauses`
+ as an empty list. When query-metrics accepts a `promql` field, test the expression with it first:
+
+
+ ```json
+
+ { "name": "Request rate", "query": { "kind": "MetricsQuery", "language": "promql", "promql":
+ "sum(rate(http_requests_total[5m]))", "clauses": [], "dateRange": { "date_from": "-24h" } } }
+
+ ```
+
+
Choose the TrendsQuery `trendsFilter.display` from the question the insight answers:
- Change over time: `ActionsLineGraph` (default), `ActionsAreaGraph`, or `ActionsBar`.
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index dfd4c40525ce..a645a20ea141 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -8382,7 +8382,7 @@
}
},
"insight-create": {
- "description": "Create a new saved insight from a name and query definition. Test queries with query-trends / query-funnel /\nquery-retention / query-paths / query-stickiness / query-lifecycle first to confirm the shape, then save.\nReturns insight metadata only — after creating, call the insight-query tool with the returned `short_id` if\nyou want to see the computed results.\n\nPut the insight definition in `query.source`, under the wrapper node that matches it. Use\n`InsightVizNode` for a product analytics chart, `DataVisualizationNode` for a SQL visualization, and `DataTableNode` with an `EventsQuery` source for a table of individual events:\n\n```json\n{ \"name\": \"Example\", \"query\": { \"kind\": \"DataVisualizationNode\", \"source\": { \"kind\": \"HogQLQuery\", \"query\": \"SELECT 1\" } } }\n```\nBare `TrendsQuery`, `HogQLQuery`, and `EventsQuery` definitions are accepted too. They are wrapped for you, so a query you just ran through one of the `query-*` tools can be passed straight through.\n\nA saved SQL insight must follow the dashboard and insight date range. Before you save a `HogQLQuery`, replace its fixed date window, such as `timestamp >= now() - INTERVAL 30 DAY`, with the `{filters}` placeholder: `WHERE event = 'signed_up' AND {filters}`. Then put the requested window in `query.source.filters.dateRange`, for example `{\"date_from\": \"-30d\"}`. A fixed window ignores the date picker, and `{filters}` without a `dateRange` shows all time. `{filters}` also applies the property and test-account filters. For a table without a `timestamp` column, bind its date column with `{filters(created_at AS timestamp)}`.\n\nSave a `MetricsQuery` or `MetricsHistogramQuery` bare, as the top-level `query`. Do not put it in an `InsightVizNode`.\n\nChoose the TrendsQuery `trendsFilter.display` from the question the insight answers:\n- Change over time: `ActionsLineGraph` (default), `ActionsAreaGraph`, or `ActionsBar`.\n- Compare breakdown values or series as totals (\"top pages\", \"failures by reason\"): `ActionsBarValue`, or `ActionsPie` for the share of a whole with a few values.\n- One number for the period, or this period against the previous one: `Metric` with `compareFilter.compare: true` for a comparison, or `BoldNumber` when a trend has no meaning.\n- Many breakdown rows that a person reads rather than compares: `ActionsTable`.\n- Totals per country from a `$geoip_country_code` breakdown: `WorldMap`.\n\nIn a TrendsQuery, `ActionsBar` is a time series with one bar per interval and the breakdown values stacked in each bar. It is not one bar per category. In a SQL `DataVisualizationNode`, `ActionsBar` is one bar per X-axis value, and `ActionsBarValue` draws the same bars horizontally.",
+ "description": "Create a new saved insight from a name and query definition. Test queries with query-trends / query-funnel /\nquery-retention / query-paths / query-stickiness / query-lifecycle first to confirm the shape, then save.\nReturns insight metadata only — after creating, call the insight-query tool with the returned `short_id` if\nyou want to see the computed results.\n\nPut the insight definition in `query.source`, under the wrapper node that matches it. Use\n`InsightVizNode` for a product analytics chart, `DataVisualizationNode` for a SQL visualization, and `DataTableNode` with an `EventsQuery` source for a table of individual events:\n\n```json\n{ \"name\": \"Example\", \"query\": { \"kind\": \"DataVisualizationNode\", \"source\": { \"kind\": \"HogQLQuery\", \"query\": \"SELECT 1\" } } }\n```\nBare `TrendsQuery`, `HogQLQuery`, and `EventsQuery` definitions are accepted too. They are wrapped for you, so a query you just ran through one of the `query-*` tools can be passed straight through.\n\nA saved SQL insight must follow the dashboard and insight date range. Before you save a `HogQLQuery`, replace its fixed date window, such as `timestamp >= now() - INTERVAL 30 DAY`, with the `{filters}` placeholder: `WHERE event = 'signed_up' AND {filters}`. Then put the requested window in `query.source.filters.dateRange`, for example `{\"date_from\": \"-30d\"}`. A fixed window ignores the date picker, and `{filters}` without a `dateRange` shows all time. `{filters}` also applies the property and test-account filters. For a table without a `timestamp` column, bind its date column with `{filters(created_at AS timestamp)}`.\n\nSave a `MetricsQuery` or `MetricsHistogramQuery` bare, as the top-level `query`. Do not put it in an `InsightVizNode`.\n\nFor a PromQL metrics insight, set `language` to `promql`, put the expression in `promql`, and send `clauses` as an empty list. When query-metrics accepts a `promql` field, test the expression with it first:\n\n```json\n{ \"name\": \"Request rate\", \"query\": { \"kind\": \"MetricsQuery\", \"language\": \"promql\", \"promql\": \"sum(rate(http_requests_total[5m]))\", \"clauses\": [], \"dateRange\": { \"date_from\": \"-24h\" } } }\n```\n\nChoose the TrendsQuery `trendsFilter.display` from the question the insight answers:\n- Change over time: `ActionsLineGraph` (default), `ActionsAreaGraph`, or `ActionsBar`.\n- Compare breakdown values or series as totals (\"top pages\", \"failures by reason\"): `ActionsBarValue`, or `ActionsPie` for the share of a whole with a few values.\n- One number for the period, or this period against the previous one: `Metric` with `compareFilter.compare: true` for a comparison, or `BoldNumber` when a trend has no meaning.\n- Many breakdown rows that a person reads rather than compares: `ActionsTable`.\n- Totals per country from a `$geoip_country_code` breakdown: `WorldMap`.\n\nIn a TrendsQuery, `ActionsBar` is a time series with one bar per interval and the breakdown values stacked in each bar. It is not one bar per category. In a SQL `DataVisualizationNode`, `ActionsBar` is one bar per X-axis value, and `ActionsBarValue` draws the same bars horizontally.",
"category": "Product analytics",
"feature": "product_analytics",
"summary": "Create insight",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 6f7b3a08312b..b5ad174b0eca 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -8614,7 +8614,7 @@
}
},
"insight-create": {
- "description": "Create a new saved insight from a name and query definition. Test queries with query-trends / query-funnel /\nquery-retention / query-paths / query-stickiness / query-lifecycle first to confirm the shape, then save.\nReturns insight metadata only — after creating, call the insight-query tool with the returned `short_id` if\nyou want to see the computed results.\n\nPut the insight definition in `query.source`, under the wrapper node that matches it. Use\n`InsightVizNode` for a product analytics chart, `DataVisualizationNode` for a SQL visualization, and `DataTableNode` with an `EventsQuery` source for a table of individual events:\n\n```json\n{ \"name\": \"Example\", \"query\": { \"kind\": \"DataVisualizationNode\", \"source\": { \"kind\": \"HogQLQuery\", \"query\": \"SELECT 1\" } } }\n```\nBare `TrendsQuery`, `HogQLQuery`, and `EventsQuery` definitions are accepted too. They are wrapped for you, so a query you just ran through one of the `query-*` tools can be passed straight through.\n\nA saved SQL insight must follow the dashboard and insight date range. Before you save a `HogQLQuery`, replace its fixed date window, such as `timestamp >= now() - INTERVAL 30 DAY`, with the `{filters}` placeholder: `WHERE event = 'signed_up' AND {filters}`. Then put the requested window in `query.source.filters.dateRange`, for example `{\"date_from\": \"-30d\"}`. A fixed window ignores the date picker, and `{filters}` without a `dateRange` shows all time. `{filters}` also applies the property and test-account filters. For a table without a `timestamp` column, bind its date column with `{filters(created_at AS timestamp)}`.\n\nSave a `MetricsQuery` or `MetricsHistogramQuery` bare, as the top-level `query`. Do not put it in an `InsightVizNode`.\n\nChoose the TrendsQuery `trendsFilter.display` from the question the insight answers:\n- Change over time: `ActionsLineGraph` (default), `ActionsAreaGraph`, or `ActionsBar`.\n- Compare breakdown values or series as totals (\"top pages\", \"failures by reason\"): `ActionsBarValue`, or `ActionsPie` for the share of a whole with a few values.\n- One number for the period, or this period against the previous one: `Metric` with `compareFilter.compare: true` for a comparison, or `BoldNumber` when a trend has no meaning.\n- Many breakdown rows that a person reads rather than compares: `ActionsTable`.\n- Totals per country from a `$geoip_country_code` breakdown: `WorldMap`.\n\nIn a TrendsQuery, `ActionsBar` is a time series with one bar per interval and the breakdown values stacked in each bar. It is not one bar per category. In a SQL `DataVisualizationNode`, `ActionsBar` is one bar per X-axis value, and `ActionsBarValue` draws the same bars horizontally.",
+ "description": "Create a new saved insight from a name and query definition. Test queries with query-trends / query-funnel /\nquery-retention / query-paths / query-stickiness / query-lifecycle first to confirm the shape, then save.\nReturns insight metadata only — after creating, call the insight-query tool with the returned `short_id` if\nyou want to see the computed results.\n\nPut the insight definition in `query.source`, under the wrapper node that matches it. Use\n`InsightVizNode` for a product analytics chart, `DataVisualizationNode` for a SQL visualization, and `DataTableNode` with an `EventsQuery` source for a table of individual events:\n\n```json\n{ \"name\": \"Example\", \"query\": { \"kind\": \"DataVisualizationNode\", \"source\": { \"kind\": \"HogQLQuery\", \"query\": \"SELECT 1\" } } }\n```\nBare `TrendsQuery`, `HogQLQuery`, and `EventsQuery` definitions are accepted too. They are wrapped for you, so a query you just ran through one of the `query-*` tools can be passed straight through.\n\nA saved SQL insight must follow the dashboard and insight date range. Before you save a `HogQLQuery`, replace its fixed date window, such as `timestamp >= now() - INTERVAL 30 DAY`, with the `{filters}` placeholder: `WHERE event = 'signed_up' AND {filters}`. Then put the requested window in `query.source.filters.dateRange`, for example `{\"date_from\": \"-30d\"}`. A fixed window ignores the date picker, and `{filters}` without a `dateRange` shows all time. `{filters}` also applies the property and test-account filters. For a table without a `timestamp` column, bind its date column with `{filters(created_at AS timestamp)}`.\n\nSave a `MetricsQuery` or `MetricsHistogramQuery` bare, as the top-level `query`. Do not put it in an `InsightVizNode`.\n\nFor a PromQL metrics insight, set `language` to `promql`, put the expression in `promql`, and send `clauses` as an empty list. When query-metrics accepts a `promql` field, test the expression with it first:\n\n```json\n{ \"name\": \"Request rate\", \"query\": { \"kind\": \"MetricsQuery\", \"language\": \"promql\", \"promql\": \"sum(rate(http_requests_total[5m]))\", \"clauses\": [], \"dateRange\": { \"date_from\": \"-24h\" } } }\n```\n\nChoose the TrendsQuery `trendsFilter.display` from the question the insight answers:\n- Change over time: `ActionsLineGraph` (default), `ActionsAreaGraph`, or `ActionsBar`.\n- Compare breakdown values or series as totals (\"top pages\", \"failures by reason\"): `ActionsBarValue`, or `ActionsPie` for the share of a whole with a few values.\n- One number for the period, or this period against the previous one: `Metric` with `compareFilter.compare: true` for a comparison, or `BoldNumber` when a trend has no meaning.\n- Many breakdown rows that a person reads rather than compares: `ActionsTable`.\n- Totals per country from a `$geoip_country_code` breakdown: `WorldMap`.\n\nIn a TrendsQuery, `ActionsBar` is a time series with one bar per interval and the breakdown values stacked in each bar. It is not one bar per category. In a SQL `DataVisualizationNode`, `ActionsBar` is one bar per X-axis value, and `ActionsBarValue` draws the same bars horizontally.",
"category": "Product analytics",
"feature": "product_analytics",
"summary": "Create insight",