Where raw text-to-SQL gets the number wrong

Unos 26 minutos de lectura, con 6 ejemplos en 8 secciones.

Edición 2026.11.15 Ejemplos verificados el 19 de nov de 2026 78 de 78 ejemplos pasan Qué ha cambiado

Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros

Traducido del libro en inglés, edición 2026.11.15. Lee el original

Esta parte aún no está traducida, así que está en 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 se multiplican e inflan una suma

Último cambio en la edición 2026.11.12

El fan-out ocurre cuando una consulta une una tabla con otra que tiene varias filas por cada una de sus filas, y luego suma una columna de la primera. Un pedido tiene una fila en el mart de pedidos y varias en las líneas de pedido, así que después del join el importe de cada pedido aparece una vez por cada línea, y una suma sobre él cuenta el pedido varias veces. La consulta se ejecuta, el número tiene las unidades correctas y nada en el resultado lo señala. Un analista que conoce el grano de cada tabla agrega las líneas por pedido antes de unir, o filtra con IN en lugar de un join. Un modelo que solo ve nombres de columnas tiene que deducir el grano a partir de ellos, y el esquema no lo indica.

En el almacén de datos de la tienda, analytics.fct_orders contiene una fila por pedido con su net_revenue_eur, y analytics.fct_order_lines contiene una fila por línea con su product_id. La pregunta es una que haría un responsable de categoría: «¿Cuántos ingresos netos procedieron de pedidos que incluyeron una tienda de campaña en 2025?» Es la pregunta dorada gq-007. Su SQL dorado cuenta una vez el ingreso neto total de cada pedido, si alguna de sus líneas es un producto de la categoría Tents. Compara las filas que produce el join del modelo con las de la consulta dorada: la suma parece plausible, pero no lo es.

tent-orders-fan-out.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""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}")
Salidapython 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

El fan-out infló la respuesta en 4.0%. El modelo unió pedidos con líneas y productos y sumó f.net_revenue_eur sobre cada fila unida, y el join encontró 493 filas para 480 pedidos, así que cada pedido con más de una línea de tienda de campaña se contó más de una vez. Contar cada pedido una sola vez, con los mismos joins y filtros, da 246,717.82 euros, menos que la respuesta del modelo.

La coincidencia por nombre es el mayor error de la consulta: encuentra productos cuyo nombre contiene tent, lo que deja fuera los refugios de la misma categoría. Contar toda la categoría Tents, una vez por pedido, da 400,909.10, y al excluir los pedidos cancelados y contar los días laborables locales se llega a la cifra dorada 377,497.40. Dos errores actuaron en direcciones opuestas: el fan-out añadió un poco y la coincidencia por nombre quitó mucho más. Un revisor que compare la cifra con la del año pasado podría no notar nada extraño.

El tamaño de un fan-out depende de los datos, no de la consulta. Pocos pedidos de la tienda tienen dos líneas de tienda de campaña, así que la inflación aquí es pequeña. Cuando un join repite la mayoría de las filas varias veces, la misma forma de consulta multiplica una suma. Une todos los pedidos de 2025 con todas sus líneas, sin filtro de producto, y la suma del ingreso neto asciende a 3.38 veces la cifra real. El ingreso de cada pedido se cuenta una vez por cada una de sus líneas, y los pedidos de la tienda tienen 2.56 líneas de media; la proporción es ese recuento ponderado por ingresos, así que puede superar el promedio simple. El tamaño que mides en una pregunta no te dice nada sobre la siguiente.

Regla práctica: Cuando una consulta une tablas de granos distintos, comprueba el grano de cada columna que suma. Agrega la tabla más fina al grano de la más gruesa antes de unir, o filtra con IN o EXISTS, y compara el número de filas después del join con el recuento de claves distintas. Espera que un modelo que solo recibe el esquema pase esto por alto, porque el esquema nombra columnas, no granos.

Definiciones que el esquema no recoge

Último cambio en la edición 2026.11.12

Un fan-out es un error mecánico: quien conozca el grano de las tablas puede detectarlo en el SQL. Una definición es otra cosa. Palabras como ingresos, valor del pedido o cliente activo tienen un solo significado en un negocio, elegido por las personas que son dueñas de la cifra, y ese significado vive en una política financiera, en el SQL de un panel o en la memoria de alguien. El esquema puede contener varias columnas que encajan con la palabra, y nunca dice cuál es la que el negocio quiere decir. Una consulta que escoge la equivocada es SQL correcto para otra pregunta.

El equipo financiero de la tienda define los ingresos como ingresos netos: en euros, después de descuentos, antes de impuestos, de pedidos reales que no fueron cancelados, en el día hábil local del pedido. El mart de pedidos tiene gross_revenue_eur y net_revenue_eur. Los precios de EMEA incluyen el IVA y las demás regiones añaden el impuesto sobre ventas por encima, así que la diferencia entre las dos columnas varía según la región. La pregunta es la pregunta dorada gq-008: "¿Cuáles fueron nuestros ingresos totales en 2025?" No dice netos, porque quienes trabajan en la tienda no lo dicen así. ¿Qué elección cuesta más? El ejemplo cambia una cosa cada vez, desde bruto hasta dorado.

gross-or-net-revenue.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""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%}")
Salidapython 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%

La cifra bruta sobrestima la respuesta dorada en 20.3%. El modelo eligió gross_revenue_eur, una lectura razonable de "ingresos totales" para alguien que nunca ha tratado con el equipo financiero, y respondió 1,987,532.10 euros, frente a los 1,651,527.86 dorados.

La mayor parte de esa diferencia es impuesto. Cambiar a ingresos netos sobre las mismas filas da 1,745,126.98, un paso de casi exactamente los 242,404.96 euros de impuesto, con céntimos de redondeo entre ambos. Dejar fuera los pedidos cancelados, lo que lleva el total a 1,652,978.12 euros, elimina casi todo lo demás, y contar los días hábiles locales en lugar de las fechas UTC cierra la última diferencia, pequeña.

La misma elección falló en otros puntos de la grabación. Para gq-009, el valor medio del pedido por región en marzo de 2026, el modelo promedió gross_revenue_eur sobre todos los pedidos, incluidos los cancelados, cuando la definición de la tienda divide los ingresos netos entre los pedidos que no fueron cancelados. En gq-012, los ingresos totales por región de ventas, el modelo volvió a escoger la cifra bruta. Ninguna de las dos elecciones es descuidada. Cada una es un significado habitual de la palabra fuera de la tienda.

Ninguna de las taxonomías de errores que revisamos tiene una clase para esto. Una taxonomía detallada, NL2SQL-BUGs, clasifica los errores semánticos de texto a SQL en 9 categorías y 31 subcategorías, a partir de 2,018 casos anotados por expertos (Liu et al., KDD 2025). Esa consulta la catalogaría como Attribute Mismatch, una columna incorrecta, lo que nombra el síntoma y no la causa: ninguna de sus clases es "el negocio define esto de forma distinta al esquema". Lo más cercano que encontramos está en una auditoría de anotaciones de benchmarks, que nombra los desajustes entre una pregunta y el conocimiento de dominio que necesita (Jin et al., CIDR 2026). Esa brecha es nuestra lectura de ambos artículos, no un resultado medido, y otras taxonomías podrían tener la clase.

Regla práctica: Trata cada palabra de negocio de una pregunta como una definición que hay que buscar, no como una columna que hay que emparejar. Anota quién es el dueño de cada definición y dale al agente la definición en sí, como métrica gobernada o al menos como entrada de glosario, nunca solo las columnas con las que podría calcularla. Cuando una palabra no tiene definición escrita, haz que el agente pregunte o se abstenga en lugar de elegir.

Esta parte aún no está traducida, así que está en inglés.

Time zones and the fiscal calendar

Último cambio en la edición 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 Superado
"""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)}")
Salidapython 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.

La tabla con el nombre tentador

Último cambio en la edición 2026.11.12

Una definición puede fallar dentro de la tabla correcta; una tabla completa puede ser la equivocada. La mayoría de los almacenes de datos conservan tablas que nadie debería consultar ya y que nadie puede eliminar: un mart de datos antiguo que leen los paneles de control viejos, una copia de una migración, una tabla construida para un análisis concreto. Una tabla así suele tener los nombres de columna más amigables de todo el almacén, porque se construyó pensando en las personas, y sus definiciones son las antiguas. Un modelo que elige tablas por su nombre puede preferirla. Spider 2.0, un benchmark de tareas empresariales de text-to-SQL, encontró que elegir la tabla equivocada explicaba el 10.1 % de los errores en una muestra de 300 tareas fallidas procedentes de dos frameworks de agentes (Lei et al., ICLR 2025).

El almacén de la tienda tiene una: analytics.orders_legacy, que tiene columnas llamadas revenue y sales_region. Sus ingresos son brutos, con impuestos incluidos, y conserva los pedidos de prueba y los cancelados. La pregunta dorada gq-012, "¿Cuáles fueron los ingresos totales por región de ventas en 2025?", usa ambos nombres de columna, y se escribió para tentar al modelo hacia ella, al igual que gq-013, que pide pedidos por región de ventas. A continuación, dos comprobaciones: qué responde la tabla antigua y si las consultas del modelo llegan a leerla.

legacy-table-answer.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""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)}")
Salidapython 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

Quien sume la columna revenue de la tabla antigua agrupada por sales_region para 2025 obtiene un total +21.4% superior al de la tabla dorada, bajo un nombre de columna que dice que se trata de ingresos. Para EMEA la tabla da 962,439.56 euros, mientras que los ingresos netos dorados son 749,006.73. En todas las regiones, sus filas de 2025 incluyen 62 pedidos de prueba.

El modelo registrado nunca la leyó. Sus consultas para las preguntas doradas gq-001 a gq-016 tocaron orders_legacy en 0 of 16 casos. En este almacén, fct_orders tiene una columna region y ambas columnas de ingresos, y el modelo la prefirió en todas las ocasiones. Es un resultado sobre este modelo, este esquema y estas preguntas, no una garantía. El riesgo crece con el almacén: las bases de datos de Spider 2.0-lite tienen de media más de 755 columnas, frente a unas 54 en BIRD, un benchmark académico (Lei et al., ICLR 2025). Entre cientos de tablas, esperamos que los nombres amigables de una tabla antigua coincidan más a menudo con las palabras de una pregunta. Esperamos también que el riesgo aumente cuando a un agente se le dan ejemplos o descripciones recuperados, porque una búsqueda por nombres puede situar la tabla antigua entre los primeros resultados.

Por esa razón, mantenemos orders_legacy en el almacén a lo largo de todo el libro. Una tabla que no puedes eliminar es una tabla que un agente puede encontrar, y la defensa debe estar por debajo del modelo: una lista de las tablas que puede leer.

Regla práctica: Haz una lista de las tablas que un agente puede leer, y deja fuera las tablas heredadas y de staging aunque tengan los nombres más amigables. Comprueba las tablas de cada consulta escrita por el modelo contra la lista antes de ejecutarla. Cuando en tus pruebas un agente nunca elija una tabla tentadora, mantén la comprobación de todos modos: una pregunta nueva, un esquema más grande o un ejemplo recuperado pueden cambiar ese resultado.

Filtros que nadie escribió

Último cambio en la edición 2026.11.12

Hay reglas sobre qué filas cuentan que son tan familiares para quienes son dueños de una cifra que nadie las escribe: los pedidos cancelados no cuentan como ingresos, las cuentas de prueba no son clientes, y un reembolso pertenece al mes de su pedido. Una regla así vive en el SQL del mart, en los informes del equipo de finanzas y en la cabeza de la gente. Una consulta que la omite devuelve todas las filas, lo que parece la respuesta más completa, no una respuesta equivocada. El capítulo 1 lo mostró una vez, con los ingresos netos por región.

Quienes escriben los benchmarks de texto a SQL también pasan por alto estos filtros. En la base de datos california_schools del benchmark BIRD, el SQL de referencia omite la condición sobre la columna rtype, que es lo que distingue escuelas de distritos, porque los anotadores habían marcado esa columna como "inútil" (Jin et al., CIDR 2026). Una regla que nadie escribió desaparece tanto de la clave de respuestas como de la consulta del modelo.

Los marts de la tienda aplican una de estas reglas por ti: eliminan los pedidos de prueba. No pueden eliminar los pedidos cancelados, porque algunas preguntas tratan sobre cancelaciones, así que fct_orders los conserva con su status, y las líneas de pedido también los conservan. Se trata de la pregunta dorada gq-015, "¿Cuántas unidades de cada categoría de producto vendimos en 2025?", que necesita el estado de una tabla para filtrar filas de otra. La consulta del modelo nunca descarta los pedidos cancelados, y el ejemplo muestra el costo.

cancelled-lines-counted.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""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}")
Salidapython 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

Omitir el estado es casi todo el error. El modelo sumó quantity de fct_order_lines para los pedidos de 2025 sin ninguna condición de estado, así que cuenta unidades de pedidos cancelados dentro de su rango de fechas. En todas las categorías dice 22324 unidades frente a las 21108 de la referencia dorada, 5.8% de más. La diferencia es casi toda de pedidos cancelados; las 10 unidades restantes son el neto de pedidos cuyos días UTC y locales caen en años distintos.

Para Cooking el modelo dice 5727 unidades, donde la respuesta dorada es 5427.

Los pedidos de prueba muestran el otro lado. Las líneas de pedido sin procesar contienen 202 unidades en pedidos de prueba de 2025, y la respuesta del modelo no los incluyó, porque leyó el mart y el mart ya había aplicado esa regla. Un filtro que aplica el mart es uno que el modelo no puede olvidar. En todas las consultas que escribió para este capítulo, el modelo leyó los marts, nunca las tablas sin procesar, así que los pedidos de prueba nunca llegaron a una respuesta.

La consulta tampoco preguntó si una unidad vendida fue devuelta después. La definición de unidades vendidas de la tienda no resta las devoluciones, así que la respuesta dorada tampoco lo hace. Esa es una regla más que debe escribirse en un lugar donde el agente pueda leerla; de lo contrario, la siguiente persona responderá de forma razonable de otra manera.

Regla práctica: Traslada toda regla sobre qué filas cuentan a los marts siempre que sea posible, para que ninguna consulta pueda olvidarla. Cuando un mart tenga que conservar las filas, como con los pedidos cancelados, escribe la regla en la definición que usa el agente y añade una pregunta dorada que falle si la regla se omite. Revisa también la referencia dorada en busca de las mismas reglas, porque quien la escribió puede pasarlas por alto con la misma facilidad que el modelo.

Cuenta los fallos por tipo

Último cambio en la edición 2026.11.12

Cada sección hasta ahora mostró un fallo en una sola pregunta. Para decidir qué corregir primero, necesitas saber con qué frecuencia aparece cada tipo en tus preguntas, y cuáles fallos son errores visibles y cuáles son números incorrectos plausibles. El conjunto es pequeño, así que los recuentos describen esta ejecución, no una tasa que puedas citar.

Esta ejecución toma el SQL que el modelo, con solo el esquema, genera para cada pregunta de referencia desde gq-001 hasta gq-016 que tiene respuesta; son 15 de ellas, así que sus fallos pueden contarse. Deja fuera gq-005, un pronóstico que debe rechazarse, tema del capítulo 8. Compara cada resultado con el resultado de referencia y lo califica como correcto, incorrecto o error, y etiqueta cada consulta con sus tipos de fallo. Las etiquetas provienen de lib/failure_kinds.py, que analiza la consulta del modelo y su SQL de referencia con sqlglot y los compara. Por ejemplo, una consulta que usa placed_at donde el SQL de referencia usa el día hábil local recibe la etiqueta time. Las reglas son nuestras, escritas para las trampas de este almacén de datos; la cadena de documentación del módulo enumera cada una.

classify-schema-only-errors.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""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}")
Salidapython 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

La mayoría de los fallos se ejecutaron y devolvieron un número, el tipo más difícil de detectar: 8 of 15 respuestas incorrectas, frente a 5 of 15 consultas que fallaron al ejecutarse. De los errores, 4 usaban una columna que no existe en la tabla que leían, como fiscal_year en fct_orders, y 1 comparaban una marca de tiempo con un patrón de texto usando LIKE.

Las respuestas incorrectas son las costosas. 6 de ellas tienen un error de tiempo y 6 un filtro no escrito. La mayoría de las respuestas incorrectas tenían dos o tres tipos a la vez, por eso las secciones sobre fan-out y definición cambiaron una elección a la vez para separarlos.

Las definiciones aparecen en 3 respuestas incorrectas, el fan-out en 1, y la tabla tentadora en 0, como encontró su sección.

Una calificación correcta no significa una consulta correcta. Las respuestas correctas, gq-014 y gq-016, llevan ambas la etiqueta time: sus consultas cuentan fechas UTC, y los recuentos coincidieron por razones distintas. En el caso de gq-014, los pedidos cruzaron los límites de mayo en ambos sentidos: 3 entraban solo por UTC y 3 solo por día local, como mostró la sección sobre el tiempo. En el caso de gq-016, un recuento de clientes distintos, 6 clientes tenían un pedido en los límites del año, y 6 de ellos tenían otros pedidos en 2025 según ambos relojes, así que el recuento no podía cambiar. La coincidencia del nombre de la carpa (tent) en gq-007 no tiene etiqueta, porque ninguna regla la busca.

Cada uno de los cinco tipos del libro tiene un vecino cercano en las taxonomías publicadas, con otro nombre. La correspondencia es nuestro criterio:

Tipo en este libro Clase publicada más cercana
fan-out Discrepancia en la condición de unión; Funciones de agregación [1]
definición ninguna; la más cercana es una discrepancia de conocimiento del dominio (E3) [2]
tiempo Funciones de fecha y hora [1]
tabla tentadora Discrepancia de tabla [1]
filtro no escrito Falta de condición implícita; falta de condición explícita [1]

La fuente [1] es NL2SQL-BUGs (Liu et al., KDD 2025), y la [2] es la auditoría de anotaciones de benchmarks de CIDR 2026 (Jin et al.). Sus clases son más finas que las nuestras, y las nuestras son más generales a propósito: cada uno de los cinco apunta a una corrección en el almacén de datos o en lo que se le da al agente.

Esa correspondencia también responde qué fallos puede corregir un prompt mejor. Un prompt puede incluir buenas prácticas generales, como agregar las líneas antes de unirlas con los pedidos, y puede incluir datos concretos de un almacén, como qué columna de fecha es el día hábil. No puede incluir las definiciones de la tienda para cada palabra que usa la gente, y un prompt que lo intente se convierte en una segunda copia, no revisada, de ellas. Esperamos que un prompt reduzca el fan-out y algunos errores de tiempo, y que solo las definiciones que el agente pueda leer y el almacén haga cumplir eliminen los otros tres tipos. Ese es un criterio que apoya la ejecución de este capítulo, no algo que esta ejecución mida. Los benchmarks muestran una brecha similar a mayor escala. En Spider 2.0, un marco de agente construido sobre o1-preview resolvió el 21.3 % de las tareas empresariales, mientras que los métodos basados en GPT-4 habían alcanzado el 91.2 % en Spider 1.0 y el 73.0 % en BIRD (Lei et al., ICLR 2025). Los tres números provienen de sistemas y formatos de tarea distintos, así que ilustran la brecha en lugar de medirla.

Regla práctica: Cuenta los fallos por tipo en tus propias preguntas de referencia antes de elegir una corrección, y mantén separados los errores que fallan de forma visible de los números incorrectos que no. Etiqueta los tipos comparando cada consulta con su SQL de referencia, con reglas que puedas leer, y lee las respuestas incorrectas que ninguna regla etiqueta. Corrige primero el tipo más común de número incorrecto, y espera que sea una definición, un calendario o un filtro con más frecuencia que un error de sintaxis.

Qué sale mal en producción

Último cambio en la edición 2026.11.12

Los fallos de este capítulo surgieron de preguntas escritas para encontrarlos. En producción, las preguntas las escriben personas que no saben dónde están las trampas.

Dos errores se cancelan y el número parece correcto. El fan-out y la coincidencia de nombres de la pregunta sobre las tiendas de campaña tiraban en direcciones opuestas, y los recuentos en UTC de dos preguntas coincidieron porque los errores se cancelaron o no llegaron a verse. Una comprobación puntual contra una cifra conocida supera estos casos. Solo lo notas si comparas cada resultado con un resultado de referencia bajo una misma regla, y si lees el SQL de las respuestas que pasan, no solo el de las que fallan.

Una definición cambia y la antigua sigue respondiendo. Cuando el equipo de finanzas cambia lo que cuenta como ingreso, cada consulta que lo calcula a partir de columnas conserva el significado anterior. Las preguntas de referencia sobre ingresos empiezan a fallar si su SQL de referencia se actualizó, y siguen pasando si no se actualizó. Guarda el SQL de referencia junto a las definiciones de las que depende, y revisa un cambio en cualquiera de los dos junto con el otro.

La tabla heredada aparece más tarde. En la ejecución de este capítulo, el modelo nunca eligió orders_legacy. Un esquema más grande, ejemplos recuperados o una pregunta con el vocabulario de la tabla heredada pueden cambiar eso sin que cambie tu código. Comprueba las tablas de cada consulta contra una lista de tablas permitidas, y registra qué tablas respondieron a cada pregunta, para que un cambio aparezca en un recuento.

Pequeños errores de tiempo hacen que los informes no coincidan. Un recuento que difiere en un pedido del informe de finanzas inicia una conciliación, y la causa es una fecha en UTC donde el negocio usa días locales. Lo notas cuando dos informes del mismo periodo no coinciden, lo cual ocurre tarde. Añade preguntas de referencia en los límites de periodo, donde los dos relojes difieren, y mantenlas en el conjunto.

Un filtro se aplica en un lugar y no en otro. Los pedidos de prueba se eliminan en los marts, así que cualquier consulta sobre las tablas en bruto los vuelve a incluir. Un agente con acceso a raw puede leerla, para una columna que los marts no tienen. Mantén el esquema en bruto fuera del alcance del agente, o dale los filtros como parte de la descripción de cada tabla.

El etiquetador de fallos no detecta tipos nuevos. lib/failure_kinds.py encuentra los cinco tipos que este capítulo conoce, y ninguno más, como mostró la coincidencia de nombres de la tienda de campaña. Un panel de recuentos de fallos por tipo parece completo mientras un tipo nuevo crece sin etiqueta. Lee a mano una muestra de respuestas incorrectas de forma periódica, y añade una regla cuando un tipo nuevo aparezca dos veces.

Regla práctica: Antes de que las cifras de un agente lleguen a alguien, compara cada respuesta con resultados de referencia, mantén preguntas de referencia en los límites de periodo y para cada definición, enumera las tablas que el agente puede leer y lee a mano una muestra de respuestas incorrectas. Cuenta los números incorrectos por tipo, y trata un recuento creciente en cualquier tipo como una alarma.

Decisiones de este capítulo

  • Cinco tipos de número incorrecto pero verosímil: fan-out, una definición que el esquema no sostiene, zonas horarias y el calendario fiscal, una tabla tentadora y un filtro no escrito. Cada uno apunta a una corrección en el almacén de datos o en lo que se le da al agente.
  • Cada fallo se ejecuta, no se describe. Cada fallo que cometió el modelo se ejecuta con su consulta real, y cuando dos errores se combinan, el ejemplo cambia una elección a la vez para medir cada uno.
  • 11 preguntas de referencia se sumaron al conjunto, de gq-006 a gq-016, cada una escrita para tocar una de las trampas del almacén, con SQL de referencia que sigue las definiciones del equipo de finanzas.
  • Los tipos de fallo se etiquetan con reglas que puedes leer, en lib/failure_kinds.py, comparando cada consulta con su SQL de referencia; las respuestas incorrectas que ninguna regla etiqueta se leen a mano.
  • Los errores y los números incorrectos se cuentan por separado. Una consulta que no se ejecuta es un fallo barato; una que devuelve un número verosímil es la que conviene corregir primero.
  • La tabla heredada se mantiene en el almacén, aunque el modelo nunca la eligió aquí, porque una tabla que no puedes eliminar es una que un agente puede encontrar.
  • Las definiciones, no los prompts, son la solución para la mayoría de los tipos. Un prompt puede recoger prácticas generales; las definiciones del negocio deben estar donde el agente las lee y el almacén las hace cumplir.

Este capítulo, en esta edición

Edición 2026.11.15Ejemplos verificados el 19 de nov de 2026Superan la prueba 6 de 6 ejemplos ejemplos de este capítulo

Traducido del libro en inglés, edición 2026.11.15.

Cita esta sección

Formato

Cada formato cita el libro en inglés, que esta traducción sigue.

Cada formato nombra esta edición. Su enlace abre la edición actual, donde el encabezado de cada sección indica cuándo cambió su texto por última vez. Las fechas de acceso y de recuperación son el día en que lo abres.

En esta página

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

  1. Joins que se multiplican e inflan una suma
  2. Definiciones que el esquema no recoge
  3. Time zones and the fiscal calendar
  4. La tabla con el nombre tentador
  5. Filtros que nadie escribió
  6. Cuenta los fallos por tipo
  7. Qué sale mal en producción
  8. Decisiones de este capítulo

Volver arribaTodos los capítulos