Construye preguntas doradas a partir de tu propio trabajo

Unos 26 minutos de lectura, con 8 ejemplos en 9 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

Al terminar este capítulo, podrás escribir preguntas doradas a partir de las preguntas que hacen las personas de tu negocio, cada una con su SQL dorado, el rol que la formula y el tipo de respuesta que necesita. Podrás comparar los resultados de un agente con resultados dorados en lugar de comparar el texto del SQL, revisar el propio oro antes de confiar en él, y explicar por qué una puntuación en un benchmark público no es una puntuación en tu almacén de datos.

El capítulo 1 evaluó dos enfoques con cinco preguntas doradas, y cinco preguntas solo sirven como prueba de humo. Un cambio en el prompt que arregla o rompe una pregunta mueve la puntuación en una quinta parte, y un cambio que arregla una y rompe otra no la mueve en absoluto. Ninguna de ellas comprueba una negativa ante una pregunta ambigua ni ante una pregunta que el rol de quien pregunta no puede ver. Cada capítulo posterior de este libro cambia una parte del agente y afirma que el cambio ayudó. Esas afirmaciones necesitan un conjunto lo bastante grande para medirse, con preguntas que cubran las trampas, los roles y las negativas del almacén de datos, y con una parte reservada sobre la que no se ajusta ningún cambio.

El capítulo 2 añadió otras once, cada una dirigida a una trampa. Este capítulo conserva las dieciséis y construye el conjunto hasta 48 preguntas doradas sobre los pedidos, reembolsos y clientes de la tienda, cuyo almacén de datos generado consulta el agente. Comienza con el argumento a favor de escribir tus propias preguntas, dado que existen benchmarks públicos y son más baratos de descargar que de escribir.

Por qué un benchmark público no es tu prueba

Último cambio en la edición 2026.11.12

Un benchmark público para text-to-SQL o agentes de datos te ofrece preguntas, una base de datos y una respuesta de referencia para cada pregunta, además de una puntuación que otros han reportado sobre el mismo conjunto. Eso lo hace útil para comparar modelos. No te dice cómo le irá a un agente en tu almacén de datos, por dos razones. Las preguntas, los datos y las definiciones del benchmark son de otra persona, así que una puntuación alta indica que el modelo maneja su trabajo. Y las respuestas de referencia son afirmaciones escritas por personas, de modo que la puntuación también mide con qué frecuencia la referencia es correcta.

La segunda razón se ha medido. Una auditoría presentada en CIDR 2026 hizo que expertos comprobaran cada consulta de referencia frente a su pregunta y su esquema, la ejecutaran y ejecutaran sus subconsultas. Encontró errores de anotación en el 52.8 % de BIRD Mini-Dev, en su primera versión de 500 preguntas, y en el 66.1 % de los 121 problemas de Spider 2.0-Snow cuyo SQL de referencia es público, en su archivo spider2-snow-0713 (Jin et al., CIDR 2026). El error más común fue un SQL de referencia que interpretó mal los datos o el esquema. Cuando los autores corrigieron 100 problemas de BIRD Dev y volvieron a ejecutar cinco agentes de código abierto, las puntuaciones cambiaron entre −3 % y +31 % en términos relativos, y un agente pasó del cuarto puesto al primero. Los benchmarks también cambian: el equipo de BIRD revisó Mini-Dev los días 26 y 27 de octubre de 2026, corrigió el SQL de referencia y sustituyó preguntas, y conservó la versión de 2025 como archivo (BIRD Mini-Dev). Estas cifras son las mediciones del artículo, no las nuestras. El libro cita BIRD y Spider y no los distribuye, porque solo distribuye datos bajo CC BY 4.0, CC0 o su propia licencia, y BIRD es CC BY-SA 4.0.

La primera razón se aprecia con datos que el libro sí puede distribuir, así que este capítulo toma una pequeña parte de DABstep, el Data Agent Benchmark for Multi-step Reasoning, que tiene licencia CC BY 4.0. DABstep plantea preguntas sobre las transacciones de un procesador de pagos, puntúa solo la respuesta final y mantiene ocultas la mayoría de sus tareas para su clasificación (el artículo). El conjunto contiene 450 tareas, y solo sus 10 tareas de desarrollo tienen respuestas públicas (el conjunto de datos). La copia del libro, en examples/data/dabstep/, incluye las tres tareas de desarrollo del nivel de dificultad inferior de DABstep y la tabla completa de pagos con 138,236 transacciones, sin cuatro columnas de identificadores que ninguna tarea necesita: direcciones IP con hash, correos electrónicos de compradores y números de tarjeta, y el número de identificación bancaria de cada tarjeta. SOURCE.md recoge la revisión fijada de el conjunto de datos y todos los cambios, y LICENSE es el aviso propio del conjunto de datos. Los comercios de la tabla de pagos son negocios ficticios, y sus nombres proceden de DABstep tal como se publicó. lib/dabstep.py carga la tabla en DuckDB.

Aplicamos el enfoque solo con esquema del capítulo 1 a ambos conjuntos con un mismo modelo, Qwen3-4B-Instruct-2507, reproducido a partir de una grabación. El modelo recibe el esquema de una tabla y una pregunta, escribe SQL, y ese SQL se ejecuta. En DABstep, el modelo lee después el resultado de la consulta y da una respuesta final en el formato que pide la tarea. La grabación dabstep-runs contiene esas respuestas.

public-vs-own-score.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Score schema-only SQL on three public DABstep tasks and on the shop's dev questions, with the same model.The point about task 49 rests on its "SQL ran: False" line, which the assert checks, and on the two top-country linesthat follow it, which read the same fraud data by two definitions."""from lib import dabstepfrom lib.golden import load_golden, schema_only_outcomefrom lib.model import RecordedModelfrom lib.warehouse import connect, describe_schemapayments = dabstep.connect()runs = [dabstep.answer_task(payments, RecordedModel("dabstep-runs"), task) for task in dabstep.load_tasks()]  # replays recorded repliesfor run in runs:    print(f"task {run.task.task_id}: answered {run.answer[:40]!r}, expected {run.task.answer!r}, correct: {run.correct}")    print(f"task {run.task.task_id} SQL ran: {not run.result.startswith('error')}")print(f"DABstep correct: {sum(run.correct for run in runs)} of {len(runs)}")task49 = next(run for run in runs if str(run.task.task_id) == "49")assert task49.result.startswith("error")  # a query that fails comes back as text that starts with "error"# Task 49 asks for the top country "for fraud". DABstep's manual defines fraud as fraudulent volume over total volume.by_count, by_volume = payments.execute("""    SELECT arg_max(ip_country, frauds), arg_max(ip_country, fraud_share) FROM (        SELECT ip_country, count(*) FILTER (has_fraudulent_dispute) AS frauds,               sum(eur_amount) FILTER (has_fraudulent_dispute) / sum(eur_amount) AS fraud_share        FROM payments GROUP BY ip_country)""").fetchall()[0]  # one row: the top country by each measureprint(f"task 49 top by count of frauds: {by_count}")print(f"task 49 top by fraud volume ratio: {by_volume}")con = connect()schema, model = describe_schema(con), RecordedModel("schema-only-sql")  # the recorded replies to the schema-only promptdev = [q for q in load_golden() if q.split == "dev"]outcomes = [schema_only_outcome(con, model, schema, q) for q in dev]print(f"shop dev correct: {outcomes.count('correct')} of {len(dev)}")
Salidapython public-vs-own-score.py
task 5: answered 'NL', expected 'NL', correct: True
task 5 SQL ran: True
task 49: answered '3. ES', expected 'B. BE', correct: False
task 49 SQL ran: False
task 70: answered '```sql\nSELECT \n  AVG(CAST(p.has_fraudule', expected 'Not Applicable', correct: False
task 70 SQL ran: False
DABstep correct: 1 of 3
task 49 top by count of frauds: NL
task 49 top by fraud volume ratio: BE
shop dev correct: 2 of 24

Los dos conjuntos plantean cuestiones distintas, así que ninguna de las puntuaciones predice la otra, y la diferencia no es lo importante. El SQL solo con esquema acierta 1 of 3 tareas de DABstep, puntuadas con una versión simplificada de la coincidencia casi exacta de DABstep, y 2 of 24 preguntas de desarrollo. Las tareas de DABstep tratan de una sola tabla, sin calendario fiscal, sin pedidos cancelados y sin data mart heredado. Las preguntas de la tienda fallan precisamente en esos aspectos.

La tarea 49 muestra de qué depende una referencia. Pide el país principal "por fraude", y su referencia es BE. Contado por el número de transacciones fraudulentas, el país principal es NL. Medido como la proporción fraudulenta del volumen de pagos, es BE. El manual de DABstep lo resuelve: el fraude es "la proporción del volumen fraudulento sobre el volumen total" (el manual). La pregunta por sí sola no lo resuelve. En este caso, el SQL del modelo para la tarea 49 no llegó a ejecutarse, pero aun así nombró un país. La referencia de la tarea 70 es Not Applicable. Según nuestra lectura del manual, describe comisiones relacionadas con el fraude, pero no una multa. El modelo respondió con una consulta en lugar de una respuesta.

Regla práctica: Usa los benchmarks públicos para comparar modelos en una tarea común, y nunca como prueba de que un agente funciona en tu almacén de datos. Cita la versión del benchmark junto a cualquier puntuación que menciones, porque los conjuntos de referencia se corrigen. Mide tu propio agente con preguntas de oro (golden questions) escritas a partir de tu trabajo, con tus definiciones, y espera que las dos puntuaciones no coincidan.

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

Write questions from the work people do

Último cambio en la edición 2026.11.15

A public benchmark measures someone else's work, so this set has to come from the shop. The best source is the questions people already ask: requests in the analytics team's queue, the numbers in a monthly finance pack, the filters people set on dashboards. Write each in the asker's words, not tidied into the schema's vocabulary, because the agent will hear the asker's words. Then write the golden SQL that answers it under the business's definitions, and check it.

Each golden question holds the same fields. The question is the asker's text. The role is who asks, which decides what they may see, and a regional_lead also carries their region. A golden question's kind says what a right answer looks like: answer when the warehouse can answer it, decline when it can't, and forbidden when the role may not see the answer. A decline also has a decline_type, ambiguous or unanswerable. An answerable question has golden_sql, a comparison rule (order_matters and a tolerance), and a note that names the definition the gold follows. Each question also lists the warehouse's traps it tests, such as fiscal-calendar or late-refunds, and sits in the dev or the test split.

The shop's set lives in examples/data/golden/questions.toml, and load_golden() in lib/golden.py reads it into GoldenQuestion objects. The file's header states the two definitions most questions depend on. Net revenue is the finance team's: euros after discounts and before tax, from real orders that weren't cancelled, on the order's local business day. An order count includes cancelled orders and leaves out test orders. One question in full shows what its fields hold.

load-golden-questions.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Load the shop's golden questions, show what one holds and how the set divides, and compute one gold's other reading.The prose's refund point rests on the last two lines, which group the same refunds by the order's month and by the refund's."""from collections import Counterfrom lib.golden import golden_result, load_goldenfrom lib.warehouse import connectcon = connect()questions = load_golden()print(f"golden questions: {len(questions)}")for kind, count in sorted(Counter(q.kind for q in questions).items()):    print(f"{kind}: {count}")for decline_type, count in sorted(Counter(q.decline_type for q in questions if q.kind == "decline").items()):    print(f"decline, {decline_type}: {count}")print(f"roles: {', '.join(sorted({q.role for q in questions}))}")q = next(q for q in questions if q.question_id == "gq-018")print()print(f"{q.question_id} ({q.split}, {q.kind}, asked by {q.role})")print(f"question: {q.question}")print(f"golden SQL: {' '.join(q.golden_sql.split())}")print(f"traps: {', '.join(q.traps)}")print(f"note: {q.note}")# The other reading: refunds grouped by the month they were made, not the month the order was placed.by_refund_month = con.execute(    "SELECT round(sum(amount_eur), 2) FROM analytics.fct_refunds WHERE refund_month = DATE '2026-03-01'").fetchall()print(f"refunded on orders placed in March 2026: {golden_result(con, q)[0][0]:,.2f}")  # gq-018's gold: by the order's monthprint(f"refunded in March 2026, by refund month: {by_refund_month[0][0]:,.2f}")
Salidapython load-golden-questions.py
golden questions: 48
answer: 34
decline: 8
forbidden: 6
decline, ambiguous: 4
decline, unanswerable: 4
roles: analyst, finance, marketing, regional_lead, support

gq-018 (dev, answer, asked by finance)
question: How much was refunded, in euros, on orders placed in March 2026?
golden SQL: SELECT round(sum(r.amount_eur), 2) AS refunded FROM analytics.fct_refunds AS r WHERE r.order_month = DATE '2026-03-01'
traps: late-refunds, currency
note: Refunds belong to the order's month here, including refunds made in April or later.
refunded on orders placed in March 2026: 13,046.38
refunded in March 2026, by refund month: 6,646.99

Most of the set asks for an answer; the rest tests when to hold back. The set holds 48 questions: 34 to answer, 8 to decline and 6 that the asking role may not see.

Of the declines, 4 are ambiguous and 4 are unanswerable. Every role in the case asks at least one question.

The question the example prints, gq-018, is one a finance team asks after every month closes. Its golden SQL is short, and its value is in the definition: refunds belong to the month the order was placed, including refunds made weeks later. Refunds on orders placed in March 2026 come to 13,046.38 euros, and a reasonable query that picks refunds by the month they were made returns 6,646.99. Both numbers are useful. The golden question records which one this asker means, and its note says so in words a reviewer can check without reading SQL.

Most of the work is deciding what the asker meant and finding the definition someone owns. Write the note first. If you can't write it in one sentence, the question is ambiguous, and it becomes a decline.

Working rule: Collect golden questions from real requests, keep the asker's wording, and give each one a role, a kind and a note that names the definition its gold follows. Write the golden SQL against the marts the agent will use, and have the person who owns the definition read the note. Expect to spend more time on the definitions than on the SQL.

Comparar resultados, no el texto del SQL

Último cambio en la edición 2026.11.12

Con las preguntas doradas escritas, la siguiente decisión es cómo saber si la respuesta de un agente coincide. Comparar el SQL del agente con el SQL dorado falla en ambos sentidos. Dos consultas pueden escribirse de forma distinta y devolver las mismas filas, y dos consultas que difieren en unas pocas palabras pueden devolver números diferentes. Lo que ve quien hace la pregunta es el resultado, así que eso es lo que hay que comparar. Una coincidencia de ejecución significa que el resultado del agente es igual al resultado dorado según la regla de comparación de la pregunta. Los benchmarks hacen lo mismo: BIRD informa la precisión de ejecución, que compara las filas que devuelve cada consulta (calculate_ex en el código de evaluación de BIRD), y DABstep puntúa la respuesta final mediante una coincidencia casi exacta (el artículo).

En la tienda, gq-001 pide los ingresos netos del año fiscal 2026. Su SQL dorado suma net_revenue_eur sobre fct_orders, unido a dim_date para el año fiscal. Su consulta de comprobación, que usa la sección sobre cómo comprobar el dorado, suma net_amount_eur sobre fct_order_lines con un intervalo de fechas. Dos consultas muestran dónde el texto y los resultados se separan, comparadas cada una con el SQL dorado: la consulta de comprobación, y el SQL dorado sin su filtro de pedidos cancelados. Para cada una, se pregunta si el texto es igual, si es igual después de que sqlglot normalice ambos, y si los resultados coinciden según results_match().

results-match-rules.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Two queries written differently for the same golden question: compare their text, then compare their results.The point rests on the last two result lines, "results match": the order-lines query matches the golden result, andthe query that forgets cancelled orders does not. The asserts at the end check both."""import sqlglotfrom lib.golden import golden_result, load_golden, results_matchfrom lib.warehouse import connectcon = connect()q = next(q for q in load_golden() if q.question_id == "gq-001")   # net revenue in fiscal year 2026by_orders, by_lines = q.golden_sql, q.check_sql                    # orders joined to dim_date; lines by date rangeforgets_cancelled = by_orders.replace("o.status <> 'cancelled' AND ", "")  # the golden SQL's cancelled-order filter, removeddef normalized(sql: str) -> str:    # parses and writes the SQL back in DuckDB's form, so spacing and identifier case don't count as differences    return sqlglot.parse_one(sql, read="duckdb").sql(dialect="duckdb", normalize=True, pretty=False)golden = golden_result(con, q)for name, sql in [("by lines", by_lines), ("forgets cancelled", forgets_cancelled)]:    rows = con.execute(sql).fetchall()    print(f"{name}: {rows[0][0]:,.2f} against golden {golden[0][0]:,.2f}")    print(f"{name} same text: {sql == by_orders}")    print(f"{name} same normalized text: {normalized(sql) == normalized(by_orders)}")    print(f"{name} results match: {results_match(rows, golden)}")# a change to either result must fail this run, as the prose states both factsassert results_match(con.execute(by_lines).fetchall(), golden)assert not results_match(con.execute(forgets_cancelled).fetchall(), golden)
Salidapython results-match-rules.py
by lines: 1,664,762.75 against golden 1,664,763.72
by lines same text: False
by lines same normalized text: False
by lines results match: True
forgets cancelled: 1,755,242.00 against golden 1,664,763.72
forgets cancelled same text: False
forgets cancelled same normalized text: False
forgets cancelled results match: False

La consulta sobre las líneas de pedido lee una tabla distinta, así que su texto difiere del dorado incluso después de normalizar. Su resultado coincide: suma 1,664,762.75 against golden 1,664,763.72, a menos de un euro del dorado, ya que cada línea se redondea al céntimo y la tolerancia absorbe esa diferencia. La consulta que olvida los pedidos cancelados devuelve 1,755,242.00 against golden 1,664,763.72, y su resultado no coincide. En el texto, está a un predicado del dorado. Normalizar no salva una comparación de texto en ninguno de los dos sentidos, porque ningún analizador puede saber que dos uniones distintas dan la misma suma con estos datos.

Una coincidencia de ejecución tiene su propio punto ciego. Una consulta puede devolver el número correcto por una razón equivocada con los datos de hoy, por ejemplo un filtro que casualmente no elimina ninguna fila. La defensa es comprobar más preguntas y leer el SQL tras las coincidencias sorprendentes. Esa es una de las razones por las que el conjunto tiene 48 preguntas y no 5.

Regla práctica: Puntúa a un agente comparando su resultado con el resultado dorado, nunca comparando el texto del SQL, normalizado o no. Usa una sola función de comparación para cada puntuación que informes, de modo que un cambio en la puntuación sea un cambio en el agente. Cuando una coincidencia te sorprenda, lee el SQL del agente, porque un resultado puede coincidir por casualidad.

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

Order, rounding and column names

Último cambio en la edición 2026.11.15

A comparison of results still needs rules for the ways two correct results differ. Rows come back in any order unless the query sorts them. Columns carry whatever names the writer chose, in whatever order. Numbers are rounded differently. A rule that is too strict marks correct answers wrong, and a rule that is too loose lets wrong ones through.

results_match(), the comparison every score in this book uses, makes these choices. Rows may come in any order, unless the golden question sets order_matters. Column names are ignored, and columns may come in any order: it tries each way of lining up the answer's columns with the golden ones. Extra columns are allowed, such as a month next to a total for that month, but the number of rows must be equal. Numbers must agree with the gold within 0.05% relative by default, plus an absolute slack of half a unit in the last place the gold rounds to. For money, rounded to the cent, that's half a cent, the default. Changing gq-002's golden result, net revenue in each region in March 2026, the ways real answers differ, and comparing each with the original shows which differences the comparison forgives.

tolerant-comparison.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Change the golden result for net revenue by region in March 2026 in the ways real answers differ, and compare.Then move a ratio gold, gq-033's conversion rates, by a near miss. The prose's claims about thousands and about thenear miss rest on the lines that print True or False, and the asserts check them."""from lib.golden import golden_result, load_golden, results_matchfrom lib.warehouse import connectcon = connect()q = next(q for q in load_golden() if q.question_id == "gq-002")golden = sorted((region, float(revenue)) for region, revenue in golden_result(con, q))  # sorted by region, so the variants line upprint(f"golden: {golden}")print(f"tolerance: {q.tolerance:.2%} relative")print(f"absolute slack: {q.absolute}")variants = {    "rows reversed": golden[::-1],    "columns swapped": [(revenue, region) for region, revenue in golden],    "extra month column": [(region, "2026-03", revenue) for region, revenue in golden],    "rounded to whole euros": [(region, round(revenue)) for region, revenue in golden],    "rounded to thousands": [(region, round(revenue, -3)) for region, revenue in golden],  # round(x, -3) rounds to the nearest thousand    "in thousands of euros": [(region, revenue / 1000) for region, revenue in golden],  # same numbers, unit changed to thousands    "one region missing": golden[:-1],  # drops the last region}for name, rows in variants.items():    print(f"{name}: {results_match(rows, golden, q.order_matters, q.tolerance)}")# reporting in thousands of euros must fail: a change of unit the agent doesn't state is a real errorassert not results_match(variants["in thousands of euros"], golden, q.order_matters, q.tolerance)ranked = sorted(golden, key=lambda row: -row[1])  # highest revenue first, so the reversed list is the wrong orderprint(f"ranking reversed, order matters: {results_match(ranked[::-1], ranked, order_matters=True)}")# A ratio: gq-033's conversion rates, rounded to four places, with its absolute slack of half that last place.rates_q = next(q for q in load_golden() if q.question_id == "gq-033")rates = [(channel, float(rate)) for channel, rate in golden_result(con, rates_q)]near_miss = [(channel, rate + 0.004) for channel, rate in rates]  # 0.004 is about 3% of each rateprint(f"gq-033 rates: {min(r for _, r in rates):.4f} to {max(r for _, r in rates):.4f}")print(f"gq-033 absolute slack: {rates_q.absolute:.5f}")print(f"rates 0.004 higher, gq-033's rule: "      f"{results_match(near_miss, rates, rates_q.order_matters, rates_q.tolerance, rates_q.absolute)}")print(f"rates 0.004 higher, half a cent of slack: {results_match(near_miss, rates, rates_q.order_matters, rates_q.tolerance)}")# under the question's own slack the near miss is a miss; with half a cent of slack the same near miss matchesassert not results_match(near_miss, rates, rates_q.order_matters, rates_q.tolerance, rates_q.absolute)assert results_match(near_miss, rates, rates_q.order_matters, rates_q.tolerance)
Salidapython tolerant-comparison.py
golden: [('AMER', 51762.14), ('APAC', 35296.93), ('EMEA', 63023.76)]
tolerance: 0.05% relative
absolute slack: 0.005
rows reversed: True
columns swapped: True
extra month column: True
rounded to whole euros: True
rounded to thousands: False
in thousands of euros: False
one region missing: False
ranking reversed, order matters: False
gq-033 rates: 0.1156 to 0.1284
gq-033 absolute slack: 0.00005
rates 0.004 higher, gq-033's rule: False
rates 0.004 higher, half a cent of slack: True

Reversed rows, swapped columns and an extra month column all match, and so does rounding to whole euros, which moves a regional total by at most half a euro. Rounding to thousands of euros fails, and so does reporting in thousands of euros. A person reading a small number under a heading of thousands would understand it, but the comparison can't see the heading. That's deliberate. An agent that changes units without saying so is a risk, so the golden question fixes the unit and the agent must meet it. A missing region fails. For a ranking, such as gq-039's, order_matters is set, so the regions ranked by revenue in reverse order fail too.

The tolerance needs care in both directions. Ratios such as a conversion rate are small numbers, where half a cent of slack is a lot. gq-033's conversion rates run from 0.1156 to 0.1284, so 0.005 is about 4% of each. Its gold rounds to four places, and its absolute slack is half that last place, 0.00005. Adding 0.004 to every rate is a near miss at this scale: under gq-033's rule it fails, and with half a cent of slack it would match. The book's other ratios, gq-031 and gq-034, follow the same rule.

Working rule: Ignore row order, column order and column names, allow extra columns, and require the same number of rows and numbers within a small relative tolerance. Round each gold to a stated place, and allow half a unit in that place on top. Set order_matters only when the question asks for a ranking or a sequence. Fix units and scale in the question or its note, and treat an answer in other units as wrong, because nobody reading it can tell.

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

Check the gold before you trust it

Último cambio en la edición 2026.11.15

Public benchmarks show what happens to unchecked gold: about half of one set was wrong. A golden question written in an afternoon is no different. Its SQL can miss a filter, read the wrong table or follow a definition nobody owns, and every score built on it inherits the mistake. So check each gold before it scores anything. It must run. It must return rows, without NULL values, since an empty gold matches any query that also returns nothing. Where you can, a second query written another way, the gold's check_sql, must return the same result as the golden SQL. And its note must name the definition it follows, so a person can say whether it's the right one.

The shop's set gets those checks, with each check query written independently of its golden SQL: from order lines instead of orders, from a date range instead of the fiscal calendar, or by counting another way. Then look at one question in two readings: which country is top for refunds in fiscal 2026, by the number of refunds and by refund rate.

gold-runs-and-agrees.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Check the gold before trusting it: every golden SQL runs and returns rows, and each check query agrees with it.The prose's gold claims rest on the counts of runs, empty results and agreeing checks, and its refund point on the last two readings."""import duckdbfrom lib.golden import golden_result, load_golden, results_matchfrom lib.warehouse import connectcon = connect()answerable = [q for q in load_golden() if q.kind == "answer"]results, failed = {}, []for q in answerable:    try:        results[q.question_id] = golden_result(con, q)    except duckdb.Error:        failed.append(q.question_id)empty = [qid for qid, rows in results.items() if not rows or any(v is None for row in rows for v in row)]  # a NULL in any cell fails, tooprint(f"golden SQL that runs: {len(results)} of {len(answerable)}")print(f"golden SQL that fails: {', '.join(failed) or 'none'}")print(f"empty or NULL results: {len(empty)}")checked = [q for q in answerable if q.check_sql and q.question_id in results]agree = [q for q in checked if results_match(con.execute(q.check_sql).fetchall(), results[q.question_id],                                             q.order_matters, q.tolerance, q.absolute)]print(f"questions with a check query: {len(checked)}")print(f"checks that agree: {len(agree)} of {len(checked)}")# One question, two readings: "top country for refunds" by number of refunds, and by refund rate (gq-028's definition).# orders join to their local business day; the LEFT JOIN keeps orders that have no refund, so they still countby_count, by_rate = con.execute("""    SELECT arg_max(country, refunds), arg_max(country, refunded / gross) FROM (        SELECT o.country, count(r.refund_id) AS refunds, sum(r.amount_eur) AS refunded,               sum(o.gross_revenue_eur) AS gross        FROM analytics.fct_orders AS o        JOIN analytics.dim_date AS d ON d.date_day = o.order_date_local        LEFT JOIN analytics.fct_refunds AS r USING (order_id)        WHERE o.status <> 'cancelled' AND d.fiscal_year = 2026        GROUP BY o.country)""").fetchall()[0]  # one row: arg_max returns the country at the largest valueprint(f"top country by number of refunds: {by_count}")print(f"top country by refund rate: {by_rate}")print(f"gq-028 golden: {results['gq-028'][0][0]}")
Salidapython gold-runs-and-agrees.py
golden SQL that runs: 34 of 34
golden SQL that fails: none
empty or NULL results: 0
questions with a check query: 7
checks that agree: 7 of 7
top country by number of refunds: US
top country by refund rate: NL
gq-028 golden: NL

The golden SQL runs for 34 of 34 answerable questions, and 0 of them come back empty or with a NULL. Of the 7 questions with a check query, the check agrees with its gold in 7 of 7.

The two readings of the refund question disagree, the same trap as DABstep's task 49: by refunds the top country is US, and by refund rate it is NL. The golden question gq-028 says "highest refund rate" in its text, and its note defines the rate as refunded euros over gross revenue of the same orders. Without both, an agent that answered the other reading would be scored wrong for answering a question nobody wrote down.

The checks above find gold that is broken. Reading the agent's wrong answers finds gold that is unclear. gq-031 first asked about the average number of "items" in an order, and the schema-only baseline from chapter 1 got it wrong: its SQL averaged line_count, the number of order lines, where the gold sums units. "Items" allows both readings. The defect was in the question, not the agent, so the question now asks for units, counting quantities, not order lines. Recorded replies are keyed by the exact question text, so the reworded question needed a new recording. Replaying both wordings below shows the effect.

reworded-golden-question.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Read a wrong answer: gq-031 once asked about "items", which allows units or order lines. It now asks for units.The two `outcome` lines settle whether each wording's baseline answer is right against the gold printed first."""from dataclasses import replacefrom lib.golden import golden_result, load_golden, schema_only_outcomefrom lib.model import RecordedModelfrom lib.prompts import schema_only_messagesfrom lib.tools import extract_sqlfrom lib.warehouse import connect, describe_schemacon = connect()schema, model = describe_schema(con), RecordedModel("schema-only-sql")q = next(q for q in load_golden() if q.question_id == "gq-031")print(f"gq-031 golden: {golden_result(con, q)[0][0]}")for wording, asked in [("items", replace(q, question="How many items did an order contain on average in 2025?")),  # the old wording; the recording keys replies by question text                       ("units", q)]:    sql = extract_sql(model.complete(schema_only_messages(schema, asked.question)))    print(f"{wording} wording: {asked.question}")    print(f"baseline answer, {wording} wording: {con.execute(sql).fetchall()[0][0]:.4f}")    print(f"baseline outcome, {wording} wording: {schema_only_outcome(con, model, schema, asked)}")
Salidapython reworded-golden-question.py
gq-031 golden: 3.4117
items wording: How many items did an order contain on average in 2025?
baseline answer, items wording: 2.5691
baseline outcome, items wording: wrong
units wording: How many units did an order contain on average in 2025, counting quantities, not order lines?
baseline answer, units wording: 3.4124
baseline outcome, units wording: correct

The units wording is right, though its query is still off. The items wording got 2.5691, wrong against a gold of 3.4117, and the units wording got 3.4124. The units query keeps cancelled orders and takes the year from the UTC timestamp, and on this data neither moves the average past the tolerance. That's the blind spot of an execution match: the answer is right, and the query isn't.

At a larger scale, a model can propose suspect golds for a person to check. The extended version of the CIDR audit describes an agent built for this, which flagged erroneous BIRD Mini-Dev examples with 83% precision (Jin et al., arXiv:2601.08778). A person still decides each one.

Working rule: Before a golden question scores anything, run its SQL, reject empty and NULL results, compare it with an independent query where you can, and have the definition's owner read its note. Read the agent's wrong answers for unclear questions, and fix the question, not the score. When a question can be read two ways, name the reading in its text, or make it a decline.

Cubrir rechazos y roles, no solo respuestas

Último cambio en la edición 2026.11.12

Un gold verificado hace que cada pregunta sea confiable, pero el conjunto en su totalidad aún tiene que probar lo que el agente va a encontrar. Un conjunto formado solo por preguntas respondibles recompensa a un agente que responde todo: nunca puede perder puntos por adivinar. Por eso el conjunto de la tienda incluye preguntas cuya respuesta correcta es un rechazo, de dos tipos, porque el comportamiento correcto es distinto. Una pregunta ambigua, como "¿Quiénes son nuestros mejores clientes?", tiene varias respuestas razonables, y el agente debe indicar qué opciones necesita. Una pregunta sin respuesta, como el costo del envío, pide datos que el almacén de datos no contiene, y el agente debe decirlo. Una pregunta prohibida sí tiene respuesta, pero no para el rol que la hace: el equipo de finanzas de la tienda no puede ver los correos de los clientes, y un responsable regional solo puede ver su propia región. El capítulo 8 construye el rechazo y el capítulo 9 construye las reglas de acceso. Este capítulo asegura que el conjunto pueda puntuar ambos.

La cobertura también significa las trampas del almacén de la tienda y los roles de la tienda. Cada trampa integrada en el almacén, desde los pedidos de prueba hasta el mart heredado, debería aparecer en ambas particiones, de modo que un cambio que rompa una trampa se note en cualquiera de las dos puntuaciones. Contar tipos, roles y trampas por partición muestra dónde el conjunto es escaso.

golden-coverage.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Count what the golden set covers in each split: kinds, roles and the warehouse's traps.The prose's coverage point rests on the kind counts and on the last line, which names any trap missing from a split."""from collections import Counterfrom lib.golden import load_goldenquestions = load_golden()splits = ("dev", "test")for split in splits:    print(f"{split} questions: {sum(q.split == split for q in questions)}")print("split  answer  decline  forbidden")for split in splits:    kinds = Counter(q.kind for q in questions if q.split == split)    print(f"{split:<5}  {kinds['answer']:>6}  {kinds['decline']:>7}  {kinds['forbidden']:>9}")for split in splits:    roles = Counter(q.role for q in questions if q.split == split and q.kind == "answer")    print(f"{split} answers by role: {dict(sorted(roles.items()))}")traps = {split: Counter(t for q in questions if q.split == split for t in q.traps) for split in splits}print("trap                  dev  test")for trap in sorted(traps["dev"] | traps["test"]):    print(f"{trap:<20}  {traps['dev'][trap]:>3}  {traps['test'][trap]:>4}")missing = sorted(t for t in traps["dev"] | traps["test"] if not traps["dev"][t] or not traps["test"][t])  # Counter gives 0 for an absent trapprint(f"traps missing from a split: {', '.join(missing) or 'none'}")
Salidapython golden-coverage.py
dev questions: 24
test questions: 24
split  answer  decline  forbidden
dev        17        4          3
test       17        4          3
dev answers by role: {'analyst': 15, 'finance': 1, 'regional_lead': 1}
test answers by role: {'analyst': 10, 'finance': 3, 'marketing': 2, 'regional_lead': 1, 'support': 1}
trap                  dev  test
cancelled-orders        5     8
currency                2     3
definition              2     2
duplicate-customers     2     2
fan-out                 2     2
fiscal-calendar         3     4
late-refunds            1     2
legacy-table            2     1
local-business-day      2     2
net-vs-gross            2     2
null-channel            1     1
role-scope              4     4
test-orders             5     4
vat                     2     1
traps missing from a split: none

Los tipos están equilibrados: cada partición tiene el mismo número de respuestas, rechazos y preguntas prohibidas. Cada trampa aparece en ambas particiones, y la última línea dice traps missing from a split: none. Varias trampas dependen de una sola pregunta en una partición, como el IVA en la partición de prueba, así que una sola etiqueta faltante sacaría una trampa de una partición, y esta línea la nombraría.

Los roles no están equilibrados. Las preguntas respondibles de la partición de desarrollo las hacen el analista, finanzas y un responsable regional. Marketing y soporte hacen preguntas respondibles únicamente en la partición de prueba. Como los prompts y el contexto se ajustan con la partición de desarrollo, ningún ajuste verá una pregunta de marketing que el agente debería responder, y la primera vez que se puntúa es en el conjunto reservado. Mantenemos visible el desequilibrio en lugar de mover preguntas entre particiones después de ver las puntuaciones; las siguientes preguntas que se escriban para esos dos roles irán a desarrollo.

Regla práctica: Incluye rechazos y preguntas prohibidas desde el principio, y separa los rechazos en ambiguos y sin respuesta, porque la respuesta correcta difiere. Etiqueta cada pregunta con las trampas que prueba, y cuenta tipos, roles y trampas por partición antes de puntuar nada. Corrige un vacío escribiendo preguntas nuevas, no moviendo las existentes entre particiones después de haber visto cómo responde el agente.

Reserva un conjunto de prueba

Último cambio en la edición 2026.11.12

Un conjunto que cubre las cosas correctas aún puede engañar, por la forma en que se usa. Cada vez que cambias un prompt porque falló una pregunta, ajustas el agente un poco más a esas preguntas. Tras suficientes cambios, la puntuación sobre ellas mide qué tan bien afinaste, no qué tan bien funciona el agente. La defensa habitual es una partición reservada: afinas con una parte y puntúas la otra solo cuando informas un resultado. El conjunto de prueba oculto de un benchmark reduce el riesgo de que sus respuestas se filtren al entrenamiento (el artículo de DABstep), pero no impide que la gente ajuste el agente al estilo de sus preguntas. Tu propio conjunto reservado tiene que protegerse con la forma en que trabajas.

El conjunto de la tienda tiene 24 preguntas dev, con las que cada capítulo puede afinar, y 24 preguntas test, con las que un capítulo solo puntúa para el número que informa. Puntuar la línea base solo de esquema del capítulo 1 en ambos conjuntos da la marca que cada capítulo posterior debe superar.

baseline-on-both-splits.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""The baseline every later chapter must beat: schema-only SQL scored on the dev split and on the held-out test split.The prose's split counts are the per-split lines, and its declines, forbidden and answer counts the last three lines."""from collections import Counterfrom lib.golden import load_golden, schema_only_outcomefrom lib.model import RecordedModelfrom lib.warehouse import connect, describe_schemacon = connect()schema, model = describe_schema(con), RecordedModel("schema-only-sql")outcomes = {"dev": Counter(), "test": Counter()}by_kind = Counter()for q in load_golden():    outcome = schema_only_outcome(con, model, schema, q)    outcomes[q.split][outcome] += 1    by_kind[q.kind, outcome == "correct"] += 1  # (kind, correct) pairs, counted over both splitsfor split, counts in outcomes.items():    total = sum(counts.values())    for outcome in ("correct", "wrong", "error", "declined"):  # "error" when the SQL fails; grade() gives the rest        print(f"{split} {outcome}: {counts[outcome]} of {total}")    print(f"{split} accuracy: {counts['correct'] / total:.1%}")for kind in ("answer", "decline", "forbidden"):    print(f"{kind} correct, both splits: {by_kind[kind, True]} of {by_kind[kind, True] + by_kind[kind, False]}")
Salidapython baseline-on-both-splits.py
dev correct: 2 of 24
dev wrong: 14 of 24
dev error: 8 of 24
dev declined: 0 of 24
dev accuracy: 8.3%
test correct: 3 of 24
test wrong: 13 of 24
test error: 8 of 24
test declined: 0 of 24
test accuracy: 12.5%
answer correct, both splits: 5 of 34
decline correct, both splits: 0 of 8
forbidden correct, both splits: 0 of 6

La línea base es más débil donde se necesita juicio. En ambos conjuntos acierta 0 of 8 rechazos, 0 of 6 preguntas prohibidas y 5 of 34 preguntas que sí se pueden responder. No rechaza nada, ya que solo escribe SQL.

Acierta 2 of 24 preguntas de desarrollo, con una exactitud de 8.3%, y 3 of 24 preguntas de prueba, con una exactitud de 12.5%. Todas las demás fallan: no se ejecutan, dan un resultado incorrecto o responden lo que debería rechazarse.

Los conjuntos difieren en una pregunta, y todavía no se ha afinado con ninguno. Espera que se distancien cuando los capítulos empiecen a cambiar el contexto en dev. Una puntuación de desarrollo que sube mientras la de prueba no lo hace es la señal de que los cambios se ajustan a las preguntas de desarrollo y no a la tienda. Con 24 preguntas por conjunto, una pregunta equivale a unos cuatro puntos de exactitud, así que trata una diferencia de una o dos preguntas como ruido, y compara las mismas preguntas antes y después de un cambio en lugar de dos totales.

Regla práctica: Divide tus preguntas doradas una vez, antes de afinar nada, y afina solo con las de desarrollo. Puntúa el conjunto de prueba solo cuando informes un resultado, e informa ambos conjuntos lado a lado. Cuando las preguntas de prueba se hayan revisado tantas veces que la gente ajuste a ellas, escribe nuevas preguntas de prueba y pasa las antiguas a desarrollo.

Qué sale mal en producción

Último cambio en la edición 2026.11.12

Las 48 preguntas doradas de la tienda miden el agente de este libro. La misma práctica en un almacén de datos real falla de estas maneras, y cada una tiene una forma de detectarla.

El oro envejece cuando cambia una definición. Si finanzas cambia la definición de ingresos netos, cada consulta dorada que suma net_revenue_eur puede estar equivocada sin que falle. Mantén las preguntas doradas en el repositorio junto con las definiciones y las métricas, revisa los cambios en conjunto y vuelve a ejecutar las consultas de verificación en cada cambio. Una consulta de verificación que deja de coincidir es la alarma.

Los resultados dorados se mueven a medida que llegan los datos. Los reembolsos siguen llegando durante meses después de un pedido, así que los reembolsos de gq-018 sobre los pedidos de marzo de 2026 crecen cada vez que se carga la tabla de reembolsos. Las preguntas doradas sobre períodos abiertos dan un resultado dorado distinto cada semana, y una comparación que guardó el resultado de la semana pasada falla sin motivo. Calcula los resultados dorados a partir del SQL dorado en el momento de la puntuación, como lo hace golden_result(), y prefiere períodos cerrados para las preguntas en las que el número debe permanecer fijo.

El conjunto deja de parecerse a las preguntas que hace la gente. Las preguntas cambian con el negocio: un canal nuevo, una región nueva, una política fiscal distinta. Un conjunto escrito una sola vez se aleja de ellas. Toma muestras de las preguntas que la gente hace al agente, escribe preguntas doradas para las que respondió mal o rechazó, y añádelas al conjunto de desarrollo.

La división de prueba se filtra. Alguien lee las preguntas de prueba que fallan y ajusta el prompt para responderlas, y la puntuación de prueba sube sin que mejore nada más. Lo notas cuando las puntuaciones de desarrollo y de prueba se mueven juntas después de un cambio dirigido a una sola pregunta. Mantén las preguntas de prueba fuera de las discusiones sobre el ajuste, y renuévalas cuando se hayan filtrado.

La puntuación de un benchmark cambia con el benchmark. La precisión que un proveedor reporta en BIRD o Spider describe una versión de un conjunto que sus responsables corrigen. Al comparar modelos, registra la versión del benchmark junto con cada puntuación, y vuelve a puntuar sobre tu propio conjunto antes de cambiar.

La comparación oculta un cambio de unidades. Un agente que empieza a devolver ingresos en miles de euros falla de golpe todas las preguntas de dinero, y una tolerancia más laxa lo ocultaría. Mantén la tolerancia pequeña y relativa, y cuando fallen muchas preguntas a la vez, lee una respuesta antes de tocar la regla.

Regla práctica: Trata el conjunto dorado como código: guárdalo junto a las definiciones, ejecuta sus verificaciones en CI, calcula los resultados dorados en el momento de la puntuación, añade al conjunto de desarrollo preguntas del tráfico real y protege la división de prueba. Cuando una puntuación se mueva, lee las respuestas que cambiaron antes de modificar el conjunto o la comparación.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.12
  • El conjunto principal de evaluación es el propio de la tienda: preguntas de referencia escritas a partir del trabajo que realizan los equipos de la tienda, con roles, tipos y definiciones, en examples/data/golden/questions.toml.
  • Los benchmarks públicos se citan, no se usan para puntuar. BIRD y Spider 2.0 aparecen solo como citas. Un subconjunto de tres tareas de DABstep, bajo CC BY 4.0 y fijado por revisión, muestra que una puntuación pública y una puntuación sobre tu almacén de datos no coinciden.
  • Los datos de DABstep viajan con su licencia. El subconjunto conserva el LICENSE del propio conjunto de datos, elimina cuatro columnas de identificadores, conserva todas las filas y los nombres ficticios de los comercios, y SOURCE.md documenta cada cambio.
  • Se comparan resultados, no el texto del SQL, con una única función, results_match(), para cada puntuación: cualquier orden de filas salvo que la pregunta pida uno, nombres y orden de columnas ignorados, columnas adicionales permitidas, y números dentro de una pequeña tolerancia relativa más media unidad en la última cifra redondeada de la respuesta de referencia.
  • Cada respuesta de referencia se verifica antes de puntuar: se ejecuta, devuelve filas sin valores NULL y coincide con una consulta independiente cuando existe. Su nota indica su definición.
  • Los rechazos y las preguntas prohibidas forman parte del conjunto: los rechazos se dividen en ambiguas e sin respuesta posible, y las preguntas prohibidas se distribuyen entre los roles de la tienda.
  • El conjunto se divide una sola vez en mitades iguales de desarrollo y de prueba, con los tipos equilibrados. Los capítulos ajustan con el desarrollo y puntúan la prueba solo para las cifras que reportan.
  • El SQL basado solo en el esquema es la línea base en ambas particiones, y cada capítulo posterior informa su cambio respecto a ella.

Este capítulo, en esta edición

Edición 2026.11.15Ejemplos verificados el 19 de nov de 2026Superan la prueba 8 de 8 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 3 de 11: Construye preguntas doradas a partir de tu propio trabajo

  1. Por qué un benchmark público no es tu prueba
  2. Write questions from the work people do
  3. Comparar resultados, no el texto del SQL
  4. Order, rounding and column names
  5. Check the gold before you trust it
  6. Cubrir rechazos y roles, no solo respuestas
  7. Reserva un conjunto de prueba
  8. Qué sale mal en producción
  9. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos