Where raw text-to-SQL gets the number wrong

Cerca de 31 minutos min de leitura, com 6 exemplos em 8 seções.

Edição 2026.11.15 Exemplos aprovados em 19 de nov de 2026 78 de 78 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.15. Leia o original

Esta parte ainda não foi traduzida, por isso está em inglês.

By the end of this chapter, you can name the five ways schema-only text-to-SQL returns a plausible wrong number on a real warehouse, show each one on the shop's warehouse, count them across a set of golden questions, and tell which a better prompt can fix and which need definitions the schema doesn't hold.

Chapter 1 asked a model for net revenue by region in March 2026, given only the warehouse's schema, and got a total 8.3% too high, because the query counted cancelled orders. This chapter asks 11 more questions of the shop, which sells outdoor and camping gear across EMEA, AMER and APAC, each written to touch one of the warehouse's traps, and runs the model's SQL on each. The warehouse is a DuckDB database the book generates from a fixed seed, with a raw schema as loaded and an analytics schema of marts.

The worry is common. In dbt Labs' 2026 survey of analytics engineering, 71% of respondents named "incorrect or hallucinated outputs reaching stakeholders" as a top concern (dbt Labs, April 14, 2026). The survey had 363 respondents, collected in late 2025 and early 2026, and it is a vendor's survey of people who chose to answer, so it measures worry, not how often wrong numbers ship. It doesn't say where the wrong numbers come from. The sections below show five places on the shop's warehouse, one at a time, and the last of them counts how often each appears.

Every example replays the recording called schema-only-sql: the replies a pinned open model, Qwen3-4B-Instruct-2507, gave when it was shown the schema of every table and one question, and asked for one DuckDB query. Chapter 1 explains how the recording was made and why each reply is looked up by the hash of the exact messages. Each example then runs the model's query on the warehouse and compares the result with the golden result: the question's answer from SQL written against the finance team's definitions and checked by running it, kept with the question in examples/data/golden/questions.toml.

Joins que multiplicam linhas e inflam uma soma

Última alteração na edição 2026.11.12

Fan-out é o que acontece quando uma consulta faz join de uma tabela com outra que tem várias linhas para cada uma das suas linhas, e então soma uma coluna da primeira. Um pedido tem uma linha na tabela de pedidos do data mart e várias nas linhas de itens do pedido, então, após o join, o valor de cada pedido aparece uma vez por item, e uma soma sobre ele conta o pedido várias vezes. A consulta é executada, o número tem as unidades certas, e nada no resultado o sinaliza. Um analista que conhece a granularidade de cada tabela agrega os itens por pedido antes do join, ou filtra com IN em vez de usar join. Um modelo que vê apenas nomes de colunas precisa inferir a granularidade a partir deles, e o esquema não a declara.

No armazém da loja, analytics.fct_orders tem uma linha por pedido com seu net_revenue_eur, e analytics.fct_order_lines tem uma linha por item com seu product_id. A pergunta é uma que um gerente de categoria faz: "Quanta receita líquida veio de pedidos que incluíram uma barraca em 2025?" Ela é a pergunta de referência gq-007. Sua SQL de referência conta a receita líquida total de cada pedido uma vez, se algum de seus itens for um produto da categoria Tents. Conte as linhas que o join do modelo produz, em comparação com a consulta de referência: a soma parece plausível, mas não está correta.

tent-orders-fan-out.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Replay the model's SQL for net revenue from orders with a tent, then count each order once. Read the `inflated by` line: it is the fan-out, measured with the model's own joins and filters kept as they are."""from lib.golden import golden_result, load_goldenfrom lib.model import RecordedModelfrom lib.prompts import schema_only_messagesfrom lib.tools import extract_sql, run_sqlfrom lib.warehouse import connect, describe_schemacon = connect()question = next(q for q in load_golden() if q.question_id == "gq-007")sql = extract_sql(RecordedModel("schema-only-sql").complete(schema_only_messages(describe_schema(con), question.question)))print(sql)# The model's own joins and filters, kept as they are, so only the counting changes.# placed_at is UTC, so EXTRACT gives the year by UTC, as the model wrote it.matched = """FROM analytics.fct_orders f JOIN analytics.fct_order_lines fl ON f.order_id = fl.order_id             JOIN analytics.dim_products p ON fl.product_id = p.product_id             WHERE {product} AND EXTRACT(YEAR FROM f.placed_at) = 2025"""# The model's name match, which misses shelters, and the whole Tents category, which has them.by_name, by_category = "p.product_name LIKE '%tent%'", "p.category = 'Tents'"# One row for each matched line and a count of the distinct orders behind them; the trailing comma unpacks that one row.(lines, orders), = con.execute(f"SELECT count(*), count(DISTINCT f.order_id) {matched.format(product=by_name)}").fetchall()# A semi-join: each order's whole net revenue, counted once, however many of its lines match.once = "SELECT sum(net_revenue_eur) FROM analytics.fct_orders WHERE order_id IN (SELECT f.order_id {matched})"model_total = run_sql(con, sql).rows[0][0]counted_once = con.execute(once.format(matched=matched.format(product=by_name))).fetchall()[0][0]whole_category = con.execute(once.format(matched=matched.format(product=by_category))).fetchall()[0][0]print(f"rows the join matched: {lines}")print(f"orders behind them: {orders}")print(f"model's answer: {model_total:,.2f}")print(f"each order counted once: {counted_once:,.2f}")print(f"inflated by: {model_total / counted_once - 1:.1%}")print(f"tents and shelters, counted once: {whole_category:,.2f}")print(f"golden: {golden_result(con, question)[0][0]:,.2f}")# The same query shape with no product filter: every 2025 order joined to all of its lines.# `/` is decimal division in DuckDB, so the average keeps its fraction.(per_order,), = con.execute("SELECT count(*) / count(DISTINCT order_id) FROM analytics.fct_order_lines").fetchall()# The second subquery is the true sum: each 2025 order counted once, from the orders table alone.(all_joined, all_once), = con.execute("""SELECT    (SELECT sum(f.net_revenue_eur) FROM analytics.fct_orders f JOIN analytics.fct_order_lines fl ON f.order_id = fl.order_id     WHERE EXTRACT(YEAR FROM f.placed_at) = 2025),    (SELECT sum(net_revenue_eur) FROM analytics.fct_orders WHERE EXTRACT(YEAR FROM placed_at) = 2025)""").fetchall()print(f"lines per order: {per_order:.2f}")print(f"all 2025 orders joined to their lines, sum over true sum: {all_joined / all_once:.2f}")
Saídapython tent-orders-fan-out.py
SELECT SUM(f.net_revenue_eur) AS net_revenue
FROM analytics.fct_orders f
JOIN analytics.fct_order_lines fl ON f.order_id = fl.order_id
JOIN analytics.dim_products p ON fl.product_id = p.product_id
WHERE p.product_name LIKE '%tent%'
  AND EXTRACT(YEAR FROM f.placed_at) = 2025
rows the join matched: 493
orders behind them: 480
model's answer: 256,467.71
each order counted once: 246,717.82
inflated by: 4.0%
tents and shelters, counted once: 400,909.10
golden: 377,497.40
lines per order: 2.56
all 2025 orders joined to their lines, sum over true sum: 3.38

A multiplicação inflou a resposta em 4.0%. O modelo fez join de pedidos com itens e produtos e somou f.net_revenue_eur sobre todas as linhas unidas, e o join encontrou 493 linhas para 480 pedidos, de modo que cada pedido com mais de um item de barraca foi contado mais de uma vez. Contando cada pedido uma vez, com os mesmos joins e filtros, obtém-se 246,717.82 euros, menos que a resposta do modelo.

A correspondência por nome é o maior erro da consulta: ela casa produtos cujo nome contém tent, o que deixa de fora os abrigos da mesma categoria. Contando a categoria Tents inteira, uma vez por pedido, obtém-se 400,909.10, e deixar de fora os pedidos cancelados e contar os dias úteis locais leva ao valor de referência 377,497.40. Dois erros puxaram em direções opostas: a multiplicação acrescentou um pouco, e a correspondência por nome subtraiu muito mais. Um revisor que compare o número com o do ano passado pode não notar nada estranho.

O tamanho de uma multiplicação depende dos dados, não da consulta. Poucos pedidos da loja têm duas linhas de barraca, então a inflação aqui é pequena. Quando um join repete a maioria das linhas várias vezes, o mesmo formato de consulta multiplica uma soma. Faça join de todos os pedidos de 2025 com todos os seus itens, sem filtro de produto, e a soma da receita líquida chega a 3.38 vezes o valor real. A receita de cada pedido é contada uma vez para cada um dos seus itens, e os pedidos da loja têm 2.56 itens em média; a razão é essa contagem ponderada pela receita, por isso pode superar a média simples. O tamanho medido em uma pergunta não diz nada sobre a seguinte.

Regra prática: Quando uma consulta faz join de tabelas de granularidades diferentes, verifique a granularidade de cada coluna que ela soma. Agregue a tabela mais detalhada para a granularidade mais grossa antes do join, ou filtre com IN ou EXISTS, e compare a contagem de linhas após o join com a contagem de chaves distintas. Espere que um modelo que receba apenas o esquema deixe isso passar, porque o esquema nomeia colunas, não granularidades.

Definições que o schema não contém

Última alteração na edição 2026.11.12

Um fan-out é um erro mecânico: quem conhece a granularidade das tabelas consegue identificá-lo no SQL. Uma definição é diferente. Palavras como receita, valor do pedido ou cliente ativo têm um único significado em um negócio, escolhido pelas pessoas responsáveis pelo número, e esse significado vive em uma política financeira, no SQL de um painel ou na memória de alguém. O schema pode conter várias colunas que se encaixam na palavra, e nunca diz qual delas o negócio quer dizer. Uma consulta que escolhe a errada é um SQL correto para uma pergunta diferente.

A equipe financeira da loja define receita como receita líquida: em euros, após descontos, antes de impostos, a partir de pedidos reais que não foram cancelados, no dia útil local do pedido. O data mart de pedidos tem gross_revenue_eur e net_revenue_eur. Os preços na EMEA incluem IVA, e as outras regiões acrescentam imposto sobre vendas por cima, então a diferença entre as duas colunas varia por região. A pergunta é a pergunta dourada gq-008: "Qual foi nossa receita total em 2025?" Ela não diz líquida, porque as pessoas que trabalham na loja não dizem. Qual escolha custa mais? O exemplo muda uma coisa por vez, do bruto até o dourado.

gross-or-net-revenue.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Replay the model's SQL for total revenue in 2025, then change one choice at a time until it reaches the golden result. The line that matters is `overstated by`, and the step from gross to net, which matches the tax in the gross figure."""from lib.golden import golden_result, load_goldenfrom lib.model import RecordedModelfrom lib.prompts import schema_only_messagesfrom lib.tools import extract_sql, run_sqlfrom lib.warehouse import connect, describe_schemacon = connect()question = next(q for q in load_golden() if q.question_id == "gq-008")sql = extract_sql(RecordedModel("schema-only-sql").complete(schema_only_messages(describe_schema(con), question.question)))print(sql)def total(measure: str, where: str) -> float:    return con.execute(f"SELECT sum({measure}) FROM analytics.fct_orders WHERE {where}").fetchall()[0][0]# The model filters on placed_at, the UTC timestamp, so "2025" here is 2025 by UTC, not by local business day.utc_2025 = "placed_at >= '2025-01-01' AND placed_at < '2026-01-01'"model_answer, golden = run_sql(con, sql).rows[0][0], golden_result(con, question)[0][0]# Each step changes one choice from the step before it, so the values read as a walk to the golden figure.steps = {    "model's answer (gross)": model_answer,    "net instead of gross": total("net_revenue_eur", utc_2025),    "without cancelled orders": total("net_revenue_eur", f"{utc_2025} AND status <> 'cancelled'"),    "golden (local business days)": golden,}for label, value in steps.items():    print(f"{label}: {value:,.2f}")# The tax the gross figure carries, summed over the same rows the model's query reads.print(f"tax in the gross figure: {total('tax_eur', utc_2025):,.2f}")print(f"overstated by: {model_answer / golden - 1:.1%}")
Saídapython gross-or-net-revenue.py
SELECT SUM(gross_revenue_eur) AS total_revenue
FROM analytics.fct_orders
WHERE placed_at >= '2025-01-01' AND placed_at < '2026-01-01'
model's answer (gross): 1,987,532.10
net instead of gross: 1,745,126.98
without cancelled orders: 1,652,978.12
golden (local business days): 1,651,527.86
tax in the gross figure: 242,404.96
overstated by: 20.3%

O valor bruto superestima a resposta dourada em 20.3%. O modelo escolheu gross_revenue_eur, uma leitura razoável de "receita total" para quem nunca conversou com a equipe financeira, e respondeu 1,987,532.10 euros, contra os 1,651,527.86 da resposta dourada.

A maior parte dessa diferença é imposto. Trocar para receita líquida nas mesmas linhas dá 1,745,126.98, uma redução de quase exatamente os 242,404.96 euros de imposto, com centavos de arredondamento entre um e outro. Deixar de fora os pedidos cancelados, o que leva o total a 1,652,978.12 euros, elimina quase todo o restante, e contar dias úteis locais em vez de datas UTC fecha a última diferença, pequena.

A mesma escolha deu errado em outros pontos do registro. Em gq-009, o valor médio do pedido por região em março de 2026, o modelo calculou a média de gross_revenue_eur sobre todos os pedidos, inclusive os cancelados, enquanto a definição da loja divide a receita líquida pelos pedidos que não foram cancelados. Em gq-012, a receita total de cada região de vendas, o modelo escolheu o bruto de novo. Nenhuma das escolhas é descuido. Cada uma é um significado comum da palavra fora da loja.

Nenhuma das duas taxonomias de erros que verificamos tem uma classe para isso. Uma taxonomia detalhada, NL2SQL-BUGs, classifica erros semânticos em text-to-SQL em 9 categorias e 31 subcategorias, a partir de 2,018 casos anotados por especialistas (Liu et al., KDD 2025). Ela classificaria a consulta em Attribute Mismatch, uma coluna errada, o que nomeia o sintoma e não a causa: nenhuma de suas classes é "o negócio define isso de forma diferente do schema". O mais próximo que encontramos está em uma auditoria de anotações de benchmarks, que nomeia descompassos entre uma pergunta e o conhecimento de domínio de que ela precisa (Jin et al., CIDR 2026). Essa lacuna é a nossa leitura dos dois artigos, não um resultado medido, e outras taxonomias podem ter a classe.

Regra prática: Trate cada palavra de negócio em uma pergunta como uma definição a ser consultada, não como uma coluna a ser associada. Registre quem é o responsável por cada definição, e dê ao agente a própria definição, como uma métrica governada ou pelo menos um verbete de glossário, nunca apenas as colunas a partir das quais ela poderia ser calculada. Quando uma palavra não tem definição escrita, faça o agente perguntar ou recusar, em vez de escolher.

Esta parte ainda não foi traduzida, por isso está em inglês.

Time zones and the fiscal calendar

Última alteração na edição 2026.11.15

Time looks like the least ambiguous part of a question, and on the shop's warehouse it is where the model went wrong as often as anywhere. A date in a question has a calendar and a time zone, and a warehouse usually stores timestamps in UTC while the business counts days in local time and years in its own fiscal calendar. A definition such as "fiscal year" is at least a phrase the model can see in the question. The time zone is invisible: the question says "May", and the query has to know whose May.

The shop counts each order on its region's local business day, stored as order_date_local in the orders mart, beside the UTC timestamp placed_at. Its fiscal year starts on February 1 and is named for the year it ends in, so fiscal 2026 runs from February 1, 2025 to January 31, 2026, and analytics.dim_date holds the fiscal columns. Golden question gq-004 asks how many customers placed their first order in fiscal year 2026. Golden question gq-013 asks how many orders each sales region received in May 2026. One tests the fiscal year, the other the local business day.

fiscal-year-and-local-day.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Two time traps in the model's SQL: a calendar year where the question meant a fiscal one, and UTC days. Read the `gq-004 model` line, the `gq-013` lines, and the counts of orders whose two clocks disagree."""from lib.golden import golden_result, load_goldenfrom lib.model import RecordedModelfrom lib.prompts import schema_only_messagesfrom lib.tools import extract_sql, run_sqlfrom lib.warehouse import connect, describe_schemacon = connect()schema, model = describe_schema(con), RecordedModel("schema-only-sql")golden = {q.question_id: q for q in load_golden()}def model_answer(question_id: str):    sql = extract_sql(model.complete(schema_only_messages(schema, golden[question_id].question)))    print(sql)    return run_sql(con, sql).rows# gq-004: customers whose first order was in fiscal year 2026, which runs from February 1, 2025 to January 31, 2026.print(f"gq-004 model: {model_answer('gq-004')[0][0]}")print(f"gq-004 golden: {golden_result(con, golden['gq-004'])[0][0]}")# gq-013: orders per region in May 2026. The model filters on placed_at, in UTC; the shop counts local days.# Both queries return (region, count) rows, which dict turns into a lookup by region.model_rows, golden_rows = dict(model_answer("gq-013")), dict(golden_result(con, golden["gq-013"]))for region in sorted(golden_rows):    print(f"gq-013 {region} model: {model_rows[region]}")    print(f"gq-013 {region} golden: {golden_rows[region]}")# Orders in May by exactly one of the two clocks, counting 2026 by local day.(moved,), = con.execute("""SELECT count(*) FROM analytics.fct_orders    WHERE (month(placed_at) = 5) <> (month(order_date_local) = 5) AND year(order_date_local) = 2026""").fetchall()print(f"orders across May's edges: {moved}")# Which way each of those orders crossed, by region: in May by the model's UTC filter only, or by the local day only.# UTC is a half-open range that ends before June 1; the local day is a date, so BETWEEN also takes May 31.crossings = con.execute("""SELECT region,    count(*) FILTER (WHERE in_utc AND NOT in_local), count(*) FILTER (WHERE in_local AND NOT in_utc)    FROM (SELECT region, placed_at >= '2026-05-01' AND placed_at < '2026-06-01' AS in_utc,                 order_date_local BETWEEN DATE '2026-05-01' AND DATE '2026-05-31' AS in_local          FROM analytics.fct_orders) GROUP BY region ORDER BY region""").fetchall()for region, utc_only, local_only in crossings:    print(f"gq-013 {region} in May by UTC only: {utc_only}")    print(f"gq-013 {region} in May by local day only: {local_only}")print(f"all regions in May by UTC only: {sum(c[1] for c in crossings)}")print(f"all regions in May by local day only: {sum(c[2] for c in crossings)}")
Saídapython fiscal-year-and-local-day.py
SELECT COUNT(*) AS customer_count
FROM analytics.dim_customers
WHERE first_order_on >= '2026-01-01' AND first_order_on < '2027-01-01'
gq-004 model: 225
gq-004 golden: 825
SELECT
    region,
    COUNT(order_id) AS order_count
FROM
    analytics.fct_orders
WHERE
    placed_at >= '2026-05-01' AND placed_at < '2026-06-01'
GROUP BY
    region
ORDER BY
    order_count DESC
gq-013 AMER model: 219
gq-013 AMER golden: 220
gq-013 APAC model: 148
gq-013 APAC golden: 147
gq-013 EMEA model: 317
gq-013 EMEA golden: 317
orders across May's edges: 6
gq-013 AMER in May by UTC only: 2
gq-013 AMER in May by local day only: 3
gq-013 APAC in May by UTC only: 1
gq-013 APAC in May by local day only: 0
gq-013 EMEA in May by UTC only: 0
gq-013 EMEA in May by local day only: 0
all regions in May by UTC only: 3
all regions in May by local day only: 3

The model's gq-004 query is tidy and runs, and it answers the wrong year. It counts customers whose first order fell in calendar 2026: 225, where the golden answer is 825. Because the shop's data ends on 2026-06-30, it counted half a calendar year, not a whole fiscal one, so the error is large here. For a period where the two years overlap more, the same mistake would be small and harder to see.

May is off by one order in two regions, because the filter uses placed_at, the UTC timestamp. For AMER it says 219 orders against a golden 220, and for APAC 148 against 147; EMEA matches the golden answer.

Across all regions, 6 orders of 2026 fall in May by one clock and not the other, and they partly cancel. In AMER, 3 orders count in May only by the local day and 2 only by UTC, so the model ends one order short. In APAC, 1 order counts in May only by UTC, so the model ends one over.

Errors this small are the dangerous kind. They survive a sanity check, and they make two reports of the same month disagree by a few orders, which costs a team an afternoon to explain.

The recording has the other half of the problem too. For two questions about fiscal periods, gq-001 and gq-010, the model filtered fct_orders on fiscal_year and fiscal_quarter, which exist only in dim_date, and the queries failed to run. Those failures are cheap, because someone sees them. The calendar-year query for gq-004 is the expensive one.

Working rule: Give the agent your calendar, not only your columns: which timestamp is UTC, which date is the business day, and when the fiscal year starts and how it is named. Test every period question at a boundary, such as the first day of a month or the first month of a fiscal year, where UTC and local days or calendar and fiscal years disagree. Prefer a date dimension the agent joins over date arithmetic it writes.

A tabela com o nome tentador

Última alteração na edição 2026.11.12

Uma definição pode dar errado dentro da tabela certa; uma tabela inteira pode ser a errada. A maioria dos data warehouses mantém tabelas que ninguém deveria mais consultar e que ninguém consegue remover: um data mart antigo que dashboards antigos ainda leem, uma cópia de uma migração, uma tabela criada para uma análise específica. Essa tabela costuma ter os nomes de coluna mais amigáveis do warehouse, porque foi construída para pessoas, e suas definições são as antigas. Um modelo que escolhe tabelas pelo nome pode preferi-la. O Spider 2.0, um benchmark de tarefas empresariais de text-to-SQL, constatou que escolher a tabela errada respondeu por 10.1% dos erros em uma amostra de 300 tarefas que fracassaram em dois frameworks de agentes (Lei et al., ICLR 2025).

O warehouse da loja tem uma: analytics.orders_legacy, que tem colunas chamadas revenue e sales_region. Sua receita é bruta, com imposto incluído, e ela mantém pedidos de teste e cancelados. A pergunta dourada gq-012, "Qual foi a receita total de cada região de vendas em 2025?", usa os dois nomes de coluna e foi escrita para atrair o modelo para ela, assim como gq-013, que pede pedidos por região de vendas. Duas verificações seguem: o que a tabela legada responde e se as consultas do modelo algum dia a leem.

legacy-table-answer.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""What the legacy mart says about revenue by sales region in 2025, and how often the model's queries read that mart. The line to read is `legacy total over golden`, and the count of queries that read `orders_legacy`."""from lib.golden import golden_result, load_goldenfrom lib.model import RecordedModelfrom lib.prompts import schema_only_messagesfrom lib.tools import extract_sqlfrom lib.warehouse import connect, describe_schemacon = connect()question = next(q for q in load_golden() if q.question_id == "gq-012")golden = dict(golden_result(con, question))# The legacy mart's revenue is gross, tax included, and it keeps test and cancelled orders.legacy = dict(con.execute("""SELECT sales_region, sum(revenue) FROM analytics.orders_legacy                             WHERE year(order_date) = 2025 GROUP BY sales_region""").fetchall())# Test orders are flagged only in raw, which the marts leave out; the legacy mart keeps them.(test_orders,), = con.execute("""SELECT count(*) FROM analytics.orders_legacy AS l JOIN raw.orders AS o ON o.order_id = l.id                                 WHERE o.is_test AND year(l.order_date) = 2025""").fetchall()for region in sorted(golden):    print(f"{region} golden: {golden[region]:,.2f}")    print(f"{region} orders_legacy: {legacy[region]:,.2f}")print(f"legacy total over golden: {sum(legacy.values()) / sum(golden.values()) - 1:+.1%}")print(f"test orders in the legacy rows: {test_orders}")# The model's schema-only queries for the first 16 golden questions: did any read the legacy mart?model, schema = RecordedModel("schema-only-sql"), describe_schema(con)# IDs are zero-padded, so comparing them as text selects gq-001 to gq-016.asked = [q for q in load_golden() if q.question_id <= "gq-016"]sqls = [extract_sql(model.complete(schema_only_messages(schema, q.question))) for q in asked]# A query counts as reading the legacy mart when its text names orders_legacy.print(f"model queries that read orders_legacy: {sum('orders_legacy' in sql for sql in sqls)} of {len(sqls)}")print(f"golden questions added in chapter 2, gq-006 to gq-016: {sum('gq-006' <= q.question_id <= 'gq-016' for q in asked)}")
Saídapython legacy-table-answer.py
AMER golden: 497,466.04
AMER orders_legacy: 576,980.12
APAC golden: 405,055.09
APAC orders_legacy: 465,770.13
EMEA golden: 749,006.73
EMEA orders_legacy: 962,439.56
legacy total over golden: +21.4%
test orders in the legacy rows: 62
model queries that read orders_legacy: 0 of 16
golden questions added in chapter 2, gq-006 to gq-016: 11

Quem somar a coluna revenue da tabela legada por sales_region em 2025 obtém um total +21.4% acima do dourado, sob um nome de coluna que diz ser receita. Para a EMEA, a tabela dá 962,439.56 euros, onde a receita líquida dourada é 749,006.73. Em todas as regiões, suas linhas de 2025 incluem 62 pedidos de teste.

O modelo registrado nunca a leu. Suas consultas para as perguntas douradas gq-001 a gq-016 tocaram orders_legacy em 0 of 16 casos. Neste warehouse, fct_orders tem uma coluna region e as duas colunas de receita, e o modelo a preferiu todas as vezes. Isso é um resultado sobre este modelo, este esquema e estas perguntas, e não uma garantia. O risco cresce com o warehouse: os bancos de dados do Spider 2.0-lite têm, em média, mais de 755 colunas, contra cerca de 54 no BIRD, um benchmark acadêmico (Lei et al., ICLR 2025). Entre centenas de tabelas, esperamos que os nomes amigáveis de uma tabela legada coincidam com as palavras de uma pergunta com mais frequência. Esperamos também que o risco cresça quando um agente recebe exemplos ou descrições recuperados, porque uma busca por nomes pode colocar a tabela legada no topo do ranking.

Por esse motivo, mantemos orders_legacy no warehouse ao longo de todo o livro. Uma tabela que você não pode remover é uma tabela que um agente pode encontrar, e a defesa fica abaixo do modelo: uma lista das tabelas que ele pode ler.

Regra prática: liste as tabelas que um agente pode ler e deixe de fora as tabelas legadas e de staging, mesmo quando tiverem os nomes mais amigáveis. Verifique as tabelas de cada consulta escrita pelo modelo contra a lista antes de ela ser executada. Quando um agente nunca escolher uma tabela tentadora em seus testes, mantenha a verificação mesmo assim: uma pergunta nova, um esquema maior ou um exemplo recuperado podem mudar esse comportamento.

Filtros que ninguém escreveu

Última alteração na edição 2026.11.12

Algumas regras sobre quais linhas contam são tão familiares para as pessoas donas de um número que ninguém as escreve: pedidos cancelados não contam como receita, contas de teste não são clientes, um reembolso pertence ao mês do seu pedido. Essa regra vive no SQL da mart, nos relatórios da equipe financeira e na cabeça das pessoas. Uma consulta que a deixa de fora devolve todas as linhas, o que parece a resposta mais completa, e não uma resposta errada. O Capítulo 1 mostrou isso uma vez, na receita líquida por região.

Quem escreve benchmarks de text-to-SQL também deixa esses filtros passar. No banco california_schools do benchmark BIRD, o SQL do gabarito deixa de fora a condição sobre a coluna rtype, que é o que separa escolas de distritos, porque os anotadores tinham marcado essa coluna como "inútil" (Jin et al., CIDR 2026). Uma regra que ninguém escreveu some do gabarito assim como some da consulta do modelo.

As marts da loja aplicam uma dessas regras por você: elas removem os pedidos de teste. Elas não podem remover os pedidos cancelados, porque algumas perguntas são sobre cancelamentos, então fct_orders os mantém com o seu status, e as linhas de pedido também os mantêm. A pergunta é a pergunta do gabarito gq-015, "Quantas unidades de cada categoria de produto vendemos em 2025?", que precisa do status de uma tabela para filtrar linhas de outra. A consulta do modelo nunca descarta pedidos cancelados, e o exemplo mostra o custo.

cancelled-lines-counted.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Replay the model's SQL for units sold by category in 2025, and find the filters it left out. Read the `overstated by` line, and the units on cancelled orders, which the missing status filter explains."""from lib.golden import golden_result, load_goldenfrom lib.model import RecordedModelfrom lib.prompts import schema_only_messagesfrom lib.tools import extract_sql, run_sqlfrom lib.warehouse import connect, describe_schemacon = connect()question = next(q for q in load_golden() if q.question_id == "gq-015")sql = extract_sql(RecordedModel("schema-only-sql").complete(schema_only_messages(describe_schema(con), question.question)))print(sql)# The model's query returns (category, units) rows, which dict turns into a lookup by category.model_units = dict(run_sql(con, sql).rows)golden_units = dict(golden_result(con, question))# The status is on the order, so the lines join to fct_orders to read it.(cancelled,), = con.execute("""SELECT sum(l.quantity) FROM analytics.fct_order_lines AS l    JOIN analytics.fct_orders AS o USING (order_id)    WHERE o.status = 'cancelled' AND o.placed_at >= '2025-01-01' AND o.placed_at < '2026-01-01'""").fetchall()# raw keeps test orders, which the marts drop; the is_test flag is only in raw.(test_units,), = con.execute("""SELECT sum(l.quantity) FROM raw.order_lines AS l JOIN raw.orders AS o USING (order_id)    WHERE o.is_test AND year(o.placed_at) = 2025""").fetchall()print(f"Cooking model: {model_units['Cooking']}")print(f"Cooking golden: {golden_units['Cooking']}")print(f"all categories model: {sum(model_units.values())}")print(f"all categories golden: {sum(golden_units.values())}")print(f"units on cancelled orders, in the model's dates: {cancelled}")print(f"overstated by: {sum(model_units.values()) / sum(golden_units.values()) - 1:.1%}")print(f"units on test orders, which the marts already leave out: {test_units}")# Orders that weren't cancelled but fall in 2025 by one clock and not the other: in by UTC only, minus in by local day only.(edge_net,), = con.execute("""SELECT sum(l.quantity) FILTER (WHERE year(o.placed_at) = 2025 AND year(o.order_date_local) <> 2025)                                   - sum(l.quantity) FILTER (WHERE year(o.placed_at) <> 2025 AND year(o.order_date_local) = 2025)    FROM analytics.fct_order_lines AS l JOIN analytics.fct_orders AS o USING (order_id)    WHERE o.status <> 'cancelled'""").fetchall()print(f"net units on orders across the year's edges: {edge_net}")
Saídapython cancelled-lines-counted.py
SELECT
    p.category,
    SUM(ol.quantity) AS total_units_sold
FROM
    analytics.fct_order_lines ol
JOIN
    analytics.dim_products p ON ol.product_id = p.product_id
WHERE
    ol.order_id IN (
        SELECT order_id
        FROM analytics.fct_orders
        WHERE placed_at >= '2025-01-01' AND placed_at < '2026-01-01'
    )
GROUP BY
    p.category
ORDER BY
    total_units_sold DESC
Cooking model: 5727
Cooking golden: 5427
all categories model: 22324
all categories golden: 21108
units on cancelled orders, in the model's dates: 1206
overstated by: 5.8%
units on test orders, which the marts already leave out: 202
net units on orders across the year's edges: 10

Deixar o status de fora é quase todo o erro. O modelo somou quantity de fct_order_lines para pedidos de 2025 sem nenhuma condição de status, então contou unidades de pedidos cancelados dentro do período. Em todas as categorias, ele informa 22324 unidades contra as 21108 do gabarito, 5.8% a mais. A diferença é quase toda de pedidos cancelados; as 10 unidades restantes são o líquido de pedidos cujos dias em UTC e no horário local caem em anos diferentes.

Para Cooking, o modelo diz 5727 unidades, enquanto a resposta do gabarito é 5427.

Os pedidos de teste mostram o outro lado. As linhas brutas de pedido têm 202 unidades em pedidos de teste de 2025, e a resposta do modelo não as incluiu, porque ele leu a mart, e a mart já havia aplicado essa regra. Um filtro que a mart aplica é um que o modelo não consegue esquecer. Em todas as consultas que escreveu para este capítulo, o modelo leu as marts, nunca as tabelas brutas, então os pedidos de teste nunca chegaram a uma resposta.

A consulta também não perguntou se uma unidade vendida foi depois devolvida. A definição de unidades vendidas da loja não subtrai devoluções, então a resposta do gabarito também não subtrai. Essa é mais uma regra que precisa estar escrita onde o agente possa lê-la, senão a próxima pessoa vai, com razão, responder de outra forma.

Regra prática: Coloque toda regra sobre quais linhas contam nas marts sempre que puder, para que nenhuma consulta consiga esquecê-la. Quando uma mart precisar manter as linhas, como acontece com pedidos cancelados, escreva a regra na definição que o agente usa e acrescente uma pergunta do gabarito que falhe quando a regra for deixada de fora. Leia o gabarito em busca das mesmas regras, porque quem o escreveu pode deixá-las passar tão facilmente quanto o modelo.

Conte as falhas por tipo

Última alteração na edição 2026.11.12

Cada seção até aqui mostrou uma falha em uma única pergunta. Para decidir o que corrigir primeiro, você precisa saber com que frequência cada tipo ocorre nas suas perguntas, e quais falhas são erros visíveis e quais são números errados plausíveis. O conjunto é pequeno, então as contagens descrevem esta execução, não uma taxa que você possa citar.

Esta execução pega o SQL do modelo, só com o schema, para cada pergunta dourada de gq-001 a gq-016 que tenha resposta, 15 delas, para que suas falhas possam ser contadas. Ela deixa de fora gq-005, uma previsão que deveria ser recusada, assunto do capítulo 8. Ela compara cada resultado com o resultado dourado e o classifica como correto, errado ou erro, e rotula cada consulta com seus tipos de falha. Os rótulos vêm de lib/failure_kinds.py, que faz o parse da consulta do modelo e do SQL dourado com sqlglot e os compara. Por exemplo, uma consulta que usa placed_at onde o SQL dourado usa o dia útil local recebe o rótulo time. As regras são nossas, escritas para as armadilhas deste data warehouse; a docstring do módulo lista cada uma delas.

classify-schema-only-errors.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Aprovado
"""Run the model's schema-only SQL on each golden question that has an answer, grade each result, and label the failure kinds of each query. The counts of correct, wrong and error answers, and the kinds the wrong ones carry, are what the prose quotes."""from collections import Counterimport duckdbfrom lib.failure_kinds import KINDS, failure_kindsfrom lib.golden import golden_result, grade, load_goldenfrom lib.model import RecordedModelfrom lib.prompts import schema_only_messagesfrom lib.tools import extract_sql, run_sqlfrom lib.warehouse import connect, describe_schemacon = connect()schema, model = describe_schema(con), RecordedModel("schema-only-sql")# Kind "answer" leaves out gq-005, the forecast to decline; IDs are zero-padded, so gq-001 to gq-016 is a text range.questions = [q for q in load_golden() if q.kind == "answer" and q.question_id <= "gq-016"]outcomes, kinds_in_wrong, errors = Counter(), Counter(), {}print("question  outcome  kinds")for q in questions:    sql = extract_sql(model.complete(schema_only_messages(schema, q.question)))    try:        outcome = grade(q, run_sql(con, sql), golden_result(con, q))    except duckdb.Error as e:        # A query the database refuses to run is an error, not a wrong number.        outcome, errors[q.question_id] = "error", str(e).splitlines()[0]    # Each kind is a rule in lib/failure_kinds.py that compares the query with the golden SQL; a query can carry none or several.    kinds = failure_kinds(sql, q.golden_sql)    outcomes[outcome] += 1    if outcome == "wrong":        kinds_in_wrong.update(kinds)    print(f"{q.question_id}    {outcome:<7}  {', '.join(kinds) or '-'}")for question_id, message in errors.items():    print(f"{question_id} error: {message}")print(f"questions graded: {len(questions)}")for outcome in ("correct", "wrong", "error"):    print(f"{outcome}: {outcomes[outcome]} of {len(questions)}")# DuckDB's messages: one for a column the table read does not have, one for a type mismatch such as LIKE on a timestamp.print(f"errors with a missing column: {sum('Referenced column' in m for m in errors.values())}")print(f"errors with a type mismatch: {sum('No function matches' in m for m in errors.values())}")for kind in KINDS:    print(f"wrong answers with {kind}: {kinds_in_wrong[kind]}")# gq-016 counts distinct customers: do those with an order across 2025's edges have other 2025 orders by both clocks?(edge_customers, covered), = con.execute("""SELECT count(DISTINCT customer_id), count(DISTINCT customer_id) FILTER (WHERE customer_id IN    (SELECT customer_id FROM analytics.fct_orders WHERE year(placed_at) = 2025 AND year(order_date_local) = 2025))    FROM analytics.fct_orders WHERE (year(placed_at) = 2025) <> (year(order_date_local) = 2025)""").fetchall()print(f"gq-016 customers with an order across 2025's edges: {edge_customers}")print(f"gq-016 of them, with other 2025 orders by both clocks: {covered}")
Saídapython classify-schema-only-errors.py
question  outcome  kinds
gq-001    error    unwritten filter
gq-002    wrong    unwritten filter
gq-003    error    unwritten filter
gq-004    wrong    time
gq-006    error    time, unwritten filter
gq-007    wrong    fan-out, time, unwritten filter
gq-008    wrong    definition, time, unwritten filter
gq-009    wrong    definition, unwritten filter
gq-010    error    unwritten filter
gq-011    error    time, unwritten filter
gq-012    wrong    definition, time, unwritten filter
gq-013    wrong    time
gq-014    correct  time
gq-015    wrong    time, unwritten filter
gq-016    correct  time
gq-001 error: Binder Error: Referenced column "fiscal_year" not found in FROM clause!
gq-003 error: Binder Error: Referenced column "calendar_year" not found in FROM clause!
gq-006 error: Binder Error: Referenced column "quantity" not found in FROM clause!
gq-010 error: Binder Error: Referenced column "fiscal_quarter" not found in FROM clause!
gq-011 error: Binder Error: No function matches the given name and argument types '~~(TIMESTAMP, STRING_LITERAL)'. You might need to add explicit type casts.
questions graded: 15
correct: 2 of 15
wrong: 8 of 15
error: 5 of 15
errors with a missing column: 4
errors with a type mismatch: 1
wrong answers with fan-out: 1
wrong answers with definition: 3
wrong answers with time: 6
wrong answers with tempting table: 0
wrong answers with unwritten filter: 6
gq-016 customers with an order across 2025's edges: 6
gq-016 of them, with other 2025 orders by both clocks: 6

A maioria das falhas executou e devolveu um número, o tipo mais difícil de perceber: 8 of 15 respostas erradas, contra 5 of 15 consultas que falharam ao executar. Dos erros, 4 usaram uma coluna ausente na tabela lida, como fiscal_year em fct_orders, e 1 compararam um timestamp com um padrão de texto usando LIKE.

As respostas erradas são as mais caras. 6 delas têm erro de tempo e 6 um filtro não escrito. A maioria das respostas erradas trazia dois ou três tipos ao mesmo tempo, e é por isso que as seções sobre fan-out e definição mudaram uma escolha por vez, para separá-los.

Definições aparecem em 3 respostas erradas, fan-out em 1, e a tabela tentadora em 0, como mostrou sua seção.

Uma resposta correta não significa uma consulta correta. As respostas corretas, gq-014 e gq-016, têm ambas o rótulo time: suas consultas contam datas em UTC, e as contagens coincidiram por motivos diferentes. Para gq-014, pedidos cruzaram as bordas de maio nas duas direções, 3 entrando apenas por UTC e 3 entrando apenas pelo dia local, como mostrou a seção de tempo. Para gq-016, uma contagem de clientes distintos, 6 clientes tiveram um pedido nas bordas do ano, e 6 deles tiveram outros pedidos em 2025 pelos dois relógios, então a contagem não podia mudar. A correspondência de nome de tenda em gq-007 não tem rótulo, porque nenhuma regra a procura.

Cada um dos cinco tipos do livro tem um vizinho próximo em taxonomias publicadas, sob outro nome. O mapeamento é um juízo nosso:

Tipo neste livro Classe publicada mais próxima
fan-out Incompatibilidade na condição de junção; Funções de agregação [1]
definição nenhuma; a mais próxima é uma incompatibilidade de conhecimento de domínio (E3) [2]
tempo Funções de data/hora [1]
tabela tentadora Incompatibilidade de tabela [1]
filtro não escrito Condição implícita ausente; Condição explícita ausente [1]

A fonte [1] é o NL2SQL-BUGs (Liu et al., KDD 2025), e a [2] é a auditoria da CIDR 2026 sobre anotações de benchmarks (Jin et al.). As classes deles são mais finas que as nossas, e as nossas são mais amplas de propósito: cada um dos cinco aponta para uma correção no data warehouse ou no que é dado ao agente.

Esse mapeamento também responde quais falhas um prompt melhor pode corrigir. Um prompt pode conter práticas gerais, como agregar as linhas de itens antes de juntá-las aos pedidos, e pode conter fatos sobre um data warehouse específico, como qual coluna de data é o dia útil. Ele não consegue conter as definições da loja para cada palavra que as pessoas usam, e um prompt que tenta isso se torna uma segunda cópia, não revisada, dessas definições. Esperamos que um prompt reduza o fan-out e alguns erros de tempo, e só definições que o agente consiga ler e que o warehouse imponha eliminarão os outros três tipos. É um juízo que esta execução do capítulo sustenta, não algo que ela mede. Benchmarks mostram uma lacuna semelhante em escala maior. No Spider 2.0, um framework de agentes construído sobre o o1-preview resolveu 21.3% das tarefas empresariais, enquanto métodos baseados em GPT-4 haviam chegado a 91.2% no Spider 1.0 e 73.0% no BIRD (Lei et al., ICLR 2025). Os três números vêm de sistemas e formatos de tarefa diferentes, então ilustram a lacuna, sem medi-la.

Regra prática: Conte as falhas por tipo nas suas próprias perguntas douradas antes de escolher uma correção, e mantenha separados os erros que falham de forma explícita dos números errados que não falham. Rotule os tipos comparando cada consulta com seu SQL dourado, com regras que você consiga ler, e leia as respostas erradas que nenhuma regra rotula. Corrija primeiro o tipo mais comum de número errado, e espere que ele seja uma definição, um calendário ou um filtro com mais frequência do que um erro de sintaxe.

O que dá errado em produção

Última alteração na edição 2026.11.12

As falhas deste capítulo surgiram de perguntas escritas para encontrá-las. Em produção, as perguntas são escritas por pessoas que não sabem onde estão as armadilhas.

Dois erros se anulam e o número parece correto. A pergunta sobre a tenda, com o fan-out e a correspondência de nome, puxou em direções opostas, e as contagens em UTC de duas perguntas coincidiram porque os erros se anularam ou não puderam aparecer. Uma verificação pontual contra um valor conhecido deixa essas falhas passar. Você só as percebe comparando cada resultado com um resultado de referência, sob uma única regra, e lendo o SQL das respostas que passam, não apenas o das que falham.

Uma definição muda e a antiga continua respondendo. Quando a equipe financeira muda o que conta como receita, toda consulta que a calculava a partir de colunas mantém o significado antigo. As perguntas de referência sobre receita começam a falhar se o SQL de referência delas foi atualizado, e continuam passando se não foi. Mantenha o SQL de referência junto às definições de que depende e revise uma alteração em qualquer um dos dois em conjunto com o outro.

A tabela legada aparece depois. Na execução deste capítulo, o modelo nunca escolheu orders_legacy. Um esquema maior, exemplos recuperados ou uma pergunta no vocabulário da tabela legada podem mudar isso sem nenhuma alteração no seu código. Verifique as tabelas de cada consulta contra uma lista de tabelas permitidas e registre quais tabelas responderam a cada pergunta, para que uma mudança apareça em uma contagem.

Pequenos erros de tempo fazem os relatórios divergir. Uma contagem que difere em um pedido do relatório financeiro inicia uma reconciliação, e a causa é uma data em UTC onde o negócio usa dias locais. Você percebe o problema quando dois relatórios do mesmo período divergem, o que acontece tarde. Acrescente perguntas de referência nos limites de período, onde os dois relógios diferem, e mantenha-as no conjunto.

Um filtro é aplicado em um lugar e não em outro. Pedidos de teste são removidos nos marts, então qualquer consulta sobre as tabelas brutas os traz de volta. Um agente com acesso a raw pode lê-lo, inclusive por uma coluna que os marts não têm. Mantenha o esquema bruto fora do alcance do agente, ou dê a ele os filtros como parte da descrição de cada tabela.

O classificador de falhas não reconhece tipos novos. lib/failure_kinds.py identifica os cinco tipos que este capítulo conhece, e nenhum outro, como mostrou a correspondência de nome da tenda. Um painel de contagens de falhas por tipo parece completo enquanto um tipo novo cresce sem rótulo. Leia à mão uma amostra de respostas erradas periodicamente e acrescente uma regra quando um tipo novo aparecer duas vezes.

Regra prática: Antes que as respostas de um agente cheguem a alguém, avalie cada resposta contra resultados de referência, mantenha perguntas de referência nos limites de período e para cada definição, liste as tabelas que o agente pode ler e leia à mão uma amostra de respostas erradas. Conte os números errados por tipo e trate um aumento em qualquer tipo como alarme.

Decisões tomadas neste capítulo

  • Cinco tipos de número errado plausível: fan-out, uma definição que o esquema não sustenta, fusos horários e o calendário fiscal, uma tabela tentadora e um filtro não escrito. Cada um aponta para uma correção no data warehouse ou no que é entregue ao agente.
  • Cada falha é executada, não apenas descrita. Toda falha que o modelo cometeu é executada na sua consulta real e, quando dois erros se combinam, o exemplo muda uma escolha por vez para medir cada um.
  • 11 perguntas de referência entraram no conjunto, de gq-006 a gq-016, cada uma escrita para tocar em uma das armadilhas do warehouse, com SQL dourado que segue as definições da equipe financeira.
  • Os tipos de falha recebem rótulos por regras que você pode ler, em lib/failure_kinds.py, comparando cada consulta com seu SQL dourado, e as respostas erradas que nenhuma regra rotula são lidas manualmente.
  • Erros e números errados são contados separadamente. Uma consulta que não roda é uma falha barata; uma que devolve um número plausível é a que deve ser corrigida primeiro.
  • A tabela legada permanece no warehouse, embora o modelo não a tenha escolhido aqui, porque uma tabela que você não pode remover é uma que um agente pode encontrar.
  • Definições, e não prompts, são a correção para a maioria dos tipos. Um prompt pode carregar práticas gerais; as definições do negócio devem estar onde o agente as lê e o warehouse as impõe.

Este capítulo, nesta edição

Edição 2026.11.15Exemplos aprovados em 19 de nov de 20266 de 6 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.15.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 2 de 11: Where raw text-to-SQL gets the number wrong

  1. Joins que multiplicam linhas e inflam uma soma
  2. Definições que o schema não contém
  3. Time zones and the fiscal calendar
  4. A tabela com o nome tentador
  5. Filtros que ninguém escreveu
  6. Conte as falhas por tipo
  7. O que dá errado em produção
  8. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos