fix(phai): support SQL insights when adding to a dashboard

[andyzzhao]

Problem

PostHog AI can create SQL-backed insights (a DataVisualizationNode whose source is a HogQLQuery) through its execute_sql tool, but it could not add them to a dashboard.
When a user asked PostHog AI to add a SQL insight to a dashboard, the upsert_dashboard tool failed with a pydantic validation error:

1 validation error for InsightVizNode
source
  Input tag 'DataVisualizationNode' found using 'kind' does not match any of the expected tags: 'TrendsQuery', 'FunnelsQuery', 'RetentionQuery', 'PathsQuery', 'StickinessQuery', 'LifecycleQuery', 'WebStatsTableQuery', 'WebOverviewQuery'

PostHog AI then told the user that SQL-based insights are not supported on dashboards, even though it had just generated one. SQL insights were effectively a dead end for the dashboard flow.

Root cause: _resolve_insights coerces each artifact's query and wraps anything that is not a bare HogQLQuery in InsightVizNode. InsightVizNode.source is a discriminated union that does not include DataVisualizationNode, so SQL insights raised union_tag_invalid.

Changes

_resolve_insights now handles DataVisualizationNode explicitly. It is already a valid top-level insight query node (the shape native SQL insights are stored in), so it is saved as-is. This preserves the insight's display and chartSettings, keeping the chart configuration PostHog AI chose (line graph, axes) instead of flattening it. The bare HogQLQuery and InsightVizNode (trends, funnel, etc.) branches are unchanged.

if isinstance(coerced_query, DataVisualizationNode):
    converted = coerced_query.model_dump(exclude_none=True)
elif isinstance(coerced_query, HogQLQuery):
    converted = DataTableNode(source=coerced_query).model_dump(exclude_none=True)
else:
    converted = InsightVizNode(source=coerced_query).model_dump(exclude_none=True)

How did you test this code?

I am an agent. Automated tests I actually ran locally against the Postgres test database:

• Added test_resolve_insights_creates_sql_insight_from_data_visualization_node. It builds a SQL DataVisualizationNode artifact, runs it through _resolve_insights, and asserts the saved insight keeps kind: DataVisualizationNode, its HogQLQuery source, and the line graph display. I watched it fail first with the same union_tag_invalid error at the InsightVizNode(source=...) branch, then pass after the change.
• Ran the full ee/hogai/tools/upsert_dashboard/test/test_tool.py suite: 71 passed, no regressions.
• ruff check and ruff format on the changed files: clean.
• mypy on the changed test file: clean.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

Docs update

No docs changes needed.

🤖 Agent context

Authored by Claude (Opus 4.8) in a Claude Code session.

This began as a check of whether an unrelated MCP schema PR (#60526) addressed a problem observed in a PostHog AI conversation. It did not. That PR clarifies the external MCP insight-create tool schema (AssistantDataVisualizationNode), which PostHog AI does not use. Reconstructing the conversation showed the real blocker was the upsert_dashboard tool rejecting a SQL insight PostHog AI had already created.

Decisions:

• Verified PostHog AI generates SQL insights through its own SQLGeneratorNode path, which produces plain DataVisualizationNode and HogQLQuery, independent of the Assistant* schema types the MCP PR touches. So that PR could not have fixed this.
• Reproduced the failure with a unit test before changing any code, then made the minimal fix.
• Chose to persist the DataVisualizationNode directly rather than unwrap its HogQLQuery into a DataTableNode. Unwrapping would drop the display and chart settings; keeping the node matches how SQL insights are saved natively and renders correctly as a dashboard tile.

Tools used: Claude Code with Read, Grep, Bash, and Edit, plus Explore subagents for code navigation.

This is agent-authored and requires human review.

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix(max): support SQL insights when addi..." | Re-trigger Greptile}

[github-actions]

🎭 Playwright report · View test results →

⚠️ 1 flaky test:

• launch survey with event (chromium)

These issues are not necessarily caused by your changes.
Annoyed by this comment? Help fix flakies and failures and it'll disappear!

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-05-29 13:41 UTC	Run
prod-us	✅ Deployed	2026-05-29 14:09 UTC	Run
prod-eu	✅ Deployed	2026-05-29 14:12 UTC	Run