Let the agent write SQL inside guards
Cerca de 45 minutos min de leitura, com 11 exemplos em 12 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
- Dê ao agente um banco de dados com apenas o que ele pode ler
- Give each role a database of views
- Analise o SQL antes de executá-lo
- Permita apenas consultas somente leitura em tabelas conhecidas
- Bound the rows and the cost
- Enforce the deadline by killing a process
- Reproduzir os ataques contra o guarda
- Reparar uma vez, a partir do erro
- Transpile para o dialeto do warehouse
- Quando preferir uma nova métrica ao SQL
- O que dá errado em produção
- Decisões tomadas neste capítulo
Esta parte ainda não foi traduzida, por isso está em inglês.
By the end of this chapter, you can handle the questions no metric covers by letting the agent write SQL that runs read-only on a database holding only the rows and columns its role may read, and that is parsed, checked against an allowlist of tables, bounded in rows, size, cost and time, repaired once from an error, and transpiled to your warehouse's dialect. You can also tell from the golden questions when such a question should become a metric instead.
Chapter 6 sent the questions of the shop, which sells outdoor and camping gear across three regions, to governed metrics first, and its semantic layer holds ten metrics that cover the monthly finance questions. The questions no metric covers are the long tail: how much revenue came from orders that included a tent, or what share of sessions converted. Chapter 6's agent declines those, which is honest and frustrating. Ten of the shop's golden questions are in the long tail, listed in the section on promoting them.
For the long tail, the agent has to write SQL. Chapter 4 already had it do so, and ran the SQL as written on a connection that can't write. This chapter puts guards around it. DuckDB's own documentation says to "Treat SQL in DuckDB like code in Bash or Python. Do not execute SQL from untrusted sources without proper sandboxing" (DuckDB). A model's SQL is SQL from an untrusted source in that sense, whoever typed the question.
So the security boundary is the database: the agent connects read-only, to a database that holds only views limiting the rows and columns its role may see. The parser's checks in lib/sql_guard.py, the timer and the cost check are a teaching layer and defence in depth. They catch mistakes, give the model refusals to repair from, and bound cost and time, but they don't keep data from a role. Drafts of the parser were bypassed, as the replay section shows, and any parser can be.
Dê ao agente um banco de dados com apenas o que ele pode ler
O privilégio mínimo significa que o SQL do agente roda em uma conexão que alcança apenas o que o agente pode consultar, e nada além disso. Ele vem antes de qualquer verificação sobre o SQL, porque uma verificação é um juízo sobre texto, e quando esse juízo está errado, é o banco de dados que decide o que a consulta alcança.
O warehouse.connect() do Capítulo 1 é somente leitura, mas enxerga tudo: o schema raw, o data mart legado e as views semânticas. Por isso, agent_warehouse() em lib/warehouse.py copia para um segundo arquivo de banco de dados os sete data marts que o agente pode ler, nomeados um a um em AGENT_TABLES, e o abre em modo somente leitura. O acesso a arquivos e as extensões ficam desligados, a memória é limitada a 1 GB e cada consulta a dois threads, e as configurações ficam travadas, de modo que uma consulta não consiga reativar nada disso. Uma configuração só vale o que valem as tentativas que a testam; por isso o exemplo envia seis tentativas diretamente ao banco de dados do agente, sem nenhum filtro na frente, e em seguida lê o catálogo do DuckDB.
1"""The agent's own database holds copies of the seven allowed marts, opened read-only with files, extensions and settings2locked. The attempts show what those locks refuse, and the catalog lines show what they can't hide."""3import duckdb45from lib.warehouse import agent_warehouse, connect67shop = connect()8agent = agent_warehouse(shop) # a second file: the seven allowed marts, copied, and nothing else9(shop_tables,), = shop.execute("SELECT count(*) FROM duckdb_tables()").fetchall()10print("tables in the shop's warehouse:", shop_tables)11tables = agent.execute("SELECT schema_name || '.' || table_name FROM duckdb_tables() ORDER BY 1").fetchall()12print("tables in the agent's database:", len(tables))13print("the agent's tables:", ", ".join(name for (name,) in tables))1415(source,), = shop.execute("SELECT path FROM duckdb_databases() WHERE database_name = 'shop'").fetchall()16ATTEMPTS = { # sent straight to the agent's database, with no guard in front17 "raw table": "SELECT count(*) FROM raw.customers",18 "legacy mart": "SELECT sum(revenue) FROM analytics.orders_legacy",19 "attach the shop's file": f"ATTACH '{source}' AS shop (READ_ONLY)",20 "read a file": "SELECT * FROM read_csv('data/golden/questions.toml')",21 "load an extension": "LOAD httpfs",22 "turn file access back on": "SET enable_external_access = true",23}24for label, sql in ATTEMPTS.items():25 try:26 agent.execute(sql).fetchall()27 print(f"{label}: allowed")28 except duckdb.Error as e:29 kind, message = str(e).splitlines()[0].split(": ", 1) # the error's kind, then its message30 print(f"{label}: {kind}, {message.split(' - ')[-1]}") # the file's path is left out of the output3132# What no setting hides: DuckDB's own catalog, which every database has.33(listed,), = agent.execute("SELECT count(*) FROM information_schema.tables WHERE table_schema = 'analytics'").fetchall()34print("catalog, tables it lists:", listed)35(settings,), = agent.execute("SELECT count(*) FROM duckdb_settings()").fetchall()36print("catalog, settings it lists:", settings)37(paths,), = agent.execute("SELECT count(*) FROM duckdb_databases() WHERE path IS NOT NULL").fetchall()38print("catalog, database files it names:", paths)
python agent-warehouse.pytables in the shop's warehouse: 16
tables in the agent's database: 7
the agent's tables: analytics.dim_customers, analytics.dim_date, analytics.dim_products, analytics.fct_order_lines, analytics.fct_orders, analytics.fct_refunds, analytics.fct_sessions
raw table: Catalog Error, Table with name "raw.customers" does not exist because schema "raw" does not exist.
legacy mart: Catalog Error, Table with name orders_legacy does not exist!
attach the shop's file: Permission Error, file system operations are disabled by configuration
read a file: Permission Error, file system operations are disabled by configuration
load an extension: Permission Error, Loading external extensions is disabled through configuration
turn file access back on: Invalid Input Error, the configuration has been locked
catalog, tables it lists: 7
catalog, settings it lists: 170
catalog, database files it names: 1
O warehouse da loja tem 16 tabelas, e o banco de dados do agente mantém 7 delas. Uma consulta sobre raw.customers obtém Catalog Error, Table with name "raw.customers" does not exist because schema "raw" does not exist.. Nada a recusou, porque o schema não está lá, e o data mart legado também não. Anexar o arquivo da loja, ler qualquer outro arquivo e carregar uma extensão falham. Um SET que reativaria o acesso a arquivos também falha, porque a configuração está travada. A documentação do DuckDB chama essas configurações de "defesa em profundidade" e acrescenta que elas "não substituem um isolamento (sandboxing) adequado" (DuckDB).
O que nenhuma configuração esconde é o catálogo do DuckDB, como information_schema e duckdb_settings(), que descreve o próprio banco de dados. No banco de dados do agente, o catálogo lista 7 tabelas, todas elas tabelas que o agente pode ler, e 170 configurações, e nomeia 1 arquivo de banco de dados com seu caminho no disco. O banco de dados não consegue recusar essas leituras, então a seção sobre a lista de permissões as recusa no analisador.
Regra prática: Execute o SQL do agente em uma conexão que alcance apenas o que o agente pode consultar: um papel com somente essas permissões ou, no DuckDB, um arquivo de banco de dados somente leitura que contenha apenas as tabelas permitidas, com o acesso a arquivos e o carregamento de extensões desligados e as configurações travadas. Nomeie as tabelas permitidas uma a uma. Em seguida, liste o que o banco de dados não consegue esconder, como o seu catálogo, e recuse essas leituras na barreira de proteção.
Esta parte ainda não foi traduzida, por isso está em inglês.
Give each role a database of views
The agent's database leaves out whole tables, but the shop's people don't all see the same rows and columns of the rest. Five roles ask the agent questions, written down in examples/data/shop/roles.toml, which chapter 9 explains. EMEA's regional lead sees EMEA's rows only, finance sees customers with names and emails masked, and support sees orders without revenue. A role's view of a table returns the rows that role may see, with a masked column holding a constant and a denied column left out. The view, not the parser, should decide what the role reads.
Real warehouses do this with grants. PostgreSQL's documentation shows a view that hides a column, granted to a role that can't read the table beneath it, and warns that such a view can't reliably conceal rows unless its security_barrier flag is set (PostgreSQL). Snowflake's secure views exist to limit access to sensitive data (Snowflake). Its row access policies and masking policies attach the same rules to the table itself, so the mask applies wherever the column appears (Snowflake). So in production, the agent's warehouse user has a read-only role with SELECT on the role's secure views and nothing else.
DuckDB has no roles or GRANT, and a view can be read only by a connection that can read the tables under it. So agent_warehouse(con, policy=...) builds each role its own database: every table in it is the role's view of a mart, written out as a table of the same name, and opened read-only with the same locked settings. The views come from chapter 9's Policy.subquery(), so each rule is written once. The example sends three queries the guard accepts, since it knows tables and columns but not roles, straight to each role's database, then replays a catalog bypass that a draft of the guard let through.
1"""A role's database, not the guard, decides what the role reads: queries the guard accepts return less from each role's2database than from every mart, and the catalog bypass lists no net_revenue_eur for support. The assert after the bypass's3tables-listed line settles that none of support's tables has the net_revenue_eur column the sum needs."""4import duckdb56from lib.guard_attacks import ATTEMPTS7from lib.policies import policy_for8from lib.sql_guard import SqlGuard9from lib.warehouse import agent_warehouse, connect1011shop = connect()12marts = agent_warehouse(shop) # every allowed mart, whole: no role's limits13guard = SqlGuard(marts) # chapter 7's guard knows tables and columns, not roles14roles = {"EMEA's regional lead": policy_for("regional_lead", "EMEA"), "finance": policy_for("finance"),15 "support": policy_for("support")}16QUERIES = {"EMEA's regional lead": "SELECT count(DISTINCT region) AS regions FROM analytics.fct_orders",17 "finance": "SELECT count(*) AS n FROM analytics.dim_customers WHERE email LIKE 'customer-0004%'",18 "support": "SELECT sum(net_revenue_eur) AS revenue FROM analytics.fct_orders"}192021def first_value(con, sql):22 try:23 return con.execute(sql).fetchall()[0][0] # the first column of the first row24 except duckdb.Error as e:25 return str(e).splitlines()[0]262728for role, sql in QUERIES.items():29 database = agent_warehouse(shop, policy=roles[role]) # the role's database: its views of the marts only30 guard.check(sql) # raises if the guard refuses; it doesn't31 print(f"{role}, guard accepts: yes")32 print(f"{role}, every mart: {first_value(marts, sql)}")33 print(f"{role}, role's database: {first_value(database, sql)}")3435# A parser bypass a draft of the guard let through: a CTE named like DuckDB's catalog, which lists every table's SQL.36support = agent_warehouse(shop, policy=roles["support"])37# the bypass's rows as text: each table's CREATE statement, as DuckDB's catalog shows it38listed = " ".join(str(row) for row in support.execute(ATTEMPTS["CTE named duckdb_tables"]).fetchall())39print(f"support, catalog bypass, tables listed: {listed.count('CREATE TABLE')}")40assert "net_revenue_eur" not in listed # the catalog lists no net_revenue_eur for support, which its sum needs41print(f"support, catalog bypass, names a revenue column: {'net_revenue_eur' in listed}")42print(f"support, a write: {first_value(support, 'DELETE FROM analytics.fct_orders')}")
python role-database.pyEMEA's regional lead, guard accepts: yes
EMEA's regional lead, every mart: 3
EMEA's regional lead, role's database: 1
finance, guard accepts: yes
finance, every mart: 10
finance, role's database: 0
support, guard accepts: yes
support, every mart: 4019333.37
support, role's database: Binder Error: Referenced column "net_revenue_eur" not found in FROM clause!
support, catalog bypass, tables listed: 6
support, catalog bypass, names a revenue column: False
support, a write: Invalid Input Error: Cannot execute statement of type "DELETE" on database "agent" which is attached in read-only mode!
Each query passed the guard, and each got only what the role's views hold. Counting regions in the orders table gives 3 on every mart and 1 on the lead's database. Finance's search for emails that start customer-0004 matches 10 customers on every mart and 0 on finance's, because every email in finance's database is (masked).
Support's sum of net revenue fails with Binder Error: Referenced column "net_revenue_eur" not found in FROM clause!, because the column isn't there. The bypass, a CTE named like DuckDB's catalog, lists 6 tables in support's database, and none of them names net_revenue_eur, the column the sum needs, which the example asserts. A write fails as read-only.
Working rule: Make the database the boundary: connect the agent read-only, as a role that can read only views limiting the rows and columns that role may see, through secure views, row access policies and masking policies where the warehouse has them. In DuckDB, give each role its own read-only database of those views. Generate the views from the same policy the rest of your stack uses, and test them with queries the parser accepts.
Analise o SQL antes de executá-lo
Uma guarda só consegue verificar o que consegue ver, e o SQL como texto quase nada mostra: uma verificação da palavra DELETE deixa passar um comentário, um nome entre aspas e uma dúzia de formas de escrever a mesma instrução. A análise transforma o texto em uma árvore, com um nó para cada instrução, tabela, coluna e função, de modo que cada verificação posterior pergunta sobre nós, e não sobre caracteres. O sqlglot, na versão 30.31.0, analisa SQL no dialeto do DuckDB e em muitos outros, e a mesma árvore depois volta a se tornar SQL. O README dele é claro sobre o que a análise não faz: "O SQLGlot é um transpilador, não um validador. Uma consulta que é analisada com sucesso ainda pode falhar no momento da execução" (sqlglot). Por isso, a guarda analisa primeiro e depois verifica a árvore contra o warehouse em que ela será executada.
Para gq-017, a receita líquida em cada um dos países da loja em 2025, a gravação do capítulo 4 com as quatro camadas de contexto contém uma resposta que agrupa por uma coluna de país da tabela de calendário. Para ver o que a guarda faz com ela, o exemplo analisa essa resposta, lista a árvore e executa sobre ela a check() da guarda, depois analisa uma única string com duas instruções e uma consulta com erro, para mostrar onde a análise para.
1"""Parse the SQL the model wrote for gq-017 before it runs: its tree, the tables it reads, a column the guard refuses, and2two inputs that don't parse as one query. The prose's examples of each come from these printed lines."""3import duckdb4import sqlglot5from sqlglot import exp6from sqlglot.errors import ParseError78from lib.context import LAYERS, build_context9from lib.golden import load_golden10from lib.model import RecordedModel11from lib.prompts import layered_sql_messages12from lib.sql_guard import GuardError, allowed_schema, check13from lib.tools import extract_sql14from lib.warehouse import agent_warehouse, connect1516con = connect()17question = next(q for q in load_golden() if q.question_id == "gq-017")18context = build_context(con, question.question, LAYERS) # chapter 4's context, every layer19sql = extract_sql(RecordedModel("context-layers").complete(layered_sql_messages(context.text, question.question)))20print(f"question: {question.question}\n{sql}")2122tree = sqlglot.parse_one(sql, read="duckdb")23print("root:", type(tree).__name__)24print("tables read:", ", ".join(f"{t.db}.{t.name} AS {t.alias}" for t in tree.find_all(exp.Table)))25print("columns named:", ", ".join(sorted({f"{c.table}.{c.name}" for c in tree.find_all(exp.Column) if c.table})))2627try:28 check(sql, allowed_schema(agent_warehouse(con))) # the allowlist: the agent's database's tables29except GuardError as e:30 print("guard refuses:", e.kind)31 # the refusal, then the columns of each table it reads, after a fixed phrase32 message, columns = str(e).split(". The tables it reads have only these columns: ")33 print("guard message:", message)34 print("message then lists the columns of:", ", ".join(part.split(" has ")[0] for part in columns.split("; ")))35try:36 con.execute(sql)37except duckdb.Error as e:38 print("DuckDB, had it run:", str(e).splitlines()[0])3940statements = sqlglot.parse("SELECT 1; DROP TABLE analytics.fct_orders", read="duckdb")41print("statements in one string:", ", ".join(type(s).__name__ for s in statements))42try:43 sqlglot.parse_one("SELECT region, sum(net_revenue_eur FROM analytics.fct_orders GROUP BY region", read="duckdb")44except ParseError as e:45 error = e.errors[0] # the parser's first problem; line and col count from 146 print("parse error fields:", ", ".join(sorted(error)))47 print(f"parse error: {error['description']}\nparse error line: {error['line']}\nparse error column: {error['col']}")
python parse-agent-sql.pyquestion: What was net revenue in each of our countries in 2025?
SELECT d.country, round(sum(o.net_revenue_eur), 2) AS net_revenue
FROM analytics.fct_orders AS o
JOIN analytics.dim_date AS d ON d.date_day = o.order_date_local
WHERE o.status <> 'cancelled'
AND d.calendar_year = 2025
GROUP BY d.country
ORDER BY net_revenue DESC
root: Select
tables read: analytics.fct_orders AS o, analytics.dim_date AS d
columns named: d.calendar_year, d.country, d.date_day, o.net_revenue_eur, o.order_date_local, o.status
guard refuses: column
guard message: Unknown column: country
message then lists the columns of: analytics.fct_orders, analytics.dim_date
DuckDB, had it run: Binder Error: Table "d" does not have a column named "country"
statements in one string: Select, Drop
parse error fields: col, description, end_context, highlight, into_expression, line, start_context
parse error: Expecting )
parse error line: 1
parse error column: 39
A raiz da árvore é um Select, e ela diz analytics.fct_orders AS o, analytics.dim_date AS d. Um analisador sozinho deixaria d.country passar. check() qualifica cada coluna em relação às colunas das tabelas que a consulta pode ler, com o qualify do sqlglot, que levanta um erro para uma coluna que não consegue localizar.
Aqui ela recusa com column: Unknown column: country. A mensagem então lista as colunas de analytics.fct_orders, analytics.dim_date, de que o modelo precisa para corrigir a consulta. Executada como está, a consulta teria falhado no DuckDB com Binder Error: Table "d" does not have a column named "country".
SELECT 1; DROP TABLE analytics.fct_orders são duas instruções, Select, Drop, então a guarda aceita exatamente uma.
Uma consulta sem um parêntese de fechamento levanta o ParseError do sqlglot, cuja lista errors traz os campos de cada problema, col, description, end_context, highlight, into_expression, line, start_context. Para a consulta com erro do exemplo, a descrição é Expecting ), na linha 1, coluna 39. A guarda repassa essas informações ao modelo, como a seção de correção as usa.
Regra prática: Analise o SQL do agente em uma árvore antes que qualquer coisa seja executada, no dialeto do warehouse que vai executá-lo, e aceite exatamente uma instrução. Verifique nós, nunca texto. Trate uma consulta que é analisada como uma consulta cuja forma você agora pode inspecionar, não como uma consulta válida, e resolva suas colunas em relação às tabelas que ela pode ler antes de enviá-la ao warehouse.
Permita apenas consultas somente leitura em tabelas conhecidas
Com o SQL do agente analisado em uma árvore, o guarda pode fazer duas perguntas a ela: ela apenas lê? E ela lê apenas o que lhe é permitido? Verificar a instrução na raiz não basta. No DuckDB, uma expressão de tabela comum, um CTE, pode conter um DELETE com RETURNING dentro de um SELECT. Por isso, o guarda aceita apenas uma consulta na raiz, depois percorre cada nó da árvore e recusa qualquer instrução que escreva, altere configurações ou alcance algo fora do armazém.
Uma consulta hostil, enviada pelo guarda e diretamente ao banco somente leitura do agente, e também a uma cópia gravável da loja em uma pasta temporária, mostra o que uma escrita faria. Seu CTE exclui todos os reembolsos acima de 50 euros, e seu SELECT externo os conta.
1"""A DELETE hidden in a CTE: the root says SELECT, the tree walk finds the DELETE, and the read-only warehouse refuses it.23The attack runs for real only on a throwaway copy of the shop, built from the same seed in a temporary folder.4"""5import tempfile6from pathlib import Path78import duckdb9import sqlglot10from sqlglot import exp1112from lib.sql_guard import GuardError, SqlGuard13from lib.warehouse import agent_warehouse, build, connect1415ATTACK = """WITH gone AS (DELETE FROM analytics.fct_refunds WHERE amount_eur > 50 RETURNING refund_id)16SELECT count(*) AS refunds_over_50 FROM gone"""1718tree = sqlglot.parse_one(ATTACK, read="duckdb")19print("root:", type(tree).__name__)20print("statements in the tree:", ", ".join(type(n).__name__ for n in tree.walk() if isinstance(n, (exp.Query, exp.DML)))) # every node, not only the root2122agent = agent_warehouse(connect()) # the agent's read-only database23try:24 SqlGuard(agent).run(ATTACK)25except GuardError as e:26 print(f"guard refuses ({e.kind}): {e}")27try:28 agent.execute(ATTACK) # past the guard, straight to the read-only database29except duckdb.Error as e:30 print("read-only database:", str(e).splitlines()[0])3132with tempfile.TemporaryDirectory() as folder: # a writable copy, deleted when the block ends33 path = Path(folder) / "shop.duckdb"34 build(path)35 with duckdb.connect(str(path)) as writable:36 (before,), = writable.execute("SELECT count(*) FROM analytics.fct_refunds").fetchall()37 (answer,), = writable.execute(ATTACK).fetchall()38 (after,), = writable.execute("SELECT count(*) FROM analytics.fct_refunds").fetchall()39print("writable copy, refunds before:", before)40print("writable copy, the query's answer:", answer)41print("writable copy, refunds after:", after)
python block-a-delete.pyroot: Select
statements in the tree: Select, Delete
guard refuses (write): the query contains a Delete statement; only reads may run
read-only database: Invalid Input Error: Cannot execute statement of type "SELECT" on database "agent" which is attached in read-only mode!
writable copy, refunds before: 1068
writable copy, the query's answer: 931
writable copy, refunds after: 137
A raiz é um Select, então uma verificação da raiz a aprovaria. A varredura encontra Select, Delete, e o guarda a recusa. O banco somente leitura também recusa, e sua mensagem nomeia a instrução que viu como um SELECT.
Na cópia gravável, a consulta devolveu 931, uma contagem plausível de reembolsos, e analytics.fct_refunds passou de 1068 linhas para 137. Nada na resposta indica que linhas foram excluídas. O banco somente leitura é o que torna isso impossível; a verificação da análise sintática o transforma em uma recusa que o modelo consegue ler.
A segunda pergunta é quais tabelas. O banco de dados do agente já deixa de fora raw e analytics.orders_legacy, a definição antiga de receita sobre a qual o capítulo 2 alertou. O guarda verifica a mesma lista também no analisador, porque sua recusa nomeia as tabelas de que um reparo precisa, e porque precisa recusar o catálogo do DuckDB. A lista de permitidos é todas as tabelas do banco de dados do agente, lidas por allowed_schema() com as colunas de cada tabela, e o mesmo mapeamento é o esquema contra o qual qualify resolve colunas. A lista de permitidos é uma verificação independente, porque qualify não verifica se uma tabela existe.
Um nome sem esquema pode nomear um CTE, que é visível apenas na consulta cuja WITH o define, nas subconsultas dessa consulta e nos CTEs posteriores na mesma WITH. A função refers_to_cte() do guarda segue essas regras e recusa qualquer outro nome sem esquema. Para testar a lista de permitidos, o exemplo tenta seis maneiras de contorná-la, a última um CTE com o nome do catálogo do DuckDB, e então executa o SQL de referência de cada pergunta de referência através do guarda.
1"""The table allowlist: the marts the agent may read, six ways around it that the guard refuses, and the two golden2queries it can't answer. The last two lines are the cost the prose describes."""3from lib.golden import load_golden4from lib.sql_guard import GuardError, SqlGuard5from lib.warehouse import agent_warehouse, connect67con = agent_warehouse(connect()) # the agent's database: copies of the allowed marts, nothing else8guard = SqlGuard(con) # allowlist: the tables in it, read with their columns9print("allowed tables:", ", ".join(f"{db}.{t}" for db, tables in guard.schema.items() for t in tables))1011ATTEMPTS = {12 "raw table": "SELECT count(*) AS customers FROM raw.customers",13 "legacy mart": "SELECT sum(revenue) AS revenue FROM analytics.orders_legacy",14 "no schema": "SELECT count(*) AS orders FROM fct_orders",15 "file as a table": "SELECT * FROM 'data/golden/questions.toml'",16 "table function": "SELECT * FROM read_csv('data/golden/questions.toml')",17 "CTE named like the catalog": """SELECT * FROM (WITH duckdb_tables AS (SELECT 1 AS x) SELECT x FROM duckdb_tables) AS a,18duckdb_tables""",19}20for label, sql in ATTEMPTS.items():21 try:22 guard.check(sql)23 print(f"{label}: allowed")24 except GuardError as e:25 print(f"{label}: refused ({e.kind}), {str(e).split(';')[0]}") # the message's first clause2627golden = [q for q in load_golden() if q.golden_sql]28outside = []29for q in golden:30 try:31 guard.check(q.golden_sql)32 except GuardError as e:33 outside.append(f"{q.question_id} ({str(e).split(' ')[0]})") # the message starts with the table it refused34print(f"golden queries the allowlist refuses: {len(outside)} of {len(golden)}")35print("refused golden queries:", ", ".join(outside))
python block-raw-tables.pyallowed tables: analytics.dim_customers, analytics.dim_date, analytics.dim_products, analytics.fct_order_lines, analytics.fct_orders, analytics.fct_refunds, analytics.fct_sessions
raw table: refused (table), raw.customers isn't a table you may read
legacy mart: refused (table), analytics.orders_legacy isn't a table you may read
no schema: refused (table), fct_orders isn't a table you may read
file as a table: refused (table), data/golden/questions.toml isn't a table you may read
table function: refused (table), READ_CSV('data/golden/questions.toml') reads data through a function
CTE named like the catalog: refused (table), duckdb_tables is DuckDB's catalog, not a table you may read
golden queries the allowlist refuses: 2 of 34
refused golden queries: gq-034 (raw.marketing_spend), gq-037 (raw.customers)
As seis são recusadas, e três delas nem são nomes de tabela. Um caminho de arquivo na cláusula FROM é analisado como uma tabela com o nome do caminho, então a lista de permitidos a recusa. read_csv() é analisado como uma função no lugar da tabela, e o guarda recusa qualquer coisa em FROM que não seja uma tabela, uma subconsulta ou uma lista de VALUES, o que inclui range(), unnest() e query_table() também. O CTE chamado duckdb_tables é definido dentro de uma subconsulta, então o duckdb_tables depois dele nomeia a view de catálogo do DuckDB, e o guarda informa isso: refused (table), duckdb_tables is DuckDB's catalog, not a table you may read. Ele recusa todo nome de catálogo, como os que começam com duckdb_ ou pg_, e toda função que lê a instância, como current_setting(). Qualquer outra função precisa estar em ALLOWED_FUNCTIONS, as funções de que a análise da loja precisa.
As últimas duas linhas mostram o custo da lista de permitidos. Ela recusa 2 of 34 consultas douradas: gq-034 (raw.marketing_spend), gq-037 (raw.customers). Gastos com marketing não têm data mart, e cadastros duplicados existem apenas em raw.customers, porque o data mart os removeu.
Regra prática: Aceite apenas uma consulta na raiz, percorra cada nó em busca de uma instrução que escreva, e permita tabelas por esquema e nome, sem nada além de tabelas e subconsultas em FROM. Resolva um nome sem esquema como CTE apenas onde um CTE com esse nome estiver visível, recuse o catálogo do banco pelo nome e permita apenas as funções de que sua análise precisa. Verifique a mesma lista que o banco de dados do agente contém. Quando uma pergunta dourada precisar de uma tabela fora da lista, dê a ela um data mart ou uma métrica, não uma lista mais ampla.
Esta parte ainda não foi traduzida, por isso está em inglês.
Bound the rows and the cost
A query that only reads the allowed tables can still hurt: it can return every row of a fact table into the agent's context, or join three fact tables with no join condition and run for hours. The guard bounds both, and the time. For rows, it adds a LIMIT, and after the run it refuses a result longer than 50,000 characters, since one row can hold a whole column. For cost, the guard asks DuckDB's EXPLAIN for the plan, which plans the query without running it and gives each step an estimated number of rows (DuckDB). For time, it needs its own timer, because DuckDB has no statement timeout, and its documentation says to "Implement strict query timeouts at the application level" (DuckDB).
The costly mistake is chapter 2's fan-out taken to its end: orders, lines and refunds in one FROM clause with no keys. The plan-size limit refuses the keyless join before anything runs. The example sets that plan beside the same sum joined on order_id, checks the limit against the golden queries, and then tries three more things: a LIMIT the agent wrote, a query for too many rows, and the keyless join under the timer alone.
1"""Bound the rows and the cost: EXPLAIN a join that forgot its keys and refuse it, keep the agent's LIMIT, refuse a result2of every order, and stop the join by timer alone. The printed estimates and limits are the figures the prose quotes."""3import sqlglot45from lib.golden import load_golden6from lib.sql_guard import GuardError, SqlGuard, check, explain, run_with_timeout7from lib.warehouse import agent_warehouse, connect89guard = SqlGuard(con := agent_warehouse(connect())) # the agent's database, where the guard runs its checks10NO_KEYS = """SELECT sum(o.net_revenue_eur) AS net_revenue FROM analytics.fct_orders AS o,11analytics.fct_order_lines AS l, analytics.fct_refunds AS r"""12KEYED = """SELECT sum(o.net_revenue_eur) AS net_revenue FROM analytics.fct_orders AS o13JOIN analytics.fct_order_lines AS l USING (order_id)"""14for label, sql in (("no join keys", NO_KEYS), ("joined on order_id", KEYED)):15 cost = explain(con, check(sql, guard.schema).sql)16 print(f"{label}, largest step: {cost.largest_step}\n{label}, estimated rows: {cost.largest_estimate:,}") # one per query17try:18 guard.check(NO_KEYS)19except GuardError as e:20 print(f"guard refuses ({e.kind}): {e}")21costs = {q.question_id: explain(con, check(q.golden_sql, guard.schema).sql)22 for q in load_golden() if q.golden_sql and q.question_id not in ("gq-034", "gq-037")} # both need tables off the list23print("golden queries estimated:", len(costs))24print(f"largest estimate among golden queries: {max(c.largest_estimate for c in costs.values()):,} rows")25print("golden plans with a cross product:", ", ".join(i for i, c in costs.items() if c.cross_products))26print("golden plans with a step that has no estimate:", sum(1 for c in costs.values() if c.unestimated))27print(f"limit on estimated rows: {guard.max_estimated_rows:,}")2829TOP_FIVE = """SELECT product_id, sum(net_amount_eur) AS net_revenue FROM analytics.fct_order_lines30GROUP BY product_id ORDER BY net_revenue DESC LIMIT 5"""31print("sqlglot's .limit(1001):", sqlglot.parse_one(TOP_FIVE, read="duckdb").limit(1001).sql("duckdb").split("ORDER BY")[1].strip()) # the text after ORDER BY32print("guard's limit on the top five:", check(TOP_FIVE, guard.schema).limit)33try:34 guard.run("SELECT order_id, net_revenue_eur FROM analytics.fct_orders")35except GuardError as e:36 print(f"every order ({e.kind}): {e}")3738# The join without keys, through the time limit alone, as if the estimate had let it through. It reads its rows in39# batches, and DuckDB looks for the timer's interrupt between them.40try:41 run_with_timeout(con, check(NO_KEYS, guard.schema).sql, seconds=1.0)42except GuardError as e:43 print(f"no join keys, timer alone ({e.kind}): {e}")44print("connection still answers:", con.execute("SELECT count(*) FROM analytics.fct_orders").fetchall()[0][0])
python explain-before-running.pyno join keys, largest step: CROSS_PRODUCT
no join keys, estimated rows: 604,042,404,768
joined on order_id, largest step: SEQ_SCAN
joined on order_id, estimated rows: 38,071
guard refuses (cost): one step of the plan (CROSS_PRODUCT) is estimated to produce 604,042,404,768 rows, over the limit of 10,000,000; join each table on its key
golden queries estimated: 32
largest estimate among golden queries: 38,071 rows
golden plans with a cross product: gq-031
golden plans with a step that has no estimate: 0
limit on estimated rows: 10,000,000
sqlglot's .limit(1001): net_revenue DESC LIMIT 1001
guard's limit on the top five: 5
every order (rows): the query returns more than 1000 rows; aggregate or filter it
no join keys, timer alone (timeout): the query ran past the 1-second time limit and was stopped
connection still answers: 14856
The keyed join's largest step is a SEQ_SCAN of 38,071 rows. Without keys, the largest step is a CROSS_PRODUCT of 604,042,404,768 rows, and the guard refuses it with a message that tells the model to join on keys. The guard also refuses a plan with any step that has no estimate, such as an UNNEST that makes rows from a list, because it can't price such a plan.
Of the 32 golden queries the allowlist accepts, 0 have a step without an estimate, and the largest estimate among them is 38,071 rows, against a limit of 10,000,000 rows, a rule of thumb for the shop's size.
A cross product isn't always a mistake, either: DuckDB's plan for the golden query of gq-031, units per order, has one, and that query is correct.
The LIMIT needs care. sqlglot's .limit() replaces the LIMIT a query already has, so a top-five query given .limit(1001) ends in net_revenue DESC LIMIT 1001 and stops being a top five. The guard keeps the smaller limit, which is 5, and sets its own limit one row more than the 1,000 it allows, so it can tell a result that was cut from one that fits. A query for every order is refused: the query returns more than 1000 rows; aggregate or filter it. The first 1,000 rows would look like an answer, so a refusal makes the model aggregate.
The time limit is the backstop for estimates that are wrong. Under the timer alone, the join without keys shows whether the backstop holds. run_with_timeout() calls DuckDB's interrupt(), which DuckDB acts on between the batches of rows a query reads, so this query stops: the query ran past the 1-second time limit and was stopped. The connection then answers the next query, and counts 14856 orders.
Working rule: Bound every query four ways: a row limit that keeps a smaller one the agent wrote, a limit on the result's size, a plan-size limit from EXPLAIN checked before the query runs, and one deadline over every step of the guard, planning included. Refuse a result over either limit rather than cut it, and refuse a plan with a step that has no estimate. Set the plan limit from your own known-good queries. Never use EXPLAIN ANALYZE, which runs the query, and rely on the deadline and the result limits, not the estimate.
Esta parte ainda não foi traduzida, por isso está em inglês.
Enforce the deadline by killing a process
The bounds section stopped a slow query with an interrupt, but DuckDB acts on interrupt() only where it checks for one, and it can compute a constant while planning, before any such check. So the timer can't be relied on, but a killed process stops wherever it is.
The guard plans and runs the agent's query in a worker, a separate process started by Worker in lib/sql_guard.py that opens the agent's database file read-only with the guard's settings, and kills it when the 5-second deadline passes. At most 1,001 rows come back through a pipe, and an oversized result is refused inside the worker.
The query below compares each order ID with a constant sum over 30 million generated numbers, through list functions the guard's list refuses, which the example lets past so the plan is reached. Its plan is taken first with a small constant, 18, on two connections, and then a worker plans the full query under a half-second deadline.
1"""Stop a slow plan: DuckDB computes a constant while it plans, before any row is read, so a timer's interrupt has2nothing to stop; a killed worker stops wherever it is. The prose's claim that the plan never returns and the worker is3stopped rests on the assert after the worker's run."""4import json56from lib.sql_guard import GuardError, SqlGuard, Worker, check7from lib.warehouse import agent_warehouse, connect89shop = connect() # chapter 1's connection: constant folding on10agent = agent_warehouse(shop) # the agent's database: constant folding off11guard = SqlGuard(agent, timeout=0.5)12SLOW_PLAN = """SELECT count(*) AS n FROM analytics.fct_orders13WHERE order_id < list_sum(list_transform(range(30000000), x -> list_sum(range(40))))"""14# Checked as if the function list allowed the list functions, as sqlglot names them (range() is GENERATE_SERIES and15# list_transform() is TRANSFORM), so the plan reaches DuckDB.16LIST_FUNCTIONS = {"list_sum", "transform", "generate_series"}17planned = check(SLOW_PLAN, guard.schema, functions=guard.functions | LIST_FUNCTIONS).sql18# The same query with a small constant, 3 lists summing to 6 each: 18, under every order ID. A plan with no rows to19# read means DuckDB computed the constant while planning.20small = planned.replace("30000000", "3").replace("RANGE(0, 40)", "RANGE(0, 4)")21for label, connection in (("shop's connection, folding on", shop), ("agent's database, folding off", agent)):22 (_, plan), = connection.execute(f"EXPLAIN (FORMAT json) {small}").fetchall()23 steps, nodes = [], json.loads(plan) # the plan's tree, followed down its first child at each step24 while nodes:25 steps.append(nodes[0]["name"])26 nodes = nodes[0]["children"]27 print(f"EXPLAIN with a small constant, {label}: {' > '.join(steps)}")28worker = Worker(shop) # a process with its own connection to the shop's file29try:30 worker.explain(planned, 0.5)31 outcome = "planned"32except GuardError as e:33 outcome = e.kind # timeout, memory or worker_failed: the machine decides which34print("EXPLAIN in a worker with a half-second deadline, shop's connection, plan returned:", outcome == "planned")35print("EXPLAIN in a worker, still running afterwards:", worker.running)36assert outcome != "planned" and not worker.running # the half-second deadline stops the plan, and the kill leaves no worker37try:38 guard.run(SLOW_PLAN)39except GuardError as e:40 print(f"slow plan through the guard ({e.kind}): {e}")
python stop-a-slow-plan.pyEXPLAIN with a small constant, shop's connection, folding on: UNGROUPED_AGGREGATE > EMPTY_RESULT
EXPLAIN with a small constant, agent's database, folding off: UNGROUPED_AGGREGATE > EMPTY_RESULT
EXPLAIN in a worker with a half-second deadline, shop's connection, plan returned: False
EXPLAIN in a worker, still running afterwards: False
slow plan through the guard (function): list_sum() isn't a function the guard allows; use aggregates, window functions, casts, and date, number and text functions
With the small constant, the plan reads UNGROUPED_AGGREGATE > EMPTY_RESULT on the shop's connection, where DuckDB folds constants, and UNGROUPED_AGGREGATE > EMPTY_RESULT on the agent's database, where it doesn't (DuckDB). In both, DuckDB computed the constant while planning and found no order ID under it. For the full constant that is the slow step, so folding off is only a second line of defence, and the guard relies on the kill. In a worker with a half-second deadline, the plan doesn't come back on the shop's connection, and the worker is stopped afterwards.
Working rule: Start the deadline when the agent's SQL arrives, and run EXPLAIN under it as well as the query. Enforce it by killing a separate process with its own read-only connection, not with an interrupt. Check on your own database that a stopped plan and a stopped query really stop.
Reproduzir os ataques contra o guarda
Um primeiro rascunho do guarda confiava nas suas verificações de análise sintática e nos seus limites, na conexão do capítulo 1, que podia ver todos os schemas, e um crítico passou pelo analisador de três formas. Uma CTE com nome igual ao de uma visão de catálogo devolveu a instrução CREATE de cada tabela, incluindo raw. Uma constante dobrada durante o planejamento ultrapassou o cronômetro. Um produto cartesiano com unnest(range(200000)) passou pelo limite de tamanho do plano, porque um passo sem estimativa era contado como pequeno. Em cada caso, o modelo de SQL do guarda e o do banco de dados discordavam, e a leitura do banco é a que é executada. Duas revisões de segurança encontraram mais caminhos para contornar o guarda reforçado.
As tentativas das revisões e de três menores, reproduzidas contra cada camada, mostram qual delas se sustenta. Algumas vão direto ao banco de dados do agente, e cada uma passa pelo guarda, com seu limite de 5 segundos.
1"""The critics' attempts to get past the guard (lib/guard_attacks.py), replayed on a temporary copy of the marts: what the2database alone allows and what the guard does. The asserts back the claims the prose makes without a number."""3import duckdb45from lib.guard_attacks import ALONE, ATTEMPTS, alone, attempt, macro_then_sum6from lib.sql_guard import SqlGuard, explain7from lib.warehouse import agent_warehouse, connect89agent = agent_warehouse(connect())10guard = SqlGuard(agent) # the 5-second limit: the queries that run here finish far inside it11for label, sql in ATTEMPTS.items():12 if label in ALONE: # straight to the agent's database, with no guard in front13 print(f"{label}, database alone: {alone(agent, label)}")14 print(f"{label}, guard: {attempt(guard.run, sql)[0]}")15print("upper-case names, guard:", attempt(guard.run, "SELECT count(*) AS n FROM ANALYTICS.FCT_ORDERS")[0])1617# A temporary macro named sum, on a cursor of the database alone, then sent straight to the guard's worker.18alone_sum, real = macro_then_sum(agent, guard.worker)19print("temp macro named sum, database alone, the next sum:", alone_sum)20print("temp macro named sum, guard's worker, the next sum is the real one:", real)21assert real # the worker's fresh cursor dropped the macro, so the next sum is real2223# The regex attempt. In-process, a timer's interrupt waits for the end of a batch of rows, and one batch is this much24# text. With repeat() and regexp_matches() (sqlglot's REGEXP_LIKE) allowed, the guard's worker runs it under the25# review's 2-second limit, and stops it by the deadline or the memory cap, whichever the machine reaches first.26REGEX, BATCH = ATTEMPTS["regex on a repeated email"], duckdb.__standard_vector_size__27(text,), = agent.execute(f"SELECT sum(length(email)) * 200000 FROM (SELECT email FROM analytics.dim_customers "28 f"ORDER BY customer_id LIMIT {BATCH})").fetchall()29print(f"regex, characters to match in one batch of {BATCH:,} rows: {text:,}")30wider = SqlGuard(agent, timeout=2.0, functions=guard.functions | {"repeat", "regexp_like"})31print("regex, guard without the function list:", attempt(wider.run, REGEX)[1])32print("regex, worker still running afterwards:", wider.worker_running)33assert not wider.worker_running # the worker is gone, however it was stopped34print("regex, the guard's next query:", attempt(wider.run, "SELECT count(*) AS n FROM analytics.fct_orders")[0])3536# The inequality join ran. Its estimate varies a little between runs, so only its size is printed.37JOIN = ATTEMPTS["join on inequality"]38estimate, joined = explain(agent, JOIN).largest_estimate, guard.run(JOIN).rows[0][0] # the count is the only row and column39print("join on inequality, estimate under the limit:", estimate < guard.max_estimated_rows)40print(f"join on inequality, rows it joined: {joined:,}")41print("join on inequality, rows joined more than 100 times the estimate:", joined > 100 * estimate)42assert estimate < guard.max_estimated_rows and joined > 100 * estimate # under the limit, yet far more rows than estimated
python replay-guard-bypasses.pyCTE named duckdb_tables, database alone: 7 rows, one per table, all in analytics: True
CTE named duckdb_tables, guard: refused (table), duckdb_tables is DuckDB's catalog, not a table you may read
CTE named pg_settings, database alone: 170 rows of settings
CTE named pg_settings, guard: refused (table), pg_settings is DuckDB's catalog, not a table you may read
slow plan, guard: refused (function), list_sum() isn't a function the guard allows
unnest in FROM, guard: refused (table), UNNEST(RANGE(0, 200000)) AS t(x) makes rows from a function, not a table
unnest in a subquery, guard: refused (function), unnest() isn't a function the guard allows
every email in one row, database alone: 1 row of 106,670 characters
every email in one row, guard: refused (size), the result is 106,670 characters long, over the limit of 50,000
a setting read by a function, database alone: 1 row, a folder's path
a setting read by a function, guard: refused (table), current_setting() reads the database's settings or catalog
a table named with its database, database alone: 14,856 orders
a table named with its database, guard: refused (table), agent.analytics.fct_orders names a database
regex on a repeated email, guard: refused (function), regexp_matches() isn't a function the guard allows
database name and version, database alone: agent, v2.0.0
database name and version, guard: refused (table), current_database() reads the database's settings or catalog
600 nested subqueries, guard: refused (parse), the SQL is nested too deeply to check (the limit is 200 levels)
SIMILAR TO on an email, guard: refused (function), SIMILAR TO isn't an operator the guard allows
temp macro named sum, guard: refused (statement), only queries may run, and this is a Create statement
join on inequality, guard: ran
upper-case names, guard: ran
temp macro named sum, database alone, the next sum: 42
temp macro named sum, guard's worker, the next sum is the real one: True
regex, characters to match in one batch of 2,048 rows: 10,649,600,000
regex, guard without the function list: stopped, no answer
regex, worker still running afterwards: False
regex, the guard's next query: ran
join on inequality, estimate under the limit: True
join on inequality, rows it joined: 45,147,384
join on inequality, rows joined more than 100 times the estimate: True
Cada tentativa, exceto a junção, é recusada. A CTE chamada duckdb_tables, enviada somente ao banco de dados do agente, devolve 7 rows, one per table, all in analytics: True: o catálogo não consegue mostrar ao agente uma tabela que ele não pode ler, porque nenhuma existe ali. O plano lento e unnest() são recusados como funções fora da lista, como em refused (function), list_sum() isn't a function the guard allows. Uma linha com o nome e o e-mail de todos os clientes, 1 row of 106,670 characters, é recusada por ser grande demais.
A primeira tentativa da segunda revisão aplica um padrão ao e-mail de cada cliente repetido 200,000 vezes. Ela passou pelo analisador e pelo limite do plano, e escapou de uma interrupção, que o DuckDB verifica somente entre lotes de linhas; um lote aqui contém 10,649,600,000 caracteres. A lista de funções agora a recusa: refused (function), regexp_matches() isn't a function the guard allows. Executada com repeat() e regexp_matches() permitidas, sob o limite de 2 segundos da revisão, ela aparece como stopped, no answer, interrompida pelo prazo ou pelo limite de memória do worker, o que ocorrer primeiro. O worker também é interrompido, e a próxima consulta do guarda devolve ran.
current_database() e version(), que, sozinhos, devolvem agent, v2.0.0, haviam passado; o guarda agora verifica todas as funções. Seiscentas subconsultas aninhadas, que travaram o analisador do sqlglot, agora são recusadas: refused (parse), the SQL is nested too deeply to check (the limit is 200 levels).
Uma revisão final acrescentou duas. O guarda agora recusa SIMILAR TO, uma expressão regular como operador: refused (function), SIMILAR TO isn't an operator the guard allows. Uma macro temporária chamada sum, que só o banco de dados aceita, faz a próxima soma devolver 42. O analisador recusa a macro, e, se ela tivesse passado, o worker, que inicia cada consulta com um cursor novo, a descartaria, de modo que a próxima soma é a real.
A última tentativa junta pedidos a todos os clientes que não os fizeram, e ela foi executada, como as regras permitem. Sua estimativa estava abaixo do limite, e ela juntou 45,147,384 linhas, mais de 100 vezes a estimativa. Assim, o limite do plano só detecta os erros para os quais foi definido. O encerramento do worker, os limites de resultado e o limite de memória contêm o restante, e a seção de produção lista o que resta.
Regra prática: Confie nos limites do banco de dados e trate o analisador como defesa em profundidade. Mantenha todo ataque que alguém encontrar como um teste: reproduza-o contra o banco de dados do agente sozinho e através do guarda, e verifique se cada um é recusado pela camada que você espera. Quando um ataque passar pelo analisador, pergunte primeiro por que o banco deixou que ele chegasse a qualquer coisa e, depois, corrija o analisador.
Reparar uma vez, a partir do erro
Reparar significa entregar ao modelo, uma única vez, a recusa do guarda ou o erro do armazém de dados, e executar o que ele escrever em seguida. A pesquisa mostra quando o reparo ajuda. O Refiner do MAC-SQL, que corrige o SQL a partir da mensagem de erro, acrescentou 4.6 pontos no conjunto de desenvolvimento do BIRD com GPT-4 (Wang et al., Tabela 3). Sem um sinal externo, o reparo é mais fraco: modelos "têm dificuldade para corrigir sozinhos as próprias respostas sem retorno externo" (Huang et al.). No DIN-SQL, um prompt que dizia ao GPT-4 que o SQL dele tinha erros reduziu sua pontuação no Spider de 73.3 para 70.0 (Pourreza and Rafiei, Tabela 5). Por isso, o guarda repara somente com um sinal externo, a própria recusa ou o erro do DuckDB, e o prompt de reparo pede uma correção apenas quando a mensagem mostra como fazê-la.
O prompt de reparo está em GUARD_REPAIR em lib/prompts.py: a resposta própria do modelo, a mensagem e a instrução para responder com SQL corrigido ou com uma linha que começa com cannot answer:. answer_with_repair() em lib/sql_guard.py executa esse prompt no máximo uma vez por pergunta. O registro guarded-sql-runs guarda apenas as chamadas de reparo, feitas com o modelo fixado do livro, Qwen3-4B-Instruct-2507 em arquivo de 4 bits, escolhido como o capítulo 1 explica. Cada primeira resposta é reproduzida a partir do registro somente de esquema do capítulo 1 ou do registro em camadas do capítulo 4, e o modelo foi chamado apenas quando o guarda recusou essa resposta ou o DuckDB falhou: 6 vezes para SQL somente de esquema e 1 para SQL em camadas no conjunto de desenvolvimento. A mesma execução reparou as respostas do conjunto de teste, que a seção sobre a cauda longa usa. Pontuar os reparos separadamente mostra se eles ajudam: o exemplo pontua os dois tipos de primeira resposta nas 17 perguntas com resposta do conjunto de desenvolvimento, e imprime por completo dois reparos: a execução em camadas para gq-017, de a seção sobre o parse, e a execução somente de esquema para gq-001, receita líquida no ano fiscal de 2026.
1"""Repair once from the guard's message: how often one repair turns a refusal into an answer on the dev split, and two2repairs in full. The counts are the figures the prose quotes; the repaired SQL is printed for the reader to check."""3from collections import Counter45from lib.context import LAYERS, build_context6from lib.golden import golden_result, grade, load_golden7from lib.model import RecordedModels8from lib.prompts import layered_sql_messages, schema_only_messages9from lib.sql_guard import SqlGuard, answer_with_repair10from lib.warehouse import agent_warehouse, connect, describe_schema1112con = connect()13guard, schema = SqlGuard(agent_warehouse(con)), describe_schema(con)14# First replies from chapters 1 and 4's recordings; each repair reply from this chapter's.15model = RecordedModels("schema-only-sql", "context-layers", "guarded-sql-runs")16MESSAGES = {"schema-only": lambda q: schema_only_messages(schema, q.question),17 "layered": lambda q: layered_sql_messages(build_context(con, q.question, LAYERS).text, q.question)}18dev = [q for q in load_golden() if q.split == "dev" and q.kind == "answer"]19shown = {}2021for context, messages in MESSAGES.items():22 counts = Counter()23 for q in dev:24 run = answer_with_repair(guard, model, messages(q), q.question, role=q.role, repairs=1)25 outcome = grade(q, run.answer, golden_result(con, q))26 when = "after repair" if run.repaired else "first time"27 counts[f"ran {when}"] += run.attempts[-1].outcome == "ran"28 counts[f"correct {when}"] += outcome == "correct"29 counts[f"wrong {when}"] += outcome == "wrong"30 counts["refused or failed first"] += run.repaired31 counts["declined after repair"] += run.attempts[-1].outcome == "declined"32 shown[context, q.question_id] = run33 print(f"{context}, questions: {len(dev)}")34 for key in ("ran first time", "correct first time", "wrong first time", "refused or failed first",35 "ran after repair", "correct after repair", "wrong after repair", "declined after repair"):36 print(f"{context}, {key}: {counts[key]}")3738for context, question_id in (("layered", "gq-017"), ("schema-only", "gq-001")):39 run = shown[context, question_id]40 print(f"{question_id} {context}, refused: {run.attempts[0].message.split('. The tables')[0]}") # the refusal, without its list of tables41 print(run.attempts[1].sql) # attempt 0 is the first reply, attempt 1 the repair42 rows = len(run.answer.rows)43 print(f"{question_id} {context}, after repair: {run.attempts[1].outcome} and returned {rows} row{'s' * (rows != 1)}")
python repair-from-error.pyschema-only, questions: 17
schema-only, ran first time: 11
schema-only, correct first time: 2
schema-only, wrong first time: 9
schema-only, refused or failed first: 6
schema-only, ran after repair: 5
schema-only, correct after repair: 0
schema-only, wrong after repair: 5
schema-only, declined after repair: 0
layered, questions: 17
layered, ran first time: 16
layered, correct first time: 14
layered, wrong first time: 2
layered, refused or failed first: 1
layered, ran after repair: 1
layered, correct after repair: 0
layered, wrong after repair: 1
layered, declined after repair: 0
gq-017 layered, refused: Unknown column: country
SELECT o.country, round(sum(o.net_revenue_eur), 2) AS net_revenue
FROM analytics.fct_orders AS o
JOIN analytics.dim_date AS d ON d.date_day = o.order_date_local
WHERE o.status <> 'cancelled'
AND d.calendar_year = 2025
GROUP BY o.country
ORDER BY net_revenue DESC
gq-017 layered, after repair: ran and returned 10 rows
gq-001 schema-only, refused: Column 'fiscal_year' could not be resolved. Line: 3, Col: 17
SELECT SUM(net_revenue_eur) AS net_revenue
FROM analytics.fct_orders
WHERE EXTRACT(YEAR FROM placed_at) = 2026
gq-001 schema-only, after repair: ran and returned 1 row
O reparo funcionou como mecanismo. Para gq-017, a mensagem do guarda nomeou a coluna desconhecida e listou as colunas da tabela de pedidos, e o modelo moveu country do calendário para a tabela de pedidos. A consulta reparada ran and returned 10 rows. No SQL somente de esquema, 5 das 6 consultas recusadas ou com falha rodaram após um reparo.
O reparo não tornou as respostas corretas. O SQL somente de esquema obteve 0 respostas reparadas corretas, e o SQL em camadas, 0. A consulta reparada de gq-017 retorna todos os países, e a pergunta de referência é feita pelo líder regional da EMEA, que deveria ver apenas os países da EMEA: uma regra que o banco de dados próprio do líder impõe e que nenhum erro de SQL revela.
Para gq-001, o guarda recusou fiscal_year, que o modelo havia procurado na tabela de pedidos, e a correção do modelo filtrou pelo ano do calendário do carimbo de tempo UTC. Essa consulta ran and returned 1 row, mas responde a outra pergunta. Enquanto isso, o SQL em camadas rodou de primeira em 16 perguntas, com 2 delas erradas, e o reparo nunca as vê, porque nada falhou. No conjunto de desenvolvimento da loja, o reparo transformou erros visíveis em respostas que rodam e estão erradas, mais difíceis de perceber do que um erro.
Regra prática: Repare no máximo uma vez, e somente a partir de um sinal externo: a recusa do guarda ou o erro do armazém de dados, passados ao modelo junto com o SQL dele e com um prompt que não presume que o SQL está errado. Permita que o modelo recuse no reparo. Pontue as respostas reparadas separadamente das respostas de primeira, e, se as suas perguntas de referência mostrarem que elas raramente estão certas, recuse diante de uma recusa, em vez de reparar.
Transpile para o dialeto do warehouse
O warehouse da loja é o DuckDB, e o da maioria dos leitores, não. A mesma árvore pode ser escrita em outro dialeto, como o capítulo 5 fez para o SQL da camada semântica. O que é transpilado é o SQL do guard, com todos os identificadores entre aspas. O transpiler do sqlglot traduz o que conhece e, por padrão, emite um aviso e faz uma "tradução de melhor esforço" do que não consegue traduzir. Com unsupported_level=ErrorLevel.RAISE, que transpile() em lib/sql_guard.py usa, ele gera um erro em vez disso (sqlglot). Nenhum dos dois casos informa se o resultado significa o mesmo no destino.
Uma consulta de cauda longa, a receita líquida por dia da semana e mês em 2025, mostra o problema das aspas: o exemplo a escreve para o Snowflake duas vezes, primeiro com as aspas do guard e depois sem elas. Uma consulta com o agregado histogram() do DuckDB, que está na lista de funções do guard, mostra o que o transpiler faz com uma função que ele não conhece.
1"""Transpile the guard's SQL to Snowflake: the quoted table name Snowflake reads, a weekday function that answers differently,2and a histogram that passes through unchanged. The printed lines are the output the prose quotes."""3from lib.sql_guard import SqlGuard, transpile4from lib.warehouse import agent_warehouse, connect56con = connect()7guard = SqlGuard(agent_warehouse(con))8WEEKDAYS = """SELECT dayname(order_date_local) AS weekday, strftime(order_date_local, '%Y-%m') AS month,9 round(sum(net_revenue_eur), 2) AS net_revenue10FROM analytics.fct_orders11WHERE status <> 'cancelled' AND year(order_date_local) = 202512GROUP BY ALL ORDER BY month, weekday"""13checked = guard.check(WEEKDAYS)14print("kept quoted, Snowflake reads:", transpile(checked.sql, "snowflake", quoted=True).sql.split(" FROM ")[1].split(" WHERE")[0]) # the FROM clause only1516snowflake = transpile(checked.sql, "snowflake", pretty=True)17print(snowflake.sql)18print("functions passed through unchanged:", ", ".join(snowflake.passed_through) or "none")19print("DuckDB's first weekday:", guard.run(WEEKDAYS).rows[0][0])2021MIX = """SELECT region, histogram(channel) AS orders_by_channel FROM analytics.fct_orders22WHERE year(order_date_local) = 2025 GROUP BY region"""23mix = transpile(guard.check(MIX).sql, "snowflake")24print("channel mix in Snowflake:", mix.sql.split(" FROM")[0]) # the SELECT list, which holds the function25print("functions passed through in the channel mix:", ", ".join(mix.passed_through) or "none")
python transpile-to-snowflake.pykept quoted, Snowflake reads: "analytics"."fct_orders" AS "fct_orders"
SELECT
DAYNAME(fct_orders.order_date_local) AS weekday,
TO_CHAR(fct_orders.order_date_local, 'yyyy-mm') AS month,
ROUND(SUM(fct_orders.net_revenue_eur), 2) AS net_revenue
FROM analytics.fct_orders AS fct_orders
WHERE
fct_orders.status <> 'cancelled' AND YEAR(fct_orders.order_date_local) = 2025
GROUP BY ALL
ORDER BY
month,
weekday
LIMIT 1001
functions passed through unchanged: none
DuckDB's first weekday: Friday
channel mix in Snowflake: SELECT fct_orders.region AS region, HISTOGRAM(fct_orders.channel) AS orders_by_channel
functions passed through in the channel mix: histogram
Mantida entre aspas, a tabela vira "analytics"."fct_orders" AS "fct_orders". No Snowflake, isso nomeia outra tabela, porque o Snowflake converte nomes sem aspas para maiúsculas e trata nomes entre aspas como sensíveis a maiúsculas e minúsculas (Snowflake). Por isso, transpile() remove as aspas, a menos que se peça para mantê-las, e a segunda versão fica analytics.fct_orders. O sqlglot reescreveu strftime() como TO_CHAR() com o formato do Snowflake e, como conhecia todas as funções da consulta, none passou sem alteração.
Esse resultado limpo ainda altera a resposta. dayname() virou DAYNAME(), e os dois nomes não significam a mesma coisa. A função dayname() do DuckDB devolve o nome em inglês do dia da semana, que aqui é Friday, enquanto a função de Snowflake devolve um nome abreviado de três letras para o dia da semana. As mesmas linhas recebem rótulos diferentes e, por isso, um resultado de referência que diz Friday falha no Snowflake. A mistura de canais é a outra falha: histogram é uma função que o sqlglot não conhece, então foi escrita sem alteração, SELECT fct_orders.region AS region, HISTOGRAM(fct_orders.channel) AS orders_by_channel, sem nenhum erro. transpile() lista essas funções, aqui histogram, para que você possa recusá-las ou verificá-las manualmente.
Regra prática: deixe o agente escrever no dialeto em que suas perguntas de referência são verificadas, proteja esse SQL com o guard e transpile a saída do guard, não o texto do agente, com erros gerados para o que o transpiler sabe que não consegue traduzir. Remova as aspas do guard em warehouses que convertem nomes sem aspas para maiúsculas, recuse as funções que o transpiler deixou passar sem alteração e execute as perguntas de referência no warehouse de destino antes de confiar em uma resposta transpilada, porque uma função com o mesmo nome pode devolver valores diferentes.
Quando preferir uma nova métrica ao SQL
O banco de dados e as guardas tornam o SQL do agente seguro para executar: limitado às views do perfil do agente (a seção sobre views), restrito em tamanho e reparado uma vez. Nenhuma delas, porém, o torna correto. Uma métrica está correta por construção, porque uma pessoa a definiu uma única vez. Por isso, o SQL com guardas serve para perguntas feitas uma vez só, enquanto uma pergunta que volta sempre, ou cujo número entra em um relatório, deve virar métrica. Para distinguir os dois casos, avalie o caminho com guardas na cauda longa das perguntas de referência e leia cada resposta errada.
A cauda longa da loja são as dez perguntas de resposta que nenhuma métrica ou dimensão em examples/data/semantic/ cobre, como pedidos que incluem uma barraca, conversão de sessões e desconto. 2 dessas dez estão na divisão de desenvolvimento e 8 na divisão de teste reservada. Duas perguntas são poucas para avaliar, por isso o número da cauda longa vem do teste. As guardas e o prompt de reparo foram ajustados no desenvolvimento, e nada mudou depois que lemos o teste uma vez. O capítulo 4 já avaliou ali as primeiras respostas. Avaliamos esse caminho primeiro e, depois, promovemos uma pergunta em uma cópia do seu YAML.
1"""Guarded SQL on the long tail, the answer questions no metric in the semantic layer covers; then one promoted."""2import shutil3import tempfile4from collections import Counter5from pathlib import Path67from lib.answers import format_value8from lib.context import LAYERS, build_context9from lib.golden import golden_result, grade, load_golden, results_match10from lib.model import RecordedModels11from lib.prompts import layered_sql_messages12from lib.semantic import SEMANTIC_DIR, MetricRequest, load13from lib.sql_guard import SqlGuard, answer_with_repair14from lib.warehouse import agent_warehouse, connect1516LONG_TAIL = {"gq-007": "a filter on what an order contains", "gq-016": "customers with an order",17 "gq-031": "units per order", "gq-032": "gross margin", "gq-033": "session conversion",18 "gq-034": "marketing spend", "gq-036": "one order's refunds", "gq-037": "duplicate sign-ups",19 "gq-038": "a weekday dimension", "gq-041": "discount"}20con, golden = connect(), {q.question_id: q for q in load_golden()}21guard, model = SqlGuard(agent_warehouse(con)), RecordedModels("context-layers", "context-layers-test", "guarded-sql-runs")22counts = Counter()23for question_id, needs in LONG_TAIL.items():24 q = golden[question_id]25 run = answer_with_repair(guard, model, layered_sql_messages(build_context(con, q.question, LAYERS).text,26 q.question), q.question, role=q.role)27 outcome = grade(q, run.answer, gold := golden_result(con, q))28 counts[q.split, outcome] += 129 print(f"{question_id} ({q.split}, {needs}): {outcome}, after {' then '.join(a.outcome for a in run.attempts)}")30 if outcome == "wrong":31 row = ", ".join(map(format_value, min(run.answer.rows))) if run.answer.rows else "no rows"32 print(f"{question_id} first row: {row} (golden: {', '.join(map(format_value, min(gold)))})")33print(*(f"long tail questions on {s}: {sum(golden[i].split == s for i in LONG_TAIL)}" for s in ("dev", "test")), sep="\n")34for split, outcome in [(s, o) for s in ("dev", "test") for o in ("correct", "wrong", "declined")]:35 print(f"long tail {split} {outcome}: {counts[split, outcome]} of {sum(n for (s, _), n in counts.items() if s == split)}")3637with tempfile.TemporaryDirectory() as folder: # promote gq-038: one dimension added to a copy of the YAML38 shutil.copytree(SEMANTIC_DIR, copy := Path(folder) / "semantic")39 with open(copy / "orders.yml", "a") as orders:40 orders.write(" - name: weekday\n type: categorical\n expr: dayname(order_date_local)\n")41 layer = load(copy)42answer = layer.query(con, MetricRequest(("net_revenue", "orders"), ("order__weekday",), {"metric_time__year": 2025}))43print("gq-038 as a metric request matches golden:", results_match(answer.rows, golden_result(con, golden["gq-038"])))44assert results_match(answer.rows, golden_result(con, golden["gq-038"])) # the promotion gives the golden answer
python long-tail-score.pygq-007 (dev, a filter on what an order contains): wrong, after ran
gq-007 first row: NULL (golden: 377,497.40)
gq-016 (dev, customers with an order): correct, after ran
gq-031 (test, units per order): correct, after ran
gq-032 (test, gross margin): wrong, after ran
gq-032 first row: 773,723.34 (golden: 847,864.71)
gq-033 (test, session conversion): wrong, after ran
gq-033 first row: (none), 13.46 (golden: (none), 0.13)
gq-034 (test, marketing spend): declined, after table then declined
gq-036 (test, one order's refunds): correct, after ran
gq-037 (test, duplicate sign-ups): wrong, after ran
gq-037 first row: no rows (golden: 54)
gq-038 (test, a weekday dimension): wrong, after ran
gq-038 first row: Friday, 221,172.11, 822 (golden: Friday, 221,172.11, 869)
gq-041 (test, discount): correct, after ran
long tail questions on dev: 2
long tail questions on test: 8
long tail dev correct: 1 of 2
long tail dev wrong: 1 of 2
long tail dev declined: 0 of 2
long tail test correct: 3 of 8
long tail test wrong: 4 of 8
long tail test declined: 1 of 8
gq-038 as a metric request matches golden: True
No desenvolvimento, o SQL com guardas acerta 1 of 2; no teste, acerta 3 of 8, com 1 of 8 recusada(s). A recusa foi a gq-034, retorno sobre o gasto em marketing: o guarda barrou raw.marketing_spend, e, no reparo, o modelo respondeu que nenhuma tabela permitida guarda gastos, o que está certo. A correção é um mart.
Toda resposta errada passou limpa por todas as guardas. Para gq-007, o modelo cometeu os dois erros que o capítulo 4 havia encontrado: escreveu a categoria tents onde a loja guarda Tents, de modo que a soma voltou NULL (golden: 377,497.40); e somou apenas as linhas de barraca, enquanto a pergunta pede a receita total dos pedidos que incluíram uma delas. Para gq-032, margem bruta, o modelo subtraiu a receita líquida da receita bruta, o que dá o imposto, e juntou as linhas de pedido por order_id, de modo que cada pedido conta uma vez por linha, o fan-out do capítulo 2: 773,723.34 (golden: 847,864.71). O limite de tamanho do plano não detecta um fan-out em uma chave. Para gq-033, o modelo deu a conversão como porcentagem, onde a loja informa uma fração: (none), 13.46 (golden: (none), 0.13). Para gq-038, receita líquida e pedidos por dia da semana, a receita está certa e a contagem de pedidos não: Friday, 221,172.11, 822 (golden: Friday, 221,172.11, 869). O modelo deixou os pedidos cancelados fora da contagem, enquanto a métrica orders da loja os mantém.
gq-038 é a que deve ser promovida. A loja define as duas métricas e só lhe falta uma dimensão de dia da semana: três linhas de YAML no modelo semântico de pedidos, com a expressão dayname(order_date_local). Com ela, a pergunta vira um pedido de métrica agrupado por order__weekday em 2025, e isso bate com o resultado de referência. Esse não é um resultado reservado (held-out): escolhemos a pergunta a partir da falha de gq-038 no teste. A camada do livro não muda, por isso gq-038 permanece no teste; na sua própria camada, mova-a para o desenvolvimento. gq-034 e gq-037 precisam de um mart primeiro, porque o agente não pode ler raw, e com razão. Consultas pontuais como gq-036, os reembolsos de um pedido e os motivos deles, são o que o SQL com guardas responde bem.
Regra prática: Envie uma pergunta ao SQL com guardas somente quando nenhuma métrica a cobrir, e avalie esse caminho na sua própria cauda longa de perguntas de referência. Promova uma pergunta para a camada semântica quando ela se repetir, quando sua resposta entrar em um relatório ou quando o SQL com guardas errar por causa de uma definição, como o que conta como pedido. Mantenha as consultas pontuais no caminho com guardas. Quando uma pergunta precisar de uma tabela fora da lista de permitidas, construa o mart e a sua métrica em vez de ampliar a lista.
O que dá errado em produção
Uma guarda que passou nos testes ainda pode estar errada em uso, porque o warehouse, os papéis e as listas de funções continuam mudando por baixo dela, e cada falha abaixo vem com o sintoma que a revela.
Uma resposta errada passa por todas as guardas. O banco e as guardas limitam o que uma consulta lê e o que ela custa, não o que o seu número significa. A correção baseada em execução não consegue corrigir um SQL que roda e está errado, e é por isso que Hong et al. acrescentam detecção de erros antes do reparo (Hong et al.), e Chaturvedi et al. orientam a correção com uma taxonomia de erros (Chaturvedi et al.). Você só percebe isso ao avaliar o caminho protegido com perguntas de referência e ao ler respostas cujo resultado está vazio, é NULL ou é um percentual onde você esperava uma fração.
A conexão do agente fica acima das views. O limite só se sustenta se o usuário de warehouse do agente não puder ler as tabelas sob as suas views. Verifique as permissões dele sempre que os papéis do warehouse mudarem.
A view de um papel está errada ou desatualizada. Uma view devolve o que a sua definição diz, então um filtro de linhas ou uma máscara ausente vaza em todos os caminhos ao mesmo tempo. No DuckDB, o banco de dados de cada papel é uma cópia feita no momento da sua criação, então ele deve ser reconstruído sempre que os marts forem. Gere as views a partir de uma única política, teste cada papel com consultas que o parser aceita e nomeie cada tabela uma a uma, para que um novo mart fique fora até que alguém o adicione.
As listas de funções e de catálogo são julgamentos. Uma função de que os analistas precisam pode estar ausente, uma função que está na lista ainda pode ser lenta, e uma nova função de catálogo do DuckDB pode superar a lista. Registre cada recusa por function e revise as duas listas a cada versão do DuckDB.
A guarda recusa SQL bom. A guarda recusa sintaxe do DuckDB que o sqlglot não consegue modelar. Registre cada recusa com o seu tipo e execute cada consulta de referência pela guarda no CI, como faz a seção sobre a lista de permitidos.
Uma estimativa não é um custo. O replay mostra um join que produziu mais de 100 vezes a sua estimativa. Registre a estimativa de cada consulta ao lado do seu tempo de execução.
Um banco somente leitura ainda guarda estado. Uma conexão DuckDB somente leitura aceita tabelas temporárias, views, macros e variáveis, então uma instrução que passe pelo parser poderia alterar respostas posteriores, como mostra a macro de o replay. O worker dá a cada consulta um cursor novo; faça o mesmo em qualquer pool de conexões compartilhado.
O limite de memória do DuckDB não cobre todos os valores. Ele "só se aplica ao gerenciador de buffers" (DuckDB), então as strings que uma expressão constrói escapam do seu 1 GB. O worker limita o próprio processo a 1.5 GB acima do tamanho que ele tem assim que o banco é aberto. Um worker que fica sem memória, morre ou nunca inicia levanta GuardError (memory ou worker_failed) e não devolve linhas: a guarda falha de modo seguro (fail closed). As verificações de parse rodam no processo da própria guarda, limitadas apenas pelo limite de 20,000 caracteres e pelo limite de profundidade. Dê a cada execução de agente a sua própria guarda, porque um worker responde a uma consulta por vez.
O limite do próprio warehouse está longe. O STATEMENT_TIMEOUT_IN_SECONDS do Snowflake tem como padrão "172800 (2 days)" (Snowflake). Defina o limite de tempo do agente na guarda e, também, um limite menor no papel de warehouse do agente.
O reparo esconde erros. Na divisão de desenvolvimento do shop, toda consulta reparada que rodou estava errada. Registre as tentativas com cada resposta, como answer_with_repair() faz no seu GuardedRun, e conte as respostas reparadas em toda pontuação.
As mensagens da guarda descrevem o banco de dados. Uma recusa lista as tabelas permitidas e as suas colunas. Construa a guarda sobre o banco de dados do próprio papel, para que ela liste apenas o que o papel pode ver.
Regra prática: Trate o banco somente leitura de views do papel como o controle, e a guarda como uma camada que transforma erros em recusas e limita o custo. Verifique as permissões do agente e teste as views de cada papel, execute cada consulta de referência pela guarda no CI, defina o limite de tempo na guarda e no warehouse, registre cada recusa, estimativa e reparo junto da sua resposta, e avalie o caminho na sua própria cauda longa de perguntas de referência após cada mudança.
Decisões tomadas neste capítulo
- O SQL protegido é o recurso de contingência, não o padrão, para perguntas que nenhuma métrica cobre, escrito com as quatro camadas de contexto do capítulo 4.
- O banco de dados é a fronteira de segurança. O SQL do agente roda somente leitura sobre
agent_warehouse(): um arquivo que contém os sete data marts permitidos ou, dada a política de um papel, as views desse papel sobre eles. Em um data warehouse com papéis, isso significa um papel somente leitura comSELECTsobre secure views, ou políticas de acesso por linha e de mascaramento. - O parser, o cronômetro e a verificação de custo são uma camada didática e defesa em profundidade, não a fronteira.
- O que é executado é o SQL do guardião, analisado e regenerado pelo sqlglot, com toda coluna qualificada e um limite de linhas acrescentado: uma instrução, uma consulta na raiz e nenhuma instrução de escrita em qualquer ponto da árvore.
- A lista de permissões são as tabelas do banco, nomeadas uma a uma, com os nomes de CTE resolvidos por escopo, o catálogo do DuckDB recusado, apenas funções listadas permitidas,
SIMILAR TOeGLOBrecusados, aninhamento limitado e nada além de tabelas e subconsultas emFROM. Duas perguntas de ouro (golden questions) não podem ser respondidas dentro dela. - Quatro limites em cada consulta: no máximo 1,000 linhas e 50,000 caracteres, recusados em vez de cortados; um plano cuja maior etapa
EXPLAINestima em no máximo 10 milhões de linhas, uma regra prática, sem nenhuma etapa sem estimativa; e um único prazo de 5 segundos sobre as verificações, o plano e a execução, imposto pelo encerramento do processo de trabalho, que executa cada consulta em um cursor novo. - Uma única correção, a partir da recusa do guardião ou do erro do DuckDB, com um prompt que permite ao modelo recusar. Respostas corrigidas são pontuadas separadamente.
- Transpile a saída do guardião, sem as aspas, levantando erro para o que o sqlglot não consegue traduzir e listando as funções que foram repassadas.
- Promova uma pergunta a métrica quando ela se repetir, quando seu número for reportado ou quando o SQL protegido errar sua definição.
Este capítulo, nesta edição
Edição 2026.11.15Exemplos aprovados em 19 de nov de 202611 de 11 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.15.