Insights (dw-insights)

The Insights agent answers business questions against your warehouse in plain language: it translates the question to SQL, executes it read-only, and returns structured results with a narrative — key findings, trends, and recommended next steps. It supports conversational follow-ups within a session, so “now break that down by region” works without restating the question.

What separates it from a generic NL-to-SQL tool is discipline. The agent works like a senior data scientist who has been burned by a dashboard that lied: it pins the metric’s definition, grain, and time window before querying, resolves metric definitions against the catalog rather than re-deriving them, and pre-registers confirmatory analyses before slicing. A surprising number gets root-caused — denominator change, join fan-out, late-arriving data, or real signal — before it’s allowed to become a conclusion. It would rather tell you “we can’t tell yet” than ship a false driver.

Key capabilities

• Natural-language queries. query_data_nl turns a business question into SQL, executes it read-only, and returns structured results — with the generated SQL visible for inspection, and session context for follow-ups.
• Insight narratives. generate_insight analyzes query results into findings, trends, and actionable recommendations — shipped only after the number is reproduced.
• Anomaly explanation. explain_anomaly produces a business-language explanation of a metric anomaly, with possible causes and suggested actions.
• Pre-registered analysis plans. register_analysis_plan freezes the hypothesis, primary metric, and planned cuts before the first confirmatory query; cuts discovered mid-analysis are labeled exploratory until re-tested.
• Alerts and schedules. create_alert and schedule_insight keep a verified metric watched, so a regression doesn’t go unnoticed; export_insight ships the finding.
• Catalog-resolved metrics. Metric definitions come from the Catalog & Context agent, so your number matches the rest of the company’s.

Example prompts

“Why is weekly activation down? Define the metric first, then show me the decomposition.”

“Pre-register this analysis: hypothesis, primary metric, and the three cuts we agreed on.”

“Revenue per account spiked 18% this week — explain the anomaly before we celebrate.”

“Turn yesterday’s churn query into a weekly scheduled insight with an alert on regression.”

Connect it to your stack

• Warehouses — Snowflake, BigQuery, Databricks: where the questions get answered.
• Catalog and semantic context — dbt, DataHub, and the rest of the connector catalog supply the metric definitions and lineage the rigor depends on.

Works before you connect anything

The agent starts in 🟡 Evaluation on a built-in sample estate — you can ask questions, generate insights, and walk the full pre-registration workflow before any credential exists. It earns 🟢 Connected per system through a passing live test. See Verify your setup.

Limits, honestly

• Read-only, by design. query_data_nl executes read-only queries against governed, modeled tables. This agent never mutates your warehouse.
• NL-to-SQL is generation, not magic: the agent inspects the generated SQL for join grain and grouping before trusting the rows, and you can too — the SQL is always shown.
• The rigor rules cut both ways: a cut you didn’t pre-register comes back labeled exploratory, and a number without a reproduced query and an interval won’t be reported as a finding. If you want fast unlabeled slices, this agent will push back.
• Answer quality is bounded by catalog coverage: where no canonical metric definition exists, the agent states the definition it chose rather than pretending there was one.