Crie perguntas de referência a partir do seu próprio trabalho
Cerca de 31 minutos min de leitura, com 8 exemplos em 9 seções.
Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros
Traduzido do livro em inglês, edição 2026.11.15. Leia o original
Nesta página
- Por que um benchmark público não é o seu teste
- Write questions from the work people do
- Compare resultados, não o texto do SQL
- Order, rounding and column names
- Check the gold before you trust it
- Cubra recusas e papéis, não apenas respostas
- Reserve uma divisão de teste
- O que dá errado em produção
- Decisões tomadas neste capítulo
Ao final deste capítulo, você será capaz de escrever perguntas de referência a partir das perguntas que as pessoas do seu negócio fazem, cada uma com seu SQL de referência, o papel de quem a faz e o tipo de resposta que ela exige. Você poderá comparar os resultados de um agente com resultados de referência, em vez de comparar o texto do SQL, verificar o próprio gabarito antes de confiar nele, e explicar por que a nota em um benchmark público não é a nota no seu data warehouse.
O capítulo 1 avaliou duas abordagens com cinco perguntas de referência, e cinco perguntas servem apenas como um teste de fumaça. Uma mudança no prompt que corrige ou quebra uma pergunta move a nota em um quinto, e uma mudança que corrige uma e quebra outra não move a nota de forma alguma. Nenhuma delas testa uma recusa diante de uma pergunta ambígua ou de uma pergunta que o papel de quem pergunta talvez não possa ver. Todo capítulo seguinte deste livro altera uma parte do agente e afirma que a alteração ajudou. Essas afirmações precisam de um conjunto grande o bastante para ser medido, com perguntas que cubram as armadilhas do data warehouse, os papéis e as recusas, e com uma parte reservada, na qual nenhuma mudança seja ajustada.
O capítulo 2 acrescentou mais onze, cada uma voltada a uma armadilha. Este capítulo mantém todas as dezesseis e constrói o conjunto até 48 perguntas de referência sobre os pedidos, reembolsos e clientes da loja, cujo data warehouse gerado é consultado pelo agente. Ele começa pelo motivo de escrever as próprias perguntas, já que existem benchmarks públicos e baixá-los custa menos do que escrevê-los.
Por que um benchmark público não é o seu teste
Um benchmark público para agentes de texto para SQL ou de dados oferece perguntas, um banco de dados e uma resposta gold para cada pergunta, além de uma pontuação que outros já relataram sobre o mesmo conjunto. Isso o torna útil para comparar modelos. Ele não diz como um agente se sairá no seu data warehouse, por dois motivos. As perguntas, os dados e as definições do benchmark são de outra pessoa, então uma pontuação alta diz que o modelo lida bem com o trabalho deles. E as respostas gold são afirmações escritas por pessoas, então a pontuação também mede com que frequência o gold está certo.
O segundo motivo já foi medido. Uma auditoria apresentada na CIDR 2026 fez especialistas verificarem cada consulta gold em relação à sua pergunta e ao esquema, executá-la e executar suas subconsultas. Ela encontrou erros de anotação em 52.8% do BIRD Mini-Dev, em sua primeira versão, com 500 perguntas, e em 66.1% dos 121 problemas do Spider 2.0-Snow cujo SQL gold é público, no arquivo spider2-snow-0713 (Jin et al., CIDR 2026). O erro mais comum foi SQL gold que interpretava mal os dados ou o esquema. Quando os autores corrigiram 100 problemas do BIRD Dev e executaram novamente cinco agentes de código aberto, as pontuações variaram de −3% a +31% em termos relativos, e um agente passou do quarto lugar para o primeiro. Os benchmarks também mudam sob seus pés: a equipe do BIRD revisou o Mini-Dev em 26 e 27 de outubro de 2026, corrigindo o SQL de referência e substituindo perguntas, e manteve a versão de 2025 como arquivo (BIRD Mini-Dev). Esses números são as medições do artigo, não nossas. O livro cita BIRD e Spider, mas não os distribui, porque distribui apenas dados sob CC BY 4.0, CC0 ou sua própria licença, e o BIRD está sob CC BY-SA 4.0.
O primeiro motivo aparece em dados que o livro pode distribuir, por isso este capítulo usa uma pequena parte do Data Agent Benchmark for Multi-step Reasoning (DABstep), que tem licença CC BY 4.0. O DABstep faz perguntas sobre as transações de um processador de pagamentos, avalia apenas a resposta final e mantém a maior parte de suas tarefas ocultas para o seu ranking (o artigo). O conjunto de dados tem 450 tarefas, e apenas suas 10 tarefas de desenvolvimento têm respostas públicas (o conjunto de dados). A cópia do livro, em examples/data/dabstep/, contém as três tarefas de desenvolvimento do nível de dificuldade mais baixo do DABstep e a tabela de pagamentos completa, com 138,236 transações, sem quatro colunas de identificação que nenhuma tarefa usa: endereços IP com hash, e-mails dos compradores, números de cartão e o número de identificação bancária de cada cartão. SOURCE.md traz a revisão fixada do conjunto de dados e cada alteração, e LICENSE é o aviso do próprio conjunto de dados. Os comerciantes da tabela de pagamentos são empresas fictícias, e seus nomes vêm do DABstep como publicado. lib/dabstep.py carrega a tabela no DuckDB.
Executamos a abordagem somente com esquema do capítulo 1 nos dois conjuntos com um único modelo, Qwen3-4B-Instruct-2507, reproduzido a partir de uma gravação. O modelo recebe o esquema de uma tabela e uma pergunta, escreve SQL, que é executado. No DABstep, o modelo então lê o resultado da consulta e dá uma resposta final no formato que a tarefa pede. A gravação dabstep-runs armazena essas respostas.
1"""Score schema-only SQL on three public DABstep tasks and on the shop's dev questions, with the same model.2The point about task 49 rests on its "SQL ran: False" line, which the assert checks, and on the two top-country lines3that follow it, which read the same fraud data by two definitions."""4from lib import dabstep5from lib.golden import load_golden, schema_only_outcome6from lib.model import RecordedModel7from lib.warehouse import connect, describe_schema89payments = dabstep.connect()10runs = [dabstep.answer_task(payments, RecordedModel("dabstep-runs"), task) for task in dabstep.load_tasks()] # replays recorded replies11for run in runs:12 print(f"task {run.task.task_id}: answered {run.answer[:40]!r}, expected {run.task.answer!r}, correct: {run.correct}")13 print(f"task {run.task.task_id} SQL ran: {not run.result.startswith('error')}")14print(f"DABstep correct: {sum(run.correct for run in runs)} of {len(runs)}")15task49 = next(run for run in runs if str(run.task.task_id) == "49")16assert task49.result.startswith("error") # a query that fails comes back as text that starts with "error"1718# Task 49 asks for the top country "for fraud". DABstep's manual defines fraud as fraudulent volume over total volume.19by_count, by_volume = payments.execute("""20 SELECT arg_max(ip_country, frauds), arg_max(ip_country, fraud_share) FROM (21 SELECT ip_country, count(*) FILTER (has_fraudulent_dispute) AS frauds,22 sum(eur_amount) FILTER (has_fraudulent_dispute) / sum(eur_amount) AS fraud_share23 FROM payments GROUP BY ip_country)""").fetchall()[0] # one row: the top country by each measure24print(f"task 49 top by count of frauds: {by_count}")25print(f"task 49 top by fraud volume ratio: {by_volume}")2627con = connect()28schema, model = describe_schema(con), RecordedModel("schema-only-sql") # the recorded replies to the schema-only prompt29dev = [q for q in load_golden() if q.split == "dev"]30outcomes = [schema_only_outcome(con, model, schema, q) for q in dev]31print(f"shop dev correct: {outcomes.count('correct')} of {len(dev)}")
python public-vs-own-score.pytask 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
Os dois conjuntos fazem perguntas diferentes, então nenhuma das pontuações prevê a outra, e a diferença não é o ponto. O SQL somente com esquema acerta 1 of 3 tarefas do DABstep, avaliadas por uma versão simplificada da correspondência quase exata do DABstep, e 2 of 24 perguntas de desenvolvimento. As tarefas do DABstep tratam de uma única tabela, sem calendário fiscal, sem pedidos cancelados e sem data mart legado. As perguntas da loja falham justamente nesses pontos.
A tarefa 49 mostra do que depende um gold. Ela pergunta qual é o principal país em termos de fraude, e seu gold é BE. Contado pelo número de transações fraudulentas, o principal país é NL. Medido pela fatia fraudulenta do volume de pagamentos, é BE. O manual do DABstep resolve a questão: fraude é a razão entre o volume fraudulento e o volume total (o manual). A pergunta, sozinha, não resolve. Aqui, o SQL do modelo para a tarefa 49 não foi executado, mas mesmo assim ele citou um país. O gold da tarefa 70 é Not Applicable. Na nossa leitura, o manual descreve taxas relacionadas a fraude, mas nenhuma multa. O modelo respondeu com uma consulta em vez de uma resposta.
Regra prática: Use benchmarks públicos para comparar modelos em uma tarefa comum, e nunca como evidência de que um agente funciona no seu data warehouse. Cite a versão do benchmark em qualquer pontuação que você mencionar, pois os conjuntos gold são corrigidos. Meça o seu próprio agente com perguntas golden escritas a partir do seu trabalho, com as suas definições, e espere que as duas pontuações não coincidam.
Esta parte ainda não foi traduzida, por isso está em inglês.
Write questions from the work people do
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.
1"""Load the shop's golden questions, show what one holds and how the set divides, and compute one gold's other reading.2The 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."""3from collections import Counter45from lib.golden import golden_result, load_golden6from lib.warehouse import connect78con = connect()9questions = load_golden()10print(f"golden questions: {len(questions)}")11for kind, count in sorted(Counter(q.kind for q in questions).items()):12 print(f"{kind}: {count}")13for decline_type, count in sorted(Counter(q.decline_type for q in questions if q.kind == "decline").items()):14 print(f"decline, {decline_type}: {count}")15print(f"roles: {', '.join(sorted({q.role for q in questions}))}")1617q = next(q for q in questions if q.question_id == "gq-018")18print()19print(f"{q.question_id} ({q.split}, {q.kind}, asked by {q.role})")20print(f"question: {q.question}")21print(f"golden SQL: {' '.join(q.golden_sql.split())}")22print(f"traps: {', '.join(q.traps)}")23print(f"note: {q.note}")2425# The other reading: refunds grouped by the month they were made, not the month the order was placed.26by_refund_month = con.execute(27 "SELECT round(sum(amount_eur), 2) FROM analytics.fct_refunds WHERE refund_month = DATE '2026-03-01'").fetchall()28print(f"refunded on orders placed in March 2026: {golden_result(con, q)[0][0]:,.2f}") # gq-018's gold: by the order's month29print(f"refunded in March 2026, by refund month: {by_refund_month[0][0]:,.2f}")
python load-golden-questions.pygolden 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.
Compare resultados, não o texto do SQL
Com as perguntas de referência escritas, a próxima decisão é como saber se a resposta de um agente corresponde à esperada. Comparar o SQL do agente com o SQL de referência falha nos dois sentidos. Duas consultas podem ser escritas de forma diferente e retornar as mesmas linhas, e duas consultas com algumas palavras de diferença podem retornar números diferentes. O que quem pergunta vê é o resultado, então é isso que você deve comparar. Uma correspondência de execução significa que o resultado do agente é igual ao resultado de referência, segundo a regra de comparação da pergunta. Os benchmarks fazem o mesmo: o BIRD reporta acurácia de execução, que compara as linhas que cada consulta retorna (calculate_ex no código de avaliação do BIRD), e o DABstep pontua a resposta final por uma correspondência quase exata (o artigo).
Na loja, gq-001 pede a receita líquida do ano fiscal de 2026. Seu SQL de referência soma net_revenue_eur sobre fct_orders, unido a dim_date para obter o ano fiscal. Sua consulta de verificação, que a seção sobre como verificar a referência usa, soma net_amount_eur sobre fct_order_lines, com um intervalo de datas em seu lugar. Duas consultas mostram onde o texto e os resultados se separam, cada uma comparada com o SQL de referência: a consulta de verificação e o SQL de referência sem o filtro de pedidos cancelados. Para cada uma, a tabela mostra se o texto é igual, se é igual depois que o sqlglot normaliza ambos, e se os resultados correspondem segundo results_match().
1"""Two queries written differently for the same golden question: compare their text, then compare their results.2The point rests on the last two result lines, "results match": the order-lines query matches the golden result, and3the query that forgets cancelled orders does not. The asserts at the end check both."""4import sqlglot5from lib.golden import golden_result, load_golden, results_match6from lib.warehouse import connect78con = connect()9q = next(q for q in load_golden() if q.question_id == "gq-001") # net revenue in fiscal year 202610by_orders, by_lines = q.golden_sql, q.check_sql # orders joined to dim_date; lines by date range11forgets_cancelled = by_orders.replace("o.status <> 'cancelled' AND ", "") # the golden SQL's cancelled-order filter, removed121314def normalized(sql: str) -> str:15 # parses and writes the SQL back in DuckDB's form, so spacing and identifier case don't count as differences16 return sqlglot.parse_one(sql, read="duckdb").sql(dialect="duckdb", normalize=True, pretty=False)171819golden = golden_result(con, q)20for name, sql in [("by lines", by_lines), ("forgets cancelled", forgets_cancelled)]:21 rows = con.execute(sql).fetchall()22 print(f"{name}: {rows[0][0]:,.2f} against golden {golden[0][0]:,.2f}")23 print(f"{name} same text: {sql == by_orders}")24 print(f"{name} same normalized text: {normalized(sql) == normalized(by_orders)}")25 print(f"{name} results match: {results_match(rows, golden)}")26# a change to either result must fail this run, as the prose states both facts27assert results_match(con.execute(by_lines).fetchall(), golden)28assert not results_match(con.execute(forgets_cancelled).fetchall(), golden)
python results-match-rules.pyby 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
A consulta sobre as linhas de pedido lê uma tabela diferente, então seu texto difere do de referência mesmo depois de normalizado. Seu resultado corresponde: ela soma 1,664,762.75 against golden 1,664,763.72, a menos de um euro da referência, já que cada linha é arredondada ao centavo e a tolerância absorve essa diferença. A consulta que esquece os pedidos cancelados retorna 1,755,242.00 against golden 1,664,763.72, e seu resultado não corresponde. No texto, ela está a um predicado da referência. Normalizar não salva uma comparação de texto em nenhuma das direções, porque nenhum parser consegue saber que dois joins diferentes dão a mesma soma nestes dados.
Uma correspondência de execução tem um ponto cego próprio. Uma consulta pode retornar o número certo pelo motivo errado nos dados de hoje, como um filtro que, por acaso, não remove nenhuma linha. A defesa é verificar mais perguntas e ler o SQL por trás de correspondências surpreendentes. Essa é uma das razões pelas quais o conjunto tem 48 perguntas, e não 5.
Regra prática: Avalie um agente comparando o resultado dele com o resultado de referência, nunca comparando o texto do SQL, normalizado ou não. Use uma única função de comparação para toda pontuação que você reportar, de modo que uma mudança na pontuação seja uma mudança no agente. Quando uma correspondência surpreender você, leia o SQL do agente, porque um resultado pode corresponder por coincidência.
Esta parte ainda não foi traduzida, por isso está em inglês.
Order, rounding and column names
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.
1"""Change the golden result for net revenue by region in March 2026 in the ways real answers differ, and compare.2Then move a ratio gold, gq-033's conversion rates, by a near miss. The prose's claims about thousands and about the3near miss rest on the lines that print True or False, and the asserts check them."""4from lib.golden import golden_result, load_golden, results_match5from lib.warehouse import connect67con = connect()8q = next(q for q in load_golden() if q.question_id == "gq-002")9golden = sorted((region, float(revenue)) for region, revenue in golden_result(con, q)) # sorted by region, so the variants line up10print(f"golden: {golden}")11print(f"tolerance: {q.tolerance:.2%} relative")12print(f"absolute slack: {q.absolute}")1314variants = {15 "rows reversed": golden[::-1],16 "columns swapped": [(revenue, region) for region, revenue in golden],17 "extra month column": [(region, "2026-03", revenue) for region, revenue in golden],18 "rounded to whole euros": [(region, round(revenue)) for region, revenue in golden],19 "rounded to thousands": [(region, round(revenue, -3)) for region, revenue in golden], # round(x, -3) rounds to the nearest thousand20 "in thousands of euros": [(region, revenue / 1000) for region, revenue in golden], # same numbers, unit changed to thousands21 "one region missing": golden[:-1], # drops the last region22}23for name, rows in variants.items():24 print(f"{name}: {results_match(rows, golden, q.order_matters, q.tolerance)}")25# reporting in thousands of euros must fail: a change of unit the agent doesn't state is a real error26assert not results_match(variants["in thousands of euros"], golden, q.order_matters, q.tolerance)2728ranked = sorted(golden, key=lambda row: -row[1]) # highest revenue first, so the reversed list is the wrong order29print(f"ranking reversed, order matters: {results_match(ranked[::-1], ranked, order_matters=True)}")3031# A ratio: gq-033's conversion rates, rounded to four places, with its absolute slack of half that last place.32rates_q = next(q for q in load_golden() if q.question_id == "gq-033")33rates = [(channel, float(rate)) for channel, rate in golden_result(con, rates_q)]34near_miss = [(channel, rate + 0.004) for channel, rate in rates] # 0.004 is about 3% of each rate35print(f"gq-033 rates: {min(r for _, r in rates):.4f} to {max(r for _, r in rates):.4f}")36print(f"gq-033 absolute slack: {rates_q.absolute:.5f}")37print(f"rates 0.004 higher, gq-033's rule: "38 f"{results_match(near_miss, rates, rates_q.order_matters, rates_q.tolerance, rates_q.absolute)}")39print(f"rates 0.004 higher, half a cent of slack: {results_match(near_miss, rates, rates_q.order_matters, rates_q.tolerance)}")40# under the question's own slack the near miss is a miss; with half a cent of slack the same near miss matches41assert not results_match(near_miss, rates, rates_q.order_matters, rates_q.tolerance, rates_q.absolute)42assert results_match(near_miss, rates, rates_q.order_matters, rates_q.tolerance)
python tolerant-comparison.pygolden: [('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 ainda não foi traduzida, por isso está em inglês.
Check the gold before you trust it
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.
1"""Check the gold before trusting it: every golden SQL runs and returns rows, and each check query agrees with it.2The prose's gold claims rest on the counts of runs, empty results and agreeing checks, and its refund point on the last two readings."""3import duckdb4from lib.golden import golden_result, load_golden, results_match5from lib.warehouse import connect67con = connect()8answerable = [q for q in load_golden() if q.kind == "answer"]9results, failed = {}, []10for q in answerable:11 try:12 results[q.question_id] = golden_result(con, q)13 except duckdb.Error:14 failed.append(q.question_id)15empty = [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, too16print(f"golden SQL that runs: {len(results)} of {len(answerable)}")17print(f"golden SQL that fails: {', '.join(failed) or 'none'}")18print(f"empty or NULL results: {len(empty)}")1920checked = [q for q in answerable if q.check_sql and q.question_id in results]21agree = [q for q in checked if results_match(con.execute(q.check_sql).fetchall(), results[q.question_id],22 q.order_matters, q.tolerance, q.absolute)]23print(f"questions with a check query: {len(checked)}")24print(f"checks that agree: {len(agree)} of {len(checked)}")2526# One question, two readings: "top country for refunds" by number of refunds, and by refund rate (gq-028's definition).27# orders join to their local business day; the LEFT JOIN keeps orders that have no refund, so they still count28by_count, by_rate = con.execute("""29 SELECT arg_max(country, refunds), arg_max(country, refunded / gross) FROM (30 SELECT o.country, count(r.refund_id) AS refunds, sum(r.amount_eur) AS refunded,31 sum(o.gross_revenue_eur) AS gross32 FROM analytics.fct_orders AS o33 JOIN analytics.dim_date AS d ON d.date_day = o.order_date_local34 LEFT JOIN analytics.fct_refunds AS r USING (order_id)35 WHERE o.status <> 'cancelled' AND d.fiscal_year = 202636 GROUP BY o.country)""").fetchall()[0] # one row: arg_max returns the country at the largest value37print(f"top country by number of refunds: {by_count}")38print(f"top country by refund rate: {by_rate}")39print(f"gq-028 golden: {results['gq-028'][0][0]}")
python gold-runs-and-agrees.pygolden 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.
1"""Read a wrong answer: gq-031 once asked about "items", which allows units or order lines. It now asks for units.2The two `outcome` lines settle whether each wording's baseline answer is right against the gold printed first."""3from dataclasses import replace45from lib.golden import golden_result, load_golden, schema_only_outcome6from lib.model import RecordedModel7from lib.prompts import schema_only_messages8from lib.tools import extract_sql9from lib.warehouse import connect, describe_schema1011con = connect()12schema, model = describe_schema(con), RecordedModel("schema-only-sql")13q = next(q for q in load_golden() if q.question_id == "gq-031")14print(f"gq-031 golden: {golden_result(con, q)[0][0]}")15for 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 text16 ("units", q)]:17 sql = extract_sql(model.complete(schema_only_messages(schema, asked.question)))18 print(f"{wording} wording: {asked.question}")19 print(f"baseline answer, {wording} wording: {con.execute(sql).fetchall()[0][0]:.4f}")20 print(f"baseline outcome, {wording} wording: {schema_only_outcome(con, model, schema, asked)}")
python reworded-golden-question.pygq-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.
Cubra recusas e papéis, não apenas respostas
Um gabarito verificado torna cada pergunta confiável, mas o conjunto como um todo ainda precisa testar aquilo que o agente vai encontrar. Um conjunto formado apenas por perguntas respondíveis recompensa um agente que responde a tudo: ele nunca perde pontos por chutar. Por isso, o conjunto da loja inclui perguntas cuja resposta certa é uma recusa, de dois tipos, porque o comportamento correto é diferente. Uma pergunta ambígua, como "Quem são nossos melhores clientes?", tem várias respostas razoáveis, e o agente deve dizer de quais escolhas ele precisa. Uma pergunta sem resposta possível, como o custo do frete, pede dados que o armazém de dados não possui, e o agente deve informar isso. Uma pergunta proibida é respondível, mas não para o papel que a faz: a equipe financeira da loja não pode ver os e-mails dos clientes, e um líder regional pode ver apenas a própria região. O capítulo 8 trata de construir a recusa e o capítulo 9, de construir as regras de acesso. Este capítulo garante que o conjunto consiga pontuar ambos.
Cobertura também significa as armadilhas do armazém de dados e os papéis da loja. Cada armadilha construída no armazém da loja, desde pedidos de teste até o data mart legado, deve aparecer nas duas divisões, para que uma mudança que quebre uma armadilha apareça em qualquer uma das pontuações. Contar tipos, papéis e armadilhas por divisão mostra onde o conjunto está fraco.
1"""Count what the golden set covers in each split: kinds, roles and the warehouse's traps.2The prose's coverage point rests on the kind counts and on the last line, which names any trap missing from a split."""3from collections import Counter45from lib.golden import load_golden67questions = load_golden()8splits = ("dev", "test")9for split in splits:10 print(f"{split} questions: {sum(q.split == split for q in questions)}")11print("split answer decline forbidden")12for split in splits:13 kinds = Counter(q.kind for q in questions if q.split == split)14 print(f"{split:<5} {kinds['answer']:>6} {kinds['decline']:>7} {kinds['forbidden']:>9}")1516for split in splits:17 roles = Counter(q.role for q in questions if q.split == split and q.kind == "answer")18 print(f"{split} answers by role: {dict(sorted(roles.items()))}")1920traps = {split: Counter(t for q in questions if q.split == split for t in q.traps) for split in splits}21print("trap dev test")22for trap in sorted(traps["dev"] | traps["test"]):23 print(f"{trap:<20} {traps['dev'][trap]:>3} {traps['test'][trap]:>4}")24missing = 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 trap25print(f"traps missing from a split: {', '.join(missing) or 'none'}")
python golden-coverage.pydev 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
Os tipos são equilibrados: cada divisão tem o mesmo número de respostas, recusas e perguntas proibidas. Toda armadilha aparece nas duas divisões, e a última linha informa traps missing from a split: none. Várias armadilhas dependem de uma única pergunta em uma divisão, como o IVA na divisão de teste, de modo que uma única etiqueta ausente tiraria uma armadilha de uma divisão, e esta linha apontaria qual delas.
Os papéis não são equilibrados. As perguntas respondíveis da divisão de desenvolvimento são feitas pelo analista, pela equipe financeira e por um líder regional. Marketing e suporte fazem perguntas respondíveis apenas na divisão de teste. Como os prompts e o contexto são ajustados com base na divisão de desenvolvimento, nenhum ajuste verá uma pergunta de marketing que o agente deveria responder, e a primeira vez que ela é pontuada é no conjunto reservado. Mantemos o desequilíbrio visível em vez de mover perguntas entre divisões depois de ver as pontuações; as próximas perguntas escritas para esses dois papéis irão para a divisão de desenvolvimento.
Regra prática: Inclua recusas e perguntas proibidas desde o início, e divida as recusas em ambíguas e sem resposta possível, porque a resposta certa é diferente. Marque cada pergunta com as armadilhas que ela testa, e conte tipos, papéis e armadilhas por divisão antes de pontuar qualquer coisa. Corrija uma lacuna escrevendo novas perguntas, não movendo perguntas existentes entre divisões depois de ver como o agente se saiu com elas.
Reserve uma divisão de teste
Um conjunto que cobre as coisas certas ainda pode induzir ao erro, pela forma como é usado. Cada vez que você muda um prompt porque uma pergunta falhou, ajusta o agente um pouco mais de perto a essas perguntas. Depois de muitas mudanças, a pontuação nelas mede o quão bem você ajustou, e não o quão bem o agente funciona. A defesa usual é uma divisão reservada: ajuste em uma parte e pontue a outra somente quando for reportar um resultado. O conjunto de teste oculto de um benchmark reduz o risco de que suas respostas vazem para o treinamento (o artigo do DABstep), mas não impede que as pessoas ajustem ao estilo de suas perguntas. Sua própria divisão reservada precisa ser protegida pela forma como você trabalha.
O conjunto da loja tem 24 dev perguntas, que todo capítulo pode usar para ajuste, e 24 test perguntas, que um capítulo pontua apenas pelo número que reporta. Pontuar a linha de base somente com o esquema do capítulo 1 nas duas divisões fornece a referência que todo capítulo posterior precisa superar.
1"""The baseline every later chapter must beat: schema-only SQL scored on the dev split and on the held-out test split.2The prose's split counts are the per-split lines, and its declines, forbidden and answer counts the last three lines."""3from collections import Counter45from lib.golden import load_golden, schema_only_outcome6from lib.model import RecordedModel7from lib.warehouse import connect, describe_schema89con = connect()10schema, model = describe_schema(con), RecordedModel("schema-only-sql")11outcomes = {"dev": Counter(), "test": Counter()}12by_kind = Counter()13for q in load_golden():14 outcome = schema_only_outcome(con, model, schema, q)15 outcomes[q.split][outcome] += 116 by_kind[q.kind, outcome == "correct"] += 1 # (kind, correct) pairs, counted over both splits1718for split, counts in outcomes.items():19 total = sum(counts.values())20 for outcome in ("correct", "wrong", "error", "declined"): # "error" when the SQL fails; grade() gives the rest21 print(f"{split} {outcome}: {counts[outcome]} of {total}")22 print(f"{split} accuracy: {counts['correct'] / total:.1%}")23for kind in ("answer", "decline", "forbidden"):24 print(f"{kind} correct, both splits: {by_kind[kind, True]} of {by_kind[kind, True] + by_kind[kind, False]}")
python baseline-on-both-splits.pydev 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
A linha de base é mais fraca onde é preciso julgamento. Somando as duas divisões, ela acerta 0 of 8 recusas, 0 of 6 perguntas proibidas e 5 of 34 perguntas respondíveis. Ela não recusa nada, já que apenas escreve SQL.
Ela acerta 2 of 24 perguntas de dev, com acurácia de 8.3%, e 3 of 24 perguntas de teste, com acurácia de 12.5%. Todas as outras perguntas falham: a consulta não roda, dá um resultado errado ou responde o que deveria ser recusado.
As divisões diferem em uma pergunta, e nada foi ajustado em nenhuma delas ainda. Espere que se afastem uma da outra quando os capítulos começarem a alterar o contexto na divisão de dev. Uma pontuação de dev que sobe enquanto a de teste não sobe é o sinal de que as mudanças se ajustam às perguntas de dev, e não à loja. Com 24 perguntas por divisão, uma pergunta equivale a cerca de quatro pontos de acurácia; trate, portanto, uma diferença de uma ou duas perguntas como ruído, e compare as mesmas perguntas antes e depois de uma mudança, em vez de dois totais.
Regra prática: Divida suas perguntas golden uma única vez, antes de ajustar qualquer coisa, e ajuste somente com a divisão de dev. Pontue a divisão de teste apenas quando for reportar um resultado, e reporte as duas divisões lado a lado. Quando as perguntas de teste tiverem sido observadas tantas vezes que as pessoas passem a ajustar a elas, escreva novas perguntas de teste e transfira as antigas para a divisão de dev.
O que dá errado em produção
As 48 perguntas douradas da loja medem o agente deste livro. A mesma prática em um data warehouse real falha das seguintes maneiras, e cada uma tem uma forma de ser percebida.
O padrão-ouro envelhece quando uma definição muda. Se a área financeira mudar a definição de receita líquida, toda consulta dourada que soma net_revenue_eur pode ficar errada sem falhar. Mantenha as perguntas douradas no repositório junto com as definições e métricas, revise as mudanças em conjunto e execute novamente as consultas de verificação a cada mudança. Uma consulta de verificação que deixa de concordar é o alarme.
Os resultados dourados mudam conforme os dados chegam. Reembolsos continuam chegando por meses após um pedido, então os reembolsos de gq-018 sobre pedidos de março de 2026 aumentam a cada carga da tabela de reembolsos. Perguntas douradas sobre períodos abertos geram um resultado dourado diferente a cada semana, e uma comparação que armazenou o resultado da semana passada falha sem motivo. Calcule os resultados dourados a partir do SQL dourado no momento da avaliação, como faz golden_result(), e prefira períodos fechados nas perguntas em que o número precisa permanecer o mesmo.
O conjunto deixa de se parecer com as perguntas que as pessoas fazem. As perguntas mudam com o negócio: um novo canal, uma nova região, uma nova política fiscal. Um conjunto escrito uma única vez se afasta delas. Amostre perguntas a partir do que as pessoas perguntam ao agente, escreva perguntas douradas para aquelas que ele errou ou recusou, e adicione-as ao conjunto de desenvolvimento.
O conjunto de teste vaza. Alguém lê as perguntas de teste que falharam e ajusta o prompt para elas, e a pontuação no teste sobe sem que nada mais melhore. Você percebe quando as pontuações de desenvolvimento e de teste se movem juntas após uma mudança voltada a uma única pergunta. Mantenha as perguntas de teste fora das discussões de ajuste e renove-as quando tiverem vazado.
Uma pontuação de benchmark muda com o benchmark. A acurácia de um fornecedor no BIRD ou no Spider descreve uma versão de um conjunto que seus mantenedores corrigem. Ao comparar modelos, registre a versão do benchmark junto de cada pontuação e recalcule a pontuação no seu próprio conjunto antes de trocar.
A comparação esconde uma mudança de unidades. Um agente que passa a devolver receita em milhares de euros falha em todas as perguntas sobre dinheiro de uma vez, e uma tolerância mais frouxa esconderia isso. Mantenha a tolerância pequena e relativa, e quando muitas perguntas falharem juntas, leia uma resposta antes de mexer na regra.
Regra prática: Trate o conjunto dourado como código: mantenha-o junto às definições, execute suas verificações em CI, calcule os resultados dourados no momento da avaliação, adicione perguntas de tráfego real ao conjunto de desenvolvimento e proteja o conjunto de teste. Quando uma pontuação mudar, leia as respostas que mudaram antes de alterar o conjunto ou a comparação.
Decisões tomadas neste capítulo
- O conjunto principal de avaliação é o próprio da loja: perguntas de referência (golden) escritas a partir do trabalho que as equipes da loja realizam, com papéis, tipos e definições, em
examples/data/golden/questions.toml. - Benchmarks públicos são citados, não usados para pontuação. BIRD e Spider 2.0 aparecem apenas como citações. Um subconjunto de três tarefas do DABstep, sob CC BY 4.0 e fixado por revisão, mostra que uma pontuação pública e uma pontuação no seu data warehouse não coincidem.
- Os dados do DABstep seguem a sua licença. O subconjunto mantém o
LICENSEdo próprio conjunto de dados, remove quatro colunas de identificadores, mantém todas as linhas e os nomes fictícios dos lojistas, eSOURCE.mdregistra cada alteração. - Os resultados são comparados, não o texto do SQL, com uma única função,
results_match(), para cada pontuação: qualquer ordem de linhas, a menos que a pergunta peça uma; nomes e ordem das colunas ignorados; colunas extras permitidas; números dentro de uma pequena tolerância relativa, mais meia unidade na última casa decimal arredondada do gabarito. - Todo gabarito é verificado antes de pontuar: ele executa, retorna linhas sem NULLs e concorda com uma consulta independente, quando existe uma. Sua nota nomeia a definição.
- Recusas e perguntas proibidas fazem parte do conjunto: as recusas se dividem em ambíguas e não respondíveis, e as perguntas proibidas abrangem os papéis da loja.
- O conjunto é dividido uma única vez em metades de desenvolvimento (dev) e teste de tamanho igual, com os tipos balanceados. Os capítulos fazem ajustes no dev e pontuam no teste apenas para os números que reportam.
- SQL apenas com o esquema é a linha de base nas duas metades, e cada capítulo posterior informa a sua variação em relação a ela.
Este capítulo, nesta edição
Edição 2026.11.15Exemplos aprovados em 19 de nov de 20268 de 8 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.15.