Skip to content
Data Workers Docs

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

Section titled “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

Section titled “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

Section titled “Connect it to your stack”

Works before you connect anything

Section titled “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

Section titled “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.