Claude Code + Data Science Agent: Accurate Text-to-SQL with Semantic Grounding

The Claude Code data science agent is an MCP server from Data Workers that generates accurate text-to-SQL by grounding every query in your semantic layer, business definitions, and live schema. It eliminates the hallucinations that plague generic LLMs by injecting your data context before the model writes a single line.

The Claude Code data science agent generates accurate SQL from natural language questions by grounding every query in your semantic layer definitions, business logic, and data context. Text-to-SQL is the most requested AI feature in data — and the most disappointing. Generic LLMs write syntactically correct SQL that is semantically wrong because they do not know what your data means. The data science agent from Data Workers is an MCP server that solves this by giving Claude Code access to your full semantic context before generating any query.

Google's benchmarks show that LLM-generated queries are 66% less accurate without semantic grounding. That statistic matches what every data team discovers when they try text-to-SQL: the AI writes a query that runs, returns a number, and that number is wrong because the AI used the wrong revenue definition, forgot a mandatory filter, or joined tables incorrectly. The data science agent eliminates these errors by ensuring Claude Code understands your data before writing SQL.

Why Generic Text-to-SQL Fails

Consider a simple question: "What was revenue last quarter?" A generic LLM might generate SELECT SUM(amount) FROM orders WHERE created_at >= '2026-01-01'. This query has multiple problems that are invisible without business context:

• •Is amount gross or net revenue? The business reports net revenue, but amount is gross.
• •Should cancelled orders be excluded? There is no WHERE status != 'cancelled' filter.
• •Is created_at the order date or the payment date? Revenue recognition uses payment date.
• •What about refunds? They live in a separate table that needs to be joined and subtracted.
• •Does "last quarter" mean calendar quarter or fiscal quarter? The company uses a non-standard fiscal calendar.

A generic LLM cannot know any of this. It sees table names and column names and makes its best guess. The data science agent knows all of this because it reads your semantic layer, dbt documentation, metric definitions, and business logic before generating a single line of SQL.

How Semantic Grounding Works

When you ask a question through Claude Code, the data science agent follows a multi-step process:

• •Intent parsing: Understands what business concept you are asking about (revenue, churn, conversion, etc.)
• •Semantic lookup: Retrieves the formal definition of that concept from your semantic layer — including the correct tables, columns, filters, and aggregation logic
• •Context enrichment: Pulls additional context like mandatory filters (e.g., is_deleted = false), timezone conventions, fiscal calendar definitions, and known data quality caveats
• •Query generation: Writes SQL that implements the semantic definition exactly, not an approximation based on column names
• •Validation: Checks the generated query against known constraints and test cases before returning it

The result is SQL that a senior analyst on your team would write — because it encodes the same institutional knowledge they carry.

Real Scenario: Revenue Analysis from Natural Language

Here is the same revenue question, but through the data science agent:

claude "What was net revenue last quarter by customer segment?"

The agent generates:

SELECT c.segment, SUM(p.amount - COALESCE(r.refund_amount, 0)) AS net_revenue FROM fct_payments p JOIN dim_customers c ON p.customer_id = c.customer_id LEFT JOIN fct_refunds r ON p.payment_id = r.payment_id WHERE p.payment_date >= '2026-01-01' AND p.payment_date < '2026-04-01' AND p.status = 'completed' GROUP BY c.segment ORDER BY net_revenue DESC

Notice the differences from the naive query: it uses fct_payments (not orders), subtracts refunds, filters by payment_date (not created_at), excludes non-completed payments, and uses the correct fiscal quarter dates. Every decision was driven by your semantic layer definitions, not by guessing.

Interactive Data Exploration

The data science agent supports iterative analysis, not just one-shot queries. You can explore your data conversationally:

• •claude "What was net revenue last quarter by customer segment?" — initial query
• •claude "Break that down by month" — the agent modifies the query, keeping all semantic context
• •claude "Why did Enterprise drop in March?" — the agent writes diagnostic queries to investigate
• •claude "Compare that to the same period last year" — year-over-year comparison with consistent definitions
• •claude "Create a summary table I can share with the CFO" — formatted output with context

Each follow-up question maintains the semantic grounding from the original query. The agent does not lose context between turns — it builds on the analysis progressively, just like working with a senior analyst.

Before and After: Text-to-SQL Accuracy

Connecting Your Semantic Layer

The data science agent integrates with your existing semantic layer — whether that is dbt metrics, Looker LookML, Cube.js, or custom metric definitions. If you do not have a formal semantic layer, the agent can bootstrap one from your dbt documentation and query history.

claude "Show me all the metric definitions you have for revenue" — lists every revenue metric with its SQL definition, owner, and documentation

claude "We calculate churn as customers who had activity last month but not this month. Save that as a metric definition." — the agent registers the definition for use in future queries

Over time, the agent builds a comprehensive semantic layer that captures your team's institutional knowledge. This layer is shared across all Data Workers agents, so the quality monitoring agent knows what "revenue" means when checking for anomalies, and the incident debugging agent knows which tables are business-critical.

Getting Started with Semantic Text-to-SQL

The data science agent works with any SQL warehouse and integrates with dbt, Looker, Cube.js, and custom semantic layers. Follow the Getting Started guide to install Data Workers and the Claude Code Setup guide to connect the agent to your stack.

Start by asking a business question you know the correct answer to — this lets you verify the agent's accuracy against your expectations. The Docs cover advanced features including custom metric registration, multi-dialect support, and query explanation mode. See all 15 agents on the Product page.

Stop fixing AI-generated SQL. Book a demo to see semantically grounded text-to-SQL on your own data.