Natural Language Data Agent

A conversational data agent that turns plain-English questions into verified SQL queries, pipeline diagnostics, and team visibility, grounded in the same versioned contracts engineers already maintain.

The Problem

Data teams maintain detailed documentation: schema contracts, pipeline definitions, lineage graphs, and domain READMEs. But that knowledge is rarely accessible to the people who need it most.

Analysts spend hours tracking down the right table. Engineers context-switch during critical incidents to piece together upstream dependencies. Engineering managers lose visibility into what shipped and what is at risk.

This agent was built to serve all three audiences from a single unified interface, without requiring any of them to know where the documentation lives or how to navigate complex metadata portals.

---

How It Works

Every message goes through a structured orchestration pipeline: intent is classified first, then the right schema documentation is retrieved and validated, and finally a response is generated using a domain-tested template matched to the query type.

Classifying intent before searching is the key architectural decision. It ensures the agent retrieves only the documentation relevant to the question, keeping responses highly accurate and the LLM context window focused.

---

Intent Classification

The agent handles six distinct query types, each mapped to a dedicated search strategy and response template.

Routing before retrieval means the agent never searches blindly. Each query type targets the exact subset of documentation most likely to contain the authoritative answer.

---

For Analysts: Self-Serve Data Access

Analysts often know what business metrics they want to understand but not how to construct the join logic across normalized warehouse tables. The agent handles schema discovery and SQL generation so analysts can go from question to query without involving engineering.

A pre-generation validation step catches the most common failure modes: wrong table references, incorrect date granularity, and mismatched column types, before any SQL reaches the analyst.

Safe Execution & Byte Scan Estimation

The agent supports optional query execution against cloud data warehouses but always displays a compute cost estimate first. No query runs without explicit confirmation.

At enterprise data scale, a single unconstrained query can scan terabytes unexpectedly. Treating execution as opt-in aligns with how cost-conscious engineering organizations manage cloud data spend.

---

For Engineers: Pipeline Debugging

When a pipeline fails or data looks stale, the first questions are always the same: which upstream table is the source, when did it last refresh, and what transformation sits between raw ingestion and the final output?

Previously, answering those questions meant cross-referencing dbt models, checking scheduler logs, and tracing dependencies manually across multiple systems. The agent consolidates that into a single query.

A typical lineage response surfaces:

• Upstream sources: which raw or staging tables feed the model
• Refresh schedule: how frequently the pipeline runs and the expected SLA
• Last known run: timestamp of the most recent successful load
• Owner: the team or individual responsible for the pipeline

This matters most during incidents. An engineer can confirm within seconds whether the problem is in the transformation logic or whether an upstream dependency simply has not refreshed yet. That distinction alone reduces on-call triage time significantly.

---

For Engineering Managers: Work Visibility and PR Review

The agent is not limited to data queries. Because it already has access to the repositories that hold contracts, pipeline code, and documentation, it can serve engineering managers as a lightweight work tracking and code review tool without any additional integration.

Tracking Work in Progress

Rather than navigating pull request lists or interrupting the team for status updates, the EM gets a structured summary: what changed, who owns it, and which tables or domains are affected.

PR Review Assistance

The agent accelerates the first pass of a review: understanding what the PR is trying to do, whether it aligns with the existing contract, and which questions are worth raising. This is particularly useful for EMs reviewing work across multiple domains where keeping the full context of every table and pipeline in memory is not realistic.

---

Why Source Control as the Knowledge Source

Data contracts and schema documentation live in many places: wikis, spreadsheets, internal portals, Slack threads. Most of these are stale within weeks of a schema change.

Source control is different. When a table is modified, the contract file gets updated as part of the same pull request that changes the pipeline. The documentation in source control reflects the actual deployed state of the data, not what someone intended to write six months ago.

Grounding the agent in source control provided three concrete guarantees:

• Accuracy: schema definitions match what is in production, because they go through the same review process as the code.
• Ownership: every contract file has a clear team owner, making it straightforward to surface the right contact when documentation is incomplete.
• Auditability: users can follow the citation link and see the exact file and version the agent used to generate a response.

---

Results & Impact

Persona	Before	After
Analyst	Schema lookups required data team involvement	Self-serve discovery and SQL generation in seconds
Analyst	No visibility into query cost before execution	Byte scan estimate shown before every run
Engineer	Lineage required manual cross-referencing across tools	Upstream dependencies and refresh status returned inline
EM	Work visibility required interrupting the team	Structured summaries of changes and ownership on demand
EM	PR reviews required full context of every domain	First-pass review accelerated with contract-aware summaries

The most significant shift was making the documentation that engineers already maintain directly useful to everyone who depends on it, without any extra tooling or overhead.