Skip to content
AI Engineer Guide.

concept · concepts · intermediate · concept 49 of 57

Structured RAG

0 of 57 complete

Why it matters

Questions like 'how many enterprise tickets were open at the end of the quarter' cannot be answered by retrieving a passage, because the answer does not exist as text until it is computed. Structured RAG turns the question into a query over a known schema, which is exact and auditable. The hard part is that the schema is large, the question is ambiguous and a syntactically valid query can compute the wrong thing.

Mental model

Structured RAG is a clerk translating a request into a form the records office accepts, then reading the result back. The metaphor breaks because the form can be filled in correctly and still ask the wrong question, and nothing in the records office will say so.

How it works

From question to executed queryInteractive

Synthetic analytics page · support operations

Curated schema · read-only replica

bounding boxes

Step 1/6 · No passage holds the answer

Step 1No passage holds the answer

Text retrieval returns policy pages that mention enterprise support, not a count. The answer does not exist as text until the query is executed.

ANALYTICS · SUPPORT OPERATIONS · READ-ONLY REPLICA

, running header, region 1. Select to inspect.

Open enterprise tickets at quarter end

, title, region 2. Select to inspect.
Text

“How many enterprise tickets were still open on 30 September 2026?”

, paragraph, region 3. Select to inspect.
SCHEMA VIEW
tickets(id, account_id, priority, opened_at, closed_at) accounts(id, plan, region) -- 7 curated tables, with types and join paths -- read-only role · row limit 1,000
, code block SCHEMA VIEW, region 4. Select to inspect.
GENERATED QUERY
SELECT count(*) AS open_tickets FROM tickets t JOIN accounts a ON a.id = t.account_id WHERE a.plan = 'enterprise' AND (t.closed_at IS NULL OR t.closed_at >= '2026-09-30') AND t.opened_at < '2026-10-01';
, code block GENERATED QUERY, region 5. Select to inspect.
VALIDATION
RuleResult
read-only statement✓pass
identifiers resolved✓pass
date bound present✓pass
row cap by role✓pass
, table VALIDATION, region 6. Select to inspect.
PENDING
No query has executed. The result, attempts and audit appear after validation. Validation must pass before the read-only query runs.
?, code block PENDING, region 8, needs review. Select to inspect.
7 regions

Step record

Passages found
policy excerpts
Contains the count
no
Computed answer
not yet

The text version summarises this figure; select a region for its full text.

Markspassneeds review

Figure. The question needs a computed answer, so the page supplies a curated schema, a generated query, two rejected attempts and the executed result. The validation rows are what a query must pass before it runs; the query, not the prose answer, is the auditable artefact.

What to notice. Synthetic schema and warehouse. Table names, counts and the execution time are illustrative. The figure shows the artefacts and the order of checks, not a text-to-SQL model's measured accuracy.

Text version

A synthetic analytics page for the question 'how many enterprise tickets were still open on 30 September 2026?'. A schema block lists the tickets and accounts tables and notes seven curated tables, a read-only role and a row limit. A generated SQL query joins tickets to accounts, filters on the enterprise plan, null closed_at and an opened_at date bound. A validation table passes four rules: read-only statement, resolved identifiers, a date bound and a row cap enforced by the role. A result table shows one row, open_tickets 1,284. An attempts table marks a delete attempt and an unbounded query as rejected and the final query as executed. An audit block records the query id, the row count and the schema version. The first five steps hide the result, answer, attempts, audit and footer and show a pending placeholder; the last step reveals the executed result.

  1. Publish a curated schema view: table and column names, types, descriptions and join paths, rather than the raw catalogue.
  2. Link the question to candidate tables and columns, and include sample values for low-cardinality columns.
  3. Generate a query constrained to the dialect and to read-only statements.
  4. Validate before execution: parse the query, check referenced identifiers exist, and reject writes and unbounded scans.
  5. Execute with a row and time limit, then narrate the result and show the query so the user can check it.
  6. On empty or error results, repair the query against the error message rather than falling back to text retrieval silently.

Trade-offs

ChoiceGood forCostFails when
Text-to-SQLExact aggregates and joinsSchema size, dialect quirks and wrong-but-valid queriesThe schema is large or poorly documented
Curated semantic layerFewer wrong joinsUp-front modelling workThe schema changes often
Text retrieval over table extractsNo execution riskApproximate and stale numbersThe question needs an aggregate
Query plus narrationAuditable answerLonger output and a two-step failure pathUsers want a single number
Trade-off mapInteractive

Good for

Exact aggregates and joins

Cost

Schema size, dialect quirks and wrong-but-valid queries

Fails when

The schema is large or poorly documented

  1. The schema is large or poorly documented
  2. The schema changes often
  3. The question needs an aggregate
  4. Users want a single number

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Text-to-SQL is good for Exact aggregates and joins, costs Schema size, dialect quirks and wrong-but-valid queries, and fails when The schema is large or poorly documented. Curated semantic layer is good for Fewer wrong joins, costs Up-front modelling work, and fails when The schema changes often. Text retrieval over table extracts is good for No execution risk, costs Approximate and stale numbers, and fails when The question needs an aggregate. Query plus narration is good for Auditable answer, costs Longer output and a two-step failure path, and fails when Users want a single number

Failure modes

  • Wrong join path. The query runs and returns a plausible number from a fan-out join. Debug: compare the generated query's joins with the documented relationships and check row counts before and after each join.
  • Schema linking error. A similarly named column is chosen and the metric is wrong by construction. Debug: log the linked columns beside the question and review mismatches on a labelled set.
  • Silent empty result. The query returns nothing and the answer says there is no data, when the filter was wrong. Debug: run the query without filters to confirm rows exist, then add predicates one at a time.

In production

Log every generated query, its execution time and its result size. Enforce read-only credentials, statement timeouts and row limits, and alert on queries that scan without a filter.

Common misconceptions

People think: A query that executes is a query that is correct.

Actually: Validity and intent are independent; a valid join can compute the wrong metric.

People think: Structured RAG needs no retrieval.

Actually: Schema linking is retrieval over the catalogue, and it is where most errors originate.

Interview angle

Centre schema linking and query validation, and insist on read-only execution with limits. Show the query to the user and treat an empty result as a bug to investigate. Asking the model for SQL and running it is the answer that skips the verification.

Sources