Let the agent write SQL inside guards

Unos 38 minutos de lectura, con 11 ejemplos en 12 secciones.

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

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

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

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

By the end of this chapter, you can 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.

Dale al agente una base de datos con solo lo que puede leer

Último cambio en la edición 2026.11.12

El principio de mínimo privilegio significa que el SQL del agente se ejecuta en una conexión que solo puede llegar a lo que el agente tiene permiso de consultar, y nada más. Va antes que cualquier comprobación sobre el SQL, porque una comprobación es un juicio sobre texto, y cuando ese juicio es erróneo, es la base de datos la que decide hasta dónde llega la consulta.

La warehouse.connect() del capítulo 1 es de solo lectura, pero ve todo: el esquema raw, el data mart heredado y las vistas semánticas. Por eso agent_warehouse() en lib/warehouse.py copia los siete data marts que el agente puede leer, nombrados uno a uno en AGENT_TABLES, en un segundo archivo de base de datos, y lo abre en modo de solo lectura. El acceso a archivos y las extensiones están desactivados, la memoria se limita a 1 GB y cada consulta a dos hilos, y la configuración queda bloqueada, de modo que una consulta no puede volver a activar nada de eso. Una configuración solo es tan buena como los intentos que la ponen a prueba, así que el ejemplo envía seis intentos directamente a la base de datos del agente, sin ninguna protección (guard) delante, y después lee el catálogo de DuckDB.

agent-warehouse.py Python 3.12.15 · duckdb 2.0.0 Superado
"""The agent's own database holds copies of the seven allowed marts, opened read-only with files, extensions and settingslocked. The attempts show what those locks refuse, and the catalog lines show what they can't hide."""import duckdbfrom lib.warehouse import agent_warehouse, connectshop = connect()agent = agent_warehouse(shop)                 # a second file: the seven allowed marts, copied, and nothing else(shop_tables,), = shop.execute("SELECT count(*) FROM duckdb_tables()").fetchall()print("tables in the shop's warehouse:", shop_tables)tables = agent.execute("SELECT schema_name || '.' || table_name FROM duckdb_tables() ORDER BY 1").fetchall()print("tables in the agent's database:", len(tables))print("the agent's tables:", ", ".join(name for (name,) in tables))(source,), = shop.execute("SELECT path FROM duckdb_databases() WHERE database_name = 'shop'").fetchall()ATTEMPTS = {                                  # sent straight to the agent's database, with no guard in front    "raw table": "SELECT count(*) FROM raw.customers",    "legacy mart": "SELECT sum(revenue) FROM analytics.orders_legacy",    "attach the shop's file": f"ATTACH '{source}' AS shop (READ_ONLY)",    "read a file": "SELECT * FROM read_csv('data/golden/questions.toml')",    "load an extension": "LOAD httpfs",    "turn file access back on": "SET enable_external_access = true",}for label, sql in ATTEMPTS.items():    try:        agent.execute(sql).fetchall()        print(f"{label}: allowed")    except duckdb.Error as e:        kind, message = str(e).splitlines()[0].split(": ", 1)   # the error's kind, then its message        print(f"{label}: {kind}, {message.split(' - ')[-1]}")   # the file's path is left out of the output# What no setting hides: DuckDB's own catalog, which every database has.(listed,), = agent.execute("SELECT count(*) FROM information_schema.tables WHERE table_schema = 'analytics'").fetchall()print("catalog, tables it lists:", listed)(settings,), = agent.execute("SELECT count(*) FROM duckdb_settings()").fetchall()print("catalog, settings it lists:", settings)(paths,), = agent.execute("SELECT count(*) FROM duckdb_databases() WHERE path IS NOT NULL").fetchall()print("catalog, database files it names:", paths)
Salidapython agent-warehouse.py
tables 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

El warehouse de la tienda tiene 16 tablas, y la base de datos del agente conserva 7 de ellas. Una consulta sobre raw.customers devuelve Catalog Error, Table with name "raw.customers" does not exist because schema "raw" does not exist.. Nada la rechazó, porque el esquema no está ahí, y tampoco está el data mart heredado. Adjuntar el archivo de la tienda, leer cualquier otro archivo y cargar una extensión fallan. Un SET que volviera a activar el acceso a archivos también falla, porque la configuración está bloqueada. La documentación de DuckDB llama a estos ajustes "defensa en profundidad" y añade que "no sustituyen a un sandboxing adecuado" (DuckDB).

Lo que ninguna configuración oculta es el catálogo de DuckDB, como information_schema y duckdb_settings(), que describe la propia base de datos. En la base de datos del agente, el catálogo enumera 7 tablas, todas ellas de las que el agente puede leer, y 170 ajustes, y nombra 1 archivo de base de datos con su ruta en disco. La base de datos no puede rechazar esas lecturas, así que la sección de la lista de permitidos las rechaza en el analizador.

Regla práctica: Ejecuta el SQL del agente en una conexión que solo pueda llegar a lo que el agente tiene permiso de consultar: un rol con solo esos permisos o, en DuckDB, un archivo de base de datos de solo lectura que contenga únicamente las tablas permitidas, con el acceso a archivos y la carga de extensiones desactivados y su configuración bloqueada. Nombra las tablas permitidas una por una. Después enumera lo que la base de datos no puede ocultar, como su catálogo, y rechaza esas lecturas en la protección (guard).

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

Give each role a database of views

Último cambio en la edición 2026.11.15

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.

role-database.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""A role's database, not the guard, decides what the role reads: queries the guard accepts return less from each role'sdatabase than from every mart, and the catalog bypass lists no net_revenue_eur for support. The assert after the bypass'stables-listed line settles that none of support's tables has the net_revenue_eur column the sum needs."""import duckdbfrom lib.guard_attacks import ATTEMPTSfrom lib.policies import policy_forfrom lib.sql_guard import SqlGuardfrom lib.warehouse import agent_warehouse, connectshop = connect()marts = agent_warehouse(shop)                 # every allowed mart, whole: no role's limitsguard = SqlGuard(marts)                       # chapter 7's guard knows tables and columns, not rolesroles = {"EMEA's regional lead": policy_for("regional_lead", "EMEA"), "finance": policy_for("finance"),         "support": policy_for("support")}QUERIES = {"EMEA's regional lead": "SELECT count(DISTINCT region) AS regions FROM analytics.fct_orders",           "finance": "SELECT count(*) AS n FROM analytics.dim_customers WHERE email LIKE 'customer-0004%'",           "support": "SELECT sum(net_revenue_eur) AS revenue FROM analytics.fct_orders"}def first_value(con, sql):    try:        return con.execute(sql).fetchall()[0][0]          # the first column of the first row    except duckdb.Error as e:        return str(e).splitlines()[0]for role, sql in QUERIES.items():    database = agent_warehouse(shop, policy=roles[role])     # the role's database: its views of the marts only    guard.check(sql)                                         # raises if the guard refuses; it doesn't    print(f"{role}, guard accepts: yes")    print(f"{role}, every mart: {first_value(marts, sql)}")    print(f"{role}, role's database: {first_value(database, sql)}")# A parser bypass a draft of the guard let through: a CTE named like DuckDB's catalog, which lists every table's SQL.support = agent_warehouse(shop, policy=roles["support"])# the bypass's rows as text: each table's CREATE statement, as DuckDB's catalog shows itlisted = " ".join(str(row) for row in support.execute(ATTEMPTS["CTE named duckdb_tables"]).fetchall())print(f"support, catalog bypass, tables listed: {listed.count('CREATE TABLE')}")assert "net_revenue_eur" not in listed              # the catalog lists no net_revenue_eur for support, which its sum needsprint(f"support, catalog bypass, names a revenue column: {'net_revenue_eur' in listed}")print(f"support, a write: {first_value(support, 'DELETE FROM analytics.fct_orders')}")
Salidapython role-database.py
EMEA'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.

Analiza el SQL antes de ejecutarlo

Último cambio en la edición 2026.11.12

Una guarda solo puede revisar lo que puede ver, y el SQL como texto muestra muy poco: una comprobación de la palabra DELETE no detecta un comentario, un nombre entre comillas ni una docena de formas de escribir la misma sentencia. El análisis convierte el texto en un árbol, con un nodo para cada sentencia, tabla, columna y función, de modo que cada comprobación posterior pregunta por nodos y no por caracteres. sqlglot, en la versión 30.31.0, analiza SQL en el dialecto de DuckDB y en otros muchos, y ese mismo árbol después vuelve a convertirse en SQL. Su README es claro sobre lo que el análisis no hace: "SQLGlot is a transpiler, not a validator. A query that parses successfully may still fail at execution time" (sqlglot). Por eso la guarda analiza primero y luego comprueba el árbol contra el almacén en el que se ejecutará.

Para gq-017, los ingresos netos de cada país de la tienda en 2025, la grabación del capítulo 4 con los cuatro niveles de contexto contiene una respuesta que agrupa por una columna de país de la tabla de calendario. Para ver qué hace la guarda con ella, el ejemplo analiza esa respuesta, muestra el árbol y ejecuta sobre él la comprobación check() de la guarda; después analiza una cadena con dos sentencias y una consulta mal formada, para mostrar dónde se detiene el análisis.

parse-agent-sql.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Parse the SQL the model wrote for gq-017 before it runs: its tree, the tables it reads, a column the guard refuses, andtwo inputs that don't parse as one query. The prose's examples of each come from these printed lines."""import duckdbimport sqlglotfrom sqlglot import expfrom sqlglot.errors import ParseErrorfrom lib.context import LAYERS, build_contextfrom lib.golden import load_goldenfrom lib.model import RecordedModelfrom lib.prompts import layered_sql_messagesfrom lib.sql_guard import GuardError, allowed_schema, checkfrom lib.tools import extract_sqlfrom lib.warehouse import agent_warehouse, connectcon = connect()question = next(q for q in load_golden() if q.question_id == "gq-017")context = build_context(con, question.question, LAYERS)          # chapter 4's context, every layersql = extract_sql(RecordedModel("context-layers").complete(layered_sql_messages(context.text, question.question)))print(f"question: {question.question}\n{sql}")tree = sqlglot.parse_one(sql, read="duckdb")print("root:", type(tree).__name__)print("tables read:", ", ".join(f"{t.db}.{t.name} AS {t.alias}" for t in tree.find_all(exp.Table)))print("columns named:", ", ".join(sorted({f"{c.table}.{c.name}" for c in tree.find_all(exp.Column) if c.table})))try:    check(sql, allowed_schema(agent_warehouse(con)))       # the allowlist: the agent's database's tablesexcept GuardError as e:    print("guard refuses:", e.kind)    # the refusal, then the columns of each table it reads, after a fixed phrase    message, columns = str(e).split(". The tables it reads have only these columns: ")    print("guard message:", message)    print("message then lists the columns of:", ", ".join(part.split(" has ")[0] for part in columns.split("; ")))try:    con.execute(sql)except duckdb.Error as e:    print("DuckDB, had it run:", str(e).splitlines()[0])statements = sqlglot.parse("SELECT 1; DROP TABLE analytics.fct_orders", read="duckdb")print("statements in one string:", ", ".join(type(s).__name__ for s in statements))try:    sqlglot.parse_one("SELECT region, sum(net_revenue_eur FROM analytics.fct_orders GROUP BY region", read="duckdb")except ParseError as e:    error = e.errors[0]                     # the parser's first problem; line and col count from 1    print("parse error fields:", ", ".join(sorted(error)))    print(f"parse error: {error['description']}\nparse error line: {error['line']}\nparse error column: {error['col']}")
Salidapython parse-agent-sql.py
question: 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

La raíz del árbol es un Select, y su valor es analytics.fct_orders AS o, analytics.dim_date AS d. Un analizador por sí solo dejaría pasar d.country. check() califica cada columna frente a las columnas de las tablas que la consulta puede leer, con qualify de sqlglot, que lanza un error para una columna que no puede ubicar.

Aquí la guarda la rechaza con column: Unknown column: country. El mensaje después enumera las columnas de analytics.fct_orders, analytics.dim_date, que el modelo necesita para corregir la consulta. Ejecutada tal cual, la consulta habría fallado en DuckDB con Binder Error: Table "d" does not have a column named "country".

SELECT 1; DROP TABLE analytics.fct_orders son dos sentencias, Select, Drop, así que la guarda acepta exactamente una.

Una consulta a la que le falta un paréntesis de cierre lanza el ParseError de sqlglot, cuya lista errors da los campos de cada problema, col, description, end_context, highlight, into_expression, line, start_context. Para la consulta mal formada del ejemplo, la descripción es Expecting ), en la línea 1, columna 39. La guarda pasa esos datos al modelo, tal como los usa la sección de reparación.

Regla práctica: Analiza el SQL del agente en un árbol antes de que se ejecute nada, en el dialecto del almacén que lo ejecutará, y acepta exactamente una sentencia. Comprueba nodos, nunca texto. Trata una consulta que se analiza como una consulta cuya forma ya puedes inspeccionar, no como una consulta válida, y resuelve sus columnas frente a las tablas que puede leer antes de enviarla al almacén.

Permitir solo consultas de solo lectura sobre tablas conocidas

Último cambio en la edición 2026.11.12

Con el SQL del agente analizado en un árbol, el guardián puede hacerle dos preguntas: ¿solo lee?, y ¿solo lee lo que le está permitido? Revisar la sentencia de la raíz no basta. En DuckDB, una expresión de tabla común, una CTE, puede contener un DELETE con RETURNING dentro de un SELECT. Por eso el guardián acepta solo una consulta en la raíz, recorre luego cada nodo del árbol y rechaza cualquier sentencia que escriba, cambie configuraciones o llegue a algo fuera del almacén.

Una consulta hostil, enviada a través del guardián y directamente a la base de datos de solo lectura del agente, y también a una copia escribible de la tienda en una carpeta temporal, muestra lo que haría una escritura. Su CTE borra cada reembolso de más de 50 euros, y su SELECT externo los cuenta.

block-a-delete.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""A DELETE hidden in a CTE: the root says SELECT, the tree walk finds the DELETE, and the read-only warehouse refuses it.The attack runs for real only on a throwaway copy of the shop, built from the same seed in a temporary folder."""import tempfilefrom pathlib import Pathimport duckdbimport sqlglotfrom sqlglot import expfrom lib.sql_guard import GuardError, SqlGuardfrom lib.warehouse import agent_warehouse, build, connectATTACK = """WITH gone AS (DELETE FROM analytics.fct_refunds WHERE amount_eur > 50 RETURNING refund_id)SELECT count(*) AS refunds_over_50 FROM gone"""tree = sqlglot.parse_one(ATTACK, read="duckdb")print("root:", type(tree).__name__)print("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 rootagent = agent_warehouse(connect())                      # the agent's read-only databasetry:    SqlGuard(agent).run(ATTACK)except GuardError as e:    print(f"guard refuses ({e.kind}): {e}")try:    agent.execute(ATTACK)                                 # past the guard, straight to the read-only databaseexcept duckdb.Error as e:    print("read-only database:", str(e).splitlines()[0])with tempfile.TemporaryDirectory() as folder:             # a writable copy, deleted when the block ends    path = Path(folder) / "shop.duckdb"    build(path)    with duckdb.connect(str(path)) as writable:        (before,), = writable.execute("SELECT count(*) FROM analytics.fct_refunds").fetchall()        (answer,), = writable.execute(ATTACK).fetchall()        (after,), = writable.execute("SELECT count(*) FROM analytics.fct_refunds").fetchall()print("writable copy, refunds before:", before)print("writable copy, the query's answer:", answer)print("writable copy, refunds after:", after)
Salidapython block-a-delete.py
root: 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

La raíz es un Select, así que una revisión de la raíz la dejaría pasar. El recorrido encuentra Select, Delete, y el guardián la rechaza. La base de datos de solo lectura también la rechaza, y su mensaje indica que vio la sentencia como un SELECT.

En la copia escribible, la consulta devolvió 931, un recuento verosímil de reembolsos, y analytics.fct_refunds pasó de 1068 filas a 137. Nada en la respuesta indica que se borraron filas. La base de datos de solo lectura es lo que lo hace imposible; la revisión del análisis lo convierte en un rechazo que el modelo puede leer.

La segunda pregunta es qué tablas. La base de datos del agente ya deja fuera raw y analytics.orders_legacy, la definición antigua de ingresos sobre la que advertía el capítulo 2. El guardián revisa la misma lista también en el analizador, porque su rechazo nombra las tablas que necesita una reparación, y porque debe rechazar el catálogo de DuckDB. La lista permitida es cada tabla de la base de datos del agente, leída con allowed_schema() junto con las columnas de cada tabla, y ese mismo mapeo es el esquema contra el que qualify resuelve las columnas. La lista permitida es una comprobación propia, porque qualify no comprueba que una tabla exista.

Un nombre sin esquema puede nombrar una CTE, que solo es visible en la consulta cuyo WITH la define, en las subconsultas de esa consulta y en las CTE posteriores dentro del mismo WITH. El refers_to_cte() del guardián sigue esas reglas y rechaza cualquier otro nombre sin esquema. Para probar la lista permitida, el ejemplo intenta seis formas de eludirla, la última una CTE con el nombre del catálogo de DuckDB, y luego ejecuta el SQL de referencia de cada pregunta de referencia a través del guardián.

block-raw-tables.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""The table allowlist: the marts the agent may read, six ways around it that the guard refuses, and the two goldenqueries it can't answer. The last two lines are the cost the prose describes."""from lib.golden import load_goldenfrom lib.sql_guard import GuardError, SqlGuardfrom lib.warehouse import agent_warehouse, connectcon = agent_warehouse(connect())          # the agent's database: copies of the allowed marts, nothing elseguard = SqlGuard(con)                     # allowlist: the tables in it, read with their columnsprint("allowed tables:", ", ".join(f"{db}.{t}" for db, tables in guard.schema.items() for t in tables))ATTEMPTS = {    "raw table": "SELECT count(*) AS customers FROM raw.customers",    "legacy mart": "SELECT sum(revenue) AS revenue FROM analytics.orders_legacy",    "no schema": "SELECT count(*) AS orders FROM fct_orders",    "file as a table": "SELECT * FROM 'data/golden/questions.toml'",    "table function": "SELECT * FROM read_csv('data/golden/questions.toml')",    "CTE named like the catalog": """SELECT * FROM (WITH duckdb_tables AS (SELECT 1 AS x) SELECT x FROM duckdb_tables) AS a,duckdb_tables""",}for label, sql in ATTEMPTS.items():    try:        guard.check(sql)        print(f"{label}: allowed")    except GuardError as e:        print(f"{label}: refused ({e.kind}), {str(e).split(';')[0]}")   # the message's first clausegolden = [q for q in load_golden() if q.golden_sql]outside = []for q in golden:    try:        guard.check(q.golden_sql)    except GuardError as e:        outside.append(f"{q.question_id} ({str(e).split(' ')[0]})")   # the message starts with the table it refusedprint(f"golden queries the allowlist refuses: {len(outside)} of {len(golden)}")print("refused golden queries:", ", ".join(outside))
Salidapython block-raw-tables.py
allowed 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)

Las seis son rechazadas, y tres de ellas no son nombres de tabla. Una ruta de archivo en la cláusula FROM se analiza como una tabla con el nombre de la ruta, así que la lista la rechaza. read_csv() se analiza como una función en lugar de una tabla, y el guardián rechaza cualquier cosa en FROM que no sea una tabla, una subconsulta o una lista de VALUES, lo que también cubre range(), unnest() y query_table(). La CTE llamada duckdb_tables se define dentro de una subconsulta, así que el duckdb_tables posterior nombra la vista de catálogo de DuckDB, y el guardián lo indica: refused (table), duckdb_tables is DuckDB's catalog, not a table you may read. Rechaza todo nombre de catálogo, como los que empiezan por duckdb_ o pg_, y toda función que lea la instancia, como current_setting(). Cualquier otra función debe figurar en ALLOWED_FUNCTIONS, las funciones que necesita el análisis de la tienda.

Las dos últimas líneas muestran lo que cuesta la lista permitida. Rechaza 2 of 34 consultas de referencia: gq-034 (raw.marketing_spend), gq-037 (raw.customers). El gasto en marketing no tiene una tabla de datos preparados, y los registros duplicados solo existen en raw.customers, porque la tabla de datos preparados los eliminó.

Regla práctica: Acepta solo una consulta en la raíz, recorre cada nodo en busca de una sentencia que escriba y pon en la lista permitida las tablas por esquema y nombre, sin nada más que tablas y subconsultas en FROM. Resuelve un nombre sin esquema como CTE solo donde sea visible una CTE de ese nombre, rechaza el catálogo de la base de datos por su nombre y permite solo las funciones que necesita tu análisis. Comprueba la misma lista que mantiene la base de datos del agente. Cuando una pregunta de referencia necesite una tabla que no está en la lista, dale una tabla de datos preparados o una métrica, no una lista más amplia.

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

Bound the rows and the cost

Último cambio en la edición 2026.11.15

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.

explain-before-running.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Bound the rows and the cost: EXPLAIN a join that forgot its keys and refuse it, keep the agent's LIMIT, refuse a resultof every order, and stop the join by timer alone. The printed estimates and limits are the figures the prose quotes."""import sqlglotfrom lib.golden import load_goldenfrom lib.sql_guard import GuardError, SqlGuard, check, explain, run_with_timeoutfrom lib.warehouse import agent_warehouse, connectguard = SqlGuard(con := agent_warehouse(connect()))   # the agent's database, where the guard runs its checksNO_KEYS = """SELECT sum(o.net_revenue_eur) AS net_revenue FROM analytics.fct_orders AS o,analytics.fct_order_lines AS l, analytics.fct_refunds AS r"""KEYED = """SELECT sum(o.net_revenue_eur) AS net_revenue FROM analytics.fct_orders AS oJOIN analytics.fct_order_lines AS l USING (order_id)"""for label, sql in (("no join keys", NO_KEYS), ("joined on order_id", KEYED)):    cost = explain(con, check(sql, guard.schema).sql)    print(f"{label}, largest step: {cost.largest_step}\n{label}, estimated rows: {cost.largest_estimate:,}")   # one per querytry:    guard.check(NO_KEYS)except GuardError as e:    print(f"guard refuses ({e.kind}): {e}")costs = {q.question_id: explain(con, check(q.golden_sql, guard.schema).sql)         for q in load_golden() if q.golden_sql and q.question_id not in ("gq-034", "gq-037")}   # both need tables off the listprint("golden queries estimated:", len(costs))print(f"largest estimate among golden queries: {max(c.largest_estimate for c in costs.values()):,} rows")print("golden plans with a cross product:", ", ".join(i for i, c in costs.items() if c.cross_products))print("golden plans with a step that has no estimate:", sum(1 for c in costs.values() if c.unestimated))print(f"limit on estimated rows: {guard.max_estimated_rows:,}")TOP_FIVE = """SELECT product_id, sum(net_amount_eur) AS net_revenue FROM analytics.fct_order_linesGROUP BY product_id ORDER BY net_revenue DESC LIMIT 5"""print("sqlglot's .limit(1001):", sqlglot.parse_one(TOP_FIVE, read="duckdb").limit(1001).sql("duckdb").split("ORDER BY")[1].strip())   # the text after ORDER BYprint("guard's limit on the top five:", check(TOP_FIVE, guard.schema).limit)try:    guard.run("SELECT order_id, net_revenue_eur FROM analytics.fct_orders")except GuardError as e:    print(f"every order ({e.kind}): {e}")# The join without keys, through the time limit alone, as if the estimate had let it through. It reads its rows in# batches, and DuckDB looks for the timer's interrupt between them.try:    run_with_timeout(con, check(NO_KEYS, guard.schema).sql, seconds=1.0)except GuardError as e:    print(f"no join keys, timer alone ({e.kind}): {e}")print("connection still answers:", con.execute("SELECT count(*) FROM analytics.fct_orders").fetchall()[0][0])
Salidapython explain-before-running.py
no 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 aún no está traducida, así que está en inglés.

Enforce the deadline by killing a process

Último cambio en la edición 2026.11.15

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.

stop-a-slow-plan.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Stop a slow plan: DuckDB computes a constant while it plans, before any row is read, so a timer's interrupt hasnothing to stop; a killed worker stops wherever it is. The prose's claim that the plan never returns and the worker isstopped rests on the assert after the worker's run."""import jsonfrom lib.sql_guard import GuardError, SqlGuard, Worker, checkfrom lib.warehouse import agent_warehouse, connectshop = connect()                                      # chapter 1's connection: constant folding onagent = agent_warehouse(shop)                         # the agent's database: constant folding offguard = SqlGuard(agent, timeout=0.5)SLOW_PLAN = """SELECT count(*) AS n FROM analytics.fct_ordersWHERE order_id < list_sum(list_transform(range(30000000), x -> list_sum(range(40))))"""# Checked as if the function list allowed the list functions, as sqlglot names them (range() is GENERATE_SERIES and# list_transform() is TRANSFORM), so the plan reaches DuckDB.LIST_FUNCTIONS = {"list_sum", "transform", "generate_series"}planned = check(SLOW_PLAN, guard.schema, functions=guard.functions | LIST_FUNCTIONS).sql# The same query with a small constant, 3 lists summing to 6 each: 18, under every order ID. A plan with no rows to# read means DuckDB computed the constant while planning.small = planned.replace("30000000", "3").replace("RANGE(0, 40)", "RANGE(0, 4)")for label, connection in (("shop's connection, folding on", shop), ("agent's database, folding off", agent)):    (_, plan), = connection.execute(f"EXPLAIN (FORMAT json) {small}").fetchall()    steps, nodes = [], json.loads(plan)              # the plan's tree, followed down its first child at each step    while nodes:        steps.append(nodes[0]["name"])        nodes = nodes[0]["children"]    print(f"EXPLAIN with a small constant, {label}: {' > '.join(steps)}")worker = Worker(shop)                                 # a process with its own connection to the shop's filetry:    worker.explain(planned, 0.5)    outcome = "planned"except GuardError as e:    outcome = e.kind                                  # timeout, memory or worker_failed: the machine decides whichprint("EXPLAIN in a worker with a half-second deadline, shop's connection, plan returned:", outcome == "planned")print("EXPLAIN in a worker, still running afterwards:", worker.running)assert outcome != "planned" and not worker.running   # the half-second deadline stops the plan, and the kill leaves no workertry:    guard.run(SLOW_PLAN)except GuardError as e:    print(f"slow plan through the guard ({e.kind}): {e}")
Salidapython stop-a-slow-plan.py
EXPLAIN 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.

Repite los ataques contra el guardia

Último cambio en la edición 2026.11.12

Un primer borrador del guardia confiaba en sus comprobaciones de análisis y en sus límites, en la conexión del capítulo 1, que podía ver todos los esquemas, y un crítico lo superó por el analizador de tres maneras. Un CTE con el nombre de una vista del catálogo devolvió la sentencia CREATE de cada tabla, incluida raw. Una constante evaluada durante la planificación sobrepasó el temporizador. Un producto cartesiano con unnest(range(200000)) pasó el límite de tamaño del plan, porque un paso sin estimación se contaba como pequeño. Cada uno fue un lugar donde el modelo del guardia sobre SQL y la base de datos no coincidían, y la lectura de la base de datos es la que se ejecuta. Dos revisiones de seguridad encontraron más formas de superar el guardia reforzado.

Los intentos de las revisiones y tres más pequeños, repetidos contra cada capa, muestran cuál aguanta. Algunos van directamente a la base de datos del agente, y cada uno pasa por el guardia con su límite de 5 segundos.

replay-guard-bypasses.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""The critics' attempts to get past the guard (lib/guard_attacks.py), replayed on a temporary copy of the marts: what thedatabase alone allows and what the guard does. The asserts back the claims the prose makes without a number."""import duckdbfrom lib.guard_attacks import ALONE, ATTEMPTS, alone, attempt, macro_then_sumfrom lib.sql_guard import SqlGuard, explainfrom lib.warehouse import agent_warehouse, connectagent = agent_warehouse(connect())guard = SqlGuard(agent)                       # the 5-second limit: the queries that run here finish far inside itfor label, sql in ATTEMPTS.items():    if label in ALONE:                        # straight to the agent's database, with no guard in front        print(f"{label}, database alone: {alone(agent, label)}")    print(f"{label}, guard: {attempt(guard.run, sql)[0]}")print("upper-case names, guard:", attempt(guard.run, "SELECT count(*) AS n FROM ANALYTICS.FCT_ORDERS")[0])# A temporary macro named sum, on a cursor of the database alone, then sent straight to the guard's worker.alone_sum, real = macro_then_sum(agent, guard.worker)print("temp macro named sum, database alone, the next sum:", alone_sum)print("temp macro named sum, guard's worker, the next sum is the real one:", real)assert real                                   # the worker's fresh cursor dropped the macro, so the next sum is real# The regex attempt. In-process, a timer's interrupt waits for the end of a batch of rows, and one batch is this much# text. With repeat() and regexp_matches() (sqlglot's REGEXP_LIKE) allowed, the guard's worker runs it under the# review's 2-second limit, and stops it by the deadline or the memory cap, whichever the machine reaches first.REGEX, BATCH = ATTEMPTS["regex on a repeated email"], duckdb.__standard_vector_size__(text,), = agent.execute(f"SELECT sum(length(email)) * 200000 FROM (SELECT email FROM analytics.dim_customers "                         f"ORDER BY customer_id LIMIT {BATCH})").fetchall()print(f"regex, characters to match in one batch of {BATCH:,} rows: {text:,}")wider = SqlGuard(agent, timeout=2.0, functions=guard.functions | {"repeat", "regexp_like"})print("regex, guard without the function list:", attempt(wider.run, REGEX)[1])print("regex, worker still running afterwards:", wider.worker_running)assert not wider.worker_running                # the worker is gone, however it was stoppedprint("regex, the guard's next query:", attempt(wider.run, "SELECT count(*) AS n FROM analytics.fct_orders")[0])# The inequality join ran. Its estimate varies a little between runs, so only its size is printed.JOIN = ATTEMPTS["join on inequality"]estimate, joined = explain(agent, JOIN).largest_estimate, guard.run(JOIN).rows[0][0]   # the count is the only row and columnprint("join on inequality, estimate under the limit:", estimate < guard.max_estimated_rows)print(f"join on inequality, rows it joined: {joined:,}")print("join on inequality, rows joined more than 100 times the estimate:", joined > 100 * estimate)assert estimate < guard.max_estimated_rows and joined > 100 * estimate   # under the limit, yet far more rows than estimated
Salidapython replay-guard-bypasses.py
CTE 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 intento, salvo la unión, es rechazado. El CTE llamado duckdb_tables, enviado solo a la base de datos del agente, devuelve 7 rows, one per table, all in analytics: True: el catálogo no puede mostrar al agente una tabla que no le está permitido leer, porque no hay ninguna. El plan lento y unnest() son rechazados como funciones fuera de la lista, como en refused (function), list_sum() isn't a function the guard allows. Una fila con el nombre y el correo de cada cliente, 1 row of 106,670 characters, es rechazada por ser demasiado grande.

El primer intento de la segunda revisión compara un patrón con el correo de cada cliente repetido 200,000 veces. Superó el analizador y el límite del plan, y superó en duración a una interrupción, que DuckDB comprueba solo entre lotes de filas; un lote aquí contiene 10,649,600,000 caracteres. La lista de funciones ahora lo rechaza: refused (function), regexp_matches() isn't a function the guard allows. Ejecutado con repeat() y regexp_matches() permitidos, con el límite de 2 segundos de la revisión, es stopped, no answer, detenido por el plazo o por el límite de memoria del proceso trabajador, lo que ocurra primero. El trabajador también se detiene, y la siguiente consulta del guardia ran.

current_database() y version(), que por sí solos devuelven agent, v2.0.0, habían pasado; el guardia ahora comprueba cada función. Seiscientas subconsultas anidadas, que hacían fallar al analizador de sqlglot, ahora son rechazadas: refused (parse), the SQL is nested too deeply to check (the limit is 200 levels).

Una última revisión añadió dos más. El guardia ahora rechaza SIMILAR TO, una expresión regular como operador: refused (function), SIMILAR TO isn't an operator the guard allows. Una macro temporal llamada sum, que solo la base de datos acepta, hace que la siguiente suma sea 42. El analizador rechaza la macro, y si hubiera pasado, el trabajador, que inicia cada consulta con un cursor nuevo, la eliminaría, así que la siguiente suma es la real.

El último intento une pedidos con cada cliente que no los realizó, y se ejecutó, como permiten las reglas. Su estimación estaba por debajo del límite, y unió 45,147,384 filas, más de 100 veces la estimación. Así, el límite del plan solo detecta los errores para los que fue fijado. La terminación forzada del proceso, los límites de resultados y el límite de memoria acotan el resto, y la sección de producción enumera lo que queda.

Regla práctica: Confía en los límites de la base de datos y trata el analizador como defensa en profundidad. Guarda cada ataque que alguien encuentre como una prueba: repítelo contra la base de datos del agente sola y a través del guardia, y comprueba que cada uno es rechazado por la capa que esperas. Cuando un ataque supere el analizador, pregúntate primero por qué la base de datos le permitió llegar a algo, y solo después corrige el analizador.

Repara una vez a partir del error

Último cambio en la edición 2026.11.12

Reparar significa darle al modelo, una sola vez, el rechazo del guardián o el error del almacén, y ejecutar lo que escriba a continuación. La investigación indica cuándo la reparación ayuda. El Refiner de MAC-SQL, que corrige el SQL a partir del mensaje de error, añadió 4.6 puntos en el conjunto de desarrollo de BIRD con GPT-4 (Wang et al., Tabla 3). Reparar sin una señal externa es más débil: los modelos "tienen dificultades para corregir sus propias respuestas sin retroalimentación externa" (Huang et al.), y en DIN-SQL un prompt que le indicaba a GPT-4 que su SQL tenía errores bajó su puntuación en Spider de 73.3 a 70.0 (Pourreza y Rafiei, Tabla 5). Por eso el guardián repara solo con una señal externa, su propia negativa o el error de DuckDB, y el prompt de reparación pide una corrección solo cuando el mensaje muestra cómo hacerla.

El prompt de reparación es GUARD_REPAIR en lib/prompts.py: la respuesta del propio modelo, el mensaje y la instrucción de responder con SQL corregido o con una línea que empiece por cannot answer:. answer_with_repair() en lib/sql_guard.py lo ejecuta como máximo una vez por pregunta. El registro guarded-sql-runs contiene solo las llamadas de reparación, hechas con el modelo fijado del libro, Qwen3-4B-Instruct-2507 en un archivo de 4 bits, elegido como explica el capítulo 1. Cada primera respuesta se reproduce desde el registro solo de esquema del capítulo 1 o desde el registro por capas del capítulo 4, y el modelo solo se llamó donde el guardián rechazó esa respuesta o DuckDB falló: 6 veces para el SQL solo de esquema y 1 para el SQL por capas en el conjunto de desarrollo. La misma ejecución reparó las respuestas del conjunto de prueba, que usa la sección de la cola larga. Puntuar las reparaciones por separado muestra si ayudan: el ejemplo puntúa ambos tipos de primera respuesta en las 17 preguntas de respuesta del conjunto de desarrollo, e imprime completas dos reparaciones: la ejecución por capas para gq-017 de la sección de análisis, y la ejecución solo de esquema para gq-001, los ingresos netos del año fiscal 2026.

repair-from-error.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Repair once from the guard's message: how often one repair turns a refusal into an answer on the dev split, and tworepairs in full. The counts are the figures the prose quotes; the repaired SQL is printed for the reader to check."""from collections import Counterfrom lib.context import LAYERS, build_contextfrom lib.golden import golden_result, grade, load_goldenfrom lib.model import RecordedModelsfrom lib.prompts import layered_sql_messages, schema_only_messagesfrom lib.sql_guard import SqlGuard, answer_with_repairfrom lib.warehouse import agent_warehouse, connect, describe_schemacon = connect()guard, schema = SqlGuard(agent_warehouse(con)), describe_schema(con)# First replies from chapters 1 and 4's recordings; each repair reply from this chapter's.model = RecordedModels("schema-only-sql", "context-layers", "guarded-sql-runs")MESSAGES = {"schema-only": lambda q: schema_only_messages(schema, q.question),            "layered": lambda q: layered_sql_messages(build_context(con, q.question, LAYERS).text, q.question)}dev = [q for q in load_golden() if q.split == "dev" and q.kind == "answer"]shown = {}for context, messages in MESSAGES.items():    counts = Counter()    for q in dev:        run = answer_with_repair(guard, model, messages(q), q.question, role=q.role, repairs=1)        outcome = grade(q, run.answer, golden_result(con, q))        when = "after repair" if run.repaired else "first time"        counts[f"ran {when}"] += run.attempts[-1].outcome == "ran"        counts[f"correct {when}"] += outcome == "correct"        counts[f"wrong {when}"] += outcome == "wrong"        counts["refused or failed first"] += run.repaired        counts["declined after repair"] += run.attempts[-1].outcome == "declined"        shown[context, q.question_id] = run    print(f"{context}, questions: {len(dev)}")    for key in ("ran first time", "correct first time", "wrong first time", "refused or failed first",                "ran after repair", "correct after repair", "wrong after repair", "declined after repair"):        print(f"{context}, {key}: {counts[key]}")for context, question_id in (("layered", "gq-017"), ("schema-only", "gq-001")):    run = shown[context, question_id]    print(f"{question_id} {context}, refused: {run.attempts[0].message.split('. The tables')[0]}")   # the refusal, without its list of tables    print(run.attempts[1].sql)                       # attempt 0 is the first reply, attempt 1 the repair    rows = len(run.answer.rows)    print(f"{question_id} {context}, after repair: {run.attempts[1].outcome} and returned {rows} row{'s' * (rows != 1)}")
Salidapython repair-from-error.py
schema-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

La reparación funcionó como mecanismo. Para gq-017, el mensaje del guardián nombró la columna desconocida y listó las columnas de la tabla de pedidos, y el modelo cambió country del calendario a la tabla de pedidos. La consulta reparada ran and returned 10 rows. En el SQL solo de esquema, 5 de las 6 consultas rechazadas o fallidas se ejecutaron tras una reparación.

No hizo correctas las respuestas. El SQL solo de esquema obtuvo 0 respuestas reparadas correctas, y el SQL por capas 0. La gq-017 reparada devuelve todos los países, y la pregunta de referencia la hace el responsable regional de EMEA, que solo debería ver los países de EMEA: una regla que la base de datos propia del responsable aplica y que ningún error de SQL revela.

Para gq-001, el guardián rechazó fiscal_year, que el modelo había buscado en la tabla de pedidos, y la corrección del modelo filtró por el año de calendario de la marca de tiempo UTC. Esa consulta ran and returned 1 row, pero responde a otra pregunta. Mientras tanto, el SQL por capas se ejecutó a la primera en 16 preguntas, con 2 de ellas incorrectas, y la reparación nunca las ve, porque nada falló. En el conjunto de desarrollo de la tienda, la reparación convirtió errores visibles en respuestas que se ejecutan y son incorrectas, más difíciles de detectar que un error.

Regla práctica: Repara como máximo una vez, y solo a partir de una señal externa: la negativa del guardián o el error del almacén, pasados al modelo junto con su propio SQL y un prompt que no suponga que el SQL es incorrecto. Deja que el modelo decline en la reparación. Puntúa las respuestas reparadas por separado de las respuestas a la primera, y si tus preguntas de referencia muestran que rara vez son correctas, declina ante una negativa en lugar de reparar.

Transpilar al dialecto del almacén

Último cambio en la edición 2026.11.12

El almacén de la tienda es DuckDB, y el de la mayoría de los lectores no lo es. El mismo árbol puede escribirse en otro dialecto, como hizo el capítulo 5 con el SQL de la capa semántica. Lo que se transpila es el SQL del guardián, con cada identificador entre comillas. El transpilador de sqlglot traduce lo que conoce y, por defecto, advierte y hace una "traducción de mejor esfuerzo" de lo que no puede traducir. Con unsupported_level=ErrorLevel.RAISE, que transpile() en lib/sql_guard.py utiliza, en cambio lanza un error (sqlglot). Ninguno de los dos casos te indica que el resultado signifique lo mismo en el destino.

Una consulta de cola larga, el ingreso neto por día de la semana y mes en 2025, muestra el problema de las comillas: el ejemplo la escribe para Snowflake dos veces, primero con las comillas del guardián y después sin ellas. Una consulta con el agregado histogram() de DuckDB, que está en la lista de funciones del guardián, muestra qué hace el transpilador con una función que no conoce.

transpile-to-snowflake.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Transpile the guard's SQL to Snowflake: the quoted table name Snowflake reads, a weekday function that answers differently,and a histogram that passes through unchanged. The printed lines are the output the prose quotes."""from lib.sql_guard import SqlGuard, transpilefrom lib.warehouse import agent_warehouse, connectcon = connect()guard = SqlGuard(agent_warehouse(con))WEEKDAYS = """SELECT dayname(order_date_local) AS weekday, strftime(order_date_local, '%Y-%m') AS month,       round(sum(net_revenue_eur), 2) AS net_revenueFROM analytics.fct_ordersWHERE status <> 'cancelled' AND year(order_date_local) = 2025GROUP BY ALL ORDER BY month, weekday"""checked = guard.check(WEEKDAYS)print("kept quoted, Snowflake reads:", transpile(checked.sql, "snowflake", quoted=True).sql.split(" FROM ")[1].split(" WHERE")[0])   # the FROM clause onlysnowflake = transpile(checked.sql, "snowflake", pretty=True)print(snowflake.sql)print("functions passed through unchanged:", ", ".join(snowflake.passed_through) or "none")print("DuckDB's first weekday:", guard.run(WEEKDAYS).rows[0][0])MIX = """SELECT region, histogram(channel) AS orders_by_channel FROM analytics.fct_ordersWHERE year(order_date_local) = 2025 GROUP BY region"""mix = transpile(guard.check(MIX).sql, "snowflake")print("channel mix in Snowflake:", mix.sql.split(" FROM")[0])   # the SELECT list, which holds the functionprint("functions passed through in the channel mix:", ", ".join(mix.passed_through) or "none")
Salidapython transpile-to-snowflake.py
kept 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

Con las comillas, la tabla se convierte en "analytics"."fct_orders" AS "fct_orders". En Snowflake eso nombra otra tabla, porque Snowflake pasa los nombres sin comillas a mayúsculas y trata los nombres entre comillas como sensibles a mayúsculas y minúsculas (Snowflake). Por eso transpile() quita las comillas, salvo que se le pida conservarlas, y la segunda versión queda como analytics.fct_orders. sqlglot reescribió strftime() como TO_CHAR() con el formato de Snowflake, y como conocía todas las funciones de la consulta, none pasó sin cambios.

Aun así, ese resultado limpio cambia la respuesta. dayname() se convirtió en DAYNAME(), y los dos nombres no significan lo mismo. La función dayname() de DuckDB devuelve el nombre en inglés del día de la semana, que aquí es Friday, mientras que la función de Snowflake devuelve un nombre de día de la semana de tres letras. Las mismas filas reciben etiquetas distintas, así que un resultado de referencia que dice Friday falla en Snowflake. La mezcla de canales es el otro fallo: histogram es una función que sqlglot no conoce, así que se escribió sin cambios, SELECT fct_orders.region AS region, HISTOGRAM(fct_orders.channel) AS orders_by_channel, sin ningún error. transpile() enumera funciones de este tipo, aquí histogram, para que las rechaces o las verifiques a mano.

Regla práctica: Deja que el agente escriba en el dialecto en que se comprueban tus preguntas de referencia, pasa ese SQL por el guardián y transpila la salida del guardián, no el texto del agente, con errores para lo que el transpilador sabe que no puede traducir. Quita las comillas del guardián en los almacenes que pasan los nombres sin comillas a mayúsculas, rechaza las funciones que el transpilador dejó pasar sin cambios y ejecuta las preguntas de referencia en el almacén de destino antes de fiarte de una respuesta transpilada, porque una función con el mismo nombre puede devolver valores distintos.

Cuándo preferir una métrica nueva frente a SQL

Último cambio en la edición 2026.11.12

La base de datos y las salvaguardas hacen que el SQL del agente sea seguro de ejecutar: se limita a las vistas de su rol (la sección sobre las vistas), se acota y se repara una vez. Ninguna de ellas lo hace correcto. Una métrica es correcta por construcción, porque una persona la definió una vez. Por eso, el SQL con salvaguardas sirve para preguntas que se hacen una sola vez, mientras que una pregunta que vuelve una y otra vez, o cuyo número va a un informe, debe convertirse en una métrica. Para distinguir un caso del otro, evalúa la ruta con salvaguardas sobre la cola larga de las preguntas doradas y revisa cada respuesta incorrecta.

La cola larga de la tienda son las diez preguntas de respuesta que ninguna métrica ni dimensión de examples/data/semantic/ cubre, como los pedidos que incluyen una tienda de campaña, la conversión por sesión y los descuentos. 2 de las diez están en la partición de desarrollo (dev) y 8 en la partición de prueba reservada (test). Dos preguntas son muy pocas para evaluarlas, así que el número de la cola larga sale de test. Las salvaguardas y la instrucción de reparación se ajustaron con dev, y nada cambió después de que leyéramos test una sola vez; el capítulo 4 ya evaluó allí las primeras respuestas. Evaluamos primero esa ruta y luego promovemos una pregunta en una copia de su YAML.

long-tail-score.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Guarded SQL on the long tail, the answer questions no metric in the semantic layer covers; then one promoted."""import shutilimport tempfilefrom collections import Counterfrom pathlib import Pathfrom lib.answers import format_valuefrom lib.context import LAYERS, build_contextfrom lib.golden import golden_result, grade, load_golden, results_matchfrom lib.model import RecordedModelsfrom lib.prompts import layered_sql_messagesfrom lib.semantic import SEMANTIC_DIR, MetricRequest, loadfrom lib.sql_guard import SqlGuard, answer_with_repairfrom lib.warehouse import agent_warehouse, connectLONG_TAIL = {"gq-007": "a filter on what an order contains", "gq-016": "customers with an order",             "gq-031": "units per order", "gq-032": "gross margin", "gq-033": "session conversion",             "gq-034": "marketing spend", "gq-036": "one order's refunds", "gq-037": "duplicate sign-ups",             "gq-038": "a weekday dimension", "gq-041": "discount"}con, golden = connect(), {q.question_id: q for q in load_golden()}guard, model = SqlGuard(agent_warehouse(con)), RecordedModels("context-layers", "context-layers-test", "guarded-sql-runs")counts = Counter()for question_id, needs in LONG_TAIL.items():    q = golden[question_id]    run = answer_with_repair(guard, model, layered_sql_messages(build_context(con, q.question, LAYERS).text,                                                                 q.question), q.question, role=q.role)    outcome = grade(q, run.answer, gold := golden_result(con, q))    counts[q.split, outcome] += 1    print(f"{question_id} ({q.split}, {needs}): {outcome}, after {' then '.join(a.outcome for a in run.attempts)}")    if outcome == "wrong":        row = ", ".join(map(format_value, min(run.answer.rows))) if run.answer.rows else "no rows"        print(f"{question_id} first row: {row} (golden: {', '.join(map(format_value, min(gold)))})")print(*(f"long tail questions on {s}: {sum(golden[i].split == s for i in LONG_TAIL)}" for s in ("dev", "test")), sep="\n")for split, outcome in [(s, o) for s in ("dev", "test") for o in ("correct", "wrong", "declined")]:    print(f"long tail {split} {outcome}: {counts[split, outcome]} of {sum(n for (s, _), n in counts.items() if s == split)}")with tempfile.TemporaryDirectory() as folder:        # promote gq-038: one dimension added to a copy of the YAML    shutil.copytree(SEMANTIC_DIR, copy := Path(folder) / "semantic")    with open(copy / "orders.yml", "a") as orders:        orders.write("    - name: weekday\n      type: categorical\n      expr: dayname(order_date_local)\n")    layer = load(copy)answer = layer.query(con, MetricRequest(("net_revenue", "orders"), ("order__weekday",), {"metric_time__year": 2025}))print("gq-038 as a metric request matches golden:", results_match(answer.rows, golden_result(con, golden["gq-038"])))assert results_match(answer.rows, golden_result(con, golden["gq-038"]))   # the promotion gives the golden answer
Salidapython long-tail-score.py
gq-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

En dev, el SQL con salvaguardas acierta 1 of 2; en test, 3 of 8, con 1 of 8 rechazadas. La rechazada es gq-034, el retorno sobre la inversión en marketing: la salvaguarda bloqueó raw.marketing_spend, y en su reparación el modelo respondió que ninguna tabla permitida contiene el gasto, lo cual es correcto. La solución es un mart.

Cada respuesta incorrecta pasó limpiamente por todas las salvaguardas. En gq-007, el modelo cometió los dos errores que el capítulo 4 había identificado: escribió la categoría tents donde la tienda guarda Tents, así que la suma devolvió NULL (golden: 377,497.40), y suma solo las líneas de tiendas de campaña, cuando la pregunta pide los ingresos totales de los pedidos que incluyeron una. En gq-032, el margen bruto, el modelo restó los ingresos netos de los ingresos brutos, lo que da el impuesto, y unió las líneas de pedido por order_id, de modo que cada pedido se cuenta una vez por línea: es el fan-out descrito en el capítulo 2: 773,723.34 (golden: 847,864.71). El límite de tamaño del plan no detecta un fan-out en una clave. En gq-033, dio la conversión como porcentaje, cuando la tienda la informa como fracción: (none), 13.46 (golden: (none), 0.13). En gq-038, los ingresos netos y los pedidos por día de la semana, los ingresos son correctos pero el recuento de pedidos no: Friday, 221,172.11, 822 (golden: Friday, 221,172.11, 869). El modelo dejó fuera del recuento los pedidos cancelados, que la métrica orders de la tienda sí incluye.

gq-038 es la que conviene promover. La tienda define sus dos métricas y solo le falta una dimensión por día de la semana: tres líneas de YAML en el modelo semántico de pedidos, con la expresión dayname(order_date_local). Con ella, la pregunta se convierte en una petición de métrica agrupada por order__weekday en 2025, y eso coincide con el resultado dorado. No es un resultado de la partición reservada: la elegimos a partir del fallo de gq-038 en test. La capa del libro no cambia, así que gq-038 se queda en test; en tu propia capa, muévela a dev. gq-034 y gq-037 necesitan antes un mart, porque el agente, con razón, no puede leer raw. Las búsquedas como gq-036, los reembolsos de un pedido y sus motivos, son lo que el SQL con salvaguardas responde bien.

Regla práctica: Envía una pregunta al SQL con salvaguardas solo cuando ninguna métrica la cubra, y evalúa esa ruta sobre su propia cola larga de preguntas doradas. Promueve una pregunta a la capa semántica cuando se repita, cuando su respuesta vaya a un informe, o cuando el SQL con salvaguardas la falle por una definición, como qué cuenta como pedido. Deja las búsquedas puntuales en la ruta con salvaguardas. Cuando una pregunta necesite una tabla fuera de la lista permitida, construye el mart y su métrica en lugar de ampliar la lista.

Qué sale mal en producción

Último cambio en la edición 2026.11.12

Un control de seguridad que pasó sus pruebas puede seguir fallando en uso, porque el almacén de datos, los roles y las listas de funciones siguen cambiando por debajo, y cada fallo que se describe a continuación viene acompañado del síntoma que lo revela.

Una respuesta incorrecta pasa todos los guardias. La base de datos y los guardias limitan qué lee una consulta y cuánto cuesta, pero no lo que significa su resultado. La corrección basada en la ejecución no puede arreglar un SQL que se ejecuta y es incorrecto, por eso Hong et al. añaden una detección de errores antes de la reparación (Hong et al.), y Chaturvedi et al. guían la corrección con una taxonomía de errores (Chaturvedi et al.). Solo lo notas si evalúas el camino protegido con preguntas de referencia y lees respuestas cuyo resultado está vacío, es NULL o es un porcentaje donde esperabas una fracción.

La conexión del agente está por encima de las vistas. El límite solo se mantiene si el usuario del almacén que usa el agente no puede leer las tablas que hay bajo sus vistas. Revisa sus permisos cada vez que cambien los roles del almacén.

La vista de un rol es incorrecta o está desactualizada. Una vista devuelve lo que dice su definición, así que un filtro de filas o una máscara que falte filtra datos en todos los caminos a la vez. En DuckDB, la base de datos de cada rol es una copia hecha en el momento de construirla, por lo que debe reconstruirse cuando cambien los marts. Genera las vistas a partir de una sola política, prueba cada rol con consultas que el analizador acepte, y nombra cada tabla una por una, de modo que un mart nuevo quede excluido hasta que alguien lo añada.

Las listas de funciones y de catálogos son juicios. Una función que necesitan los analistas puede faltar, una que está en la lista puede seguir siendo lenta, y una función nueva del catálogo de DuckDB puede quedar fuera de la lista. Registra cada rechazo por function y revisa ambas listas con cada versión de DuckDB.

El guardia rechaza SQL correcto. El guardia rechaza sintaxis de DuckDB que sqlglot no puede modelar. Registra cada rechazo con su tipo y ejecuta cada consulta de referencia por el guardia en CI, como lo hace la sección de lista de permitidos.

Una estimación no es un coste. La repetición muestra una unión que produjo más de 100 veces su estimación. Registra la estimación de cada consulta junto a su tiempo de ejecución.

Una base de datos de solo lectura sigue guardando estado. Una conexión de DuckDB de solo lectura acepta tablas temporales, vistas, macros y variables, así que una sentencia que supere el analizador podría alterar respuestas posteriores, como muestra la macro de la repetición. El trabajador da a cada consulta un cursor nuevo; haz lo mismo en cualquier grupo de conexiones compartido.

El límite de memoria de DuckDB no cubre todos los valores. Solo «se aplica al gestor de búfers» (DuckDB), así que las cadenas que construye una expresión escapan a su 1 GB. El trabajador limita su propio proceso a 1.5 GB por encima de su tamaño una vez abierta la base de datos. Un trabajador que se queda sin memoria, muere o nunca arranca lanza GuardError (memory o worker_failed) y no devuelve filas: el guardia falla de forma segura (rechaza por defecto). Las comprobaciones de análisis se ejecutan en el propio proceso del guardia, limitadas solo por el límite de 20,000 caracteres y el tope de profundidad. Dale a cada ejecución del agente su propio guardia, porque un trabajador responde a una consulta a la vez.

El propio límite del almacén está lejos. El STATEMENT_TIMEOUT_IN_SECONDS de Snowflake tiene por defecto «172800 (2 days)» (Snowflake). Establece el límite de tiempo del agente en el guardia y, además, un límite menor en el rol de almacén del agente.

La reparación oculta errores. En el conjunto de desarrollo de la tienda, cada consulta reparada que se ejecutó era incorrecta. Registra los intentos junto a cada respuesta, como lo hace answer_with_repair() en su GuardedRun, y cuenta las respuestas reparadas en cada evaluación.

Los mensajes del guardia describen la base de datos. Un rechazo enumera las tablas permitidas y sus columnas. Construye el guardia sobre la base de datos del propio rol, para que liste solo lo que el rol puede ver.

Regla práctica: Trata la base de datos de vistas de solo lectura del rol como el control, y el guardia como una capa que convierte los errores en rechazos y limita el coste. Revisa los permisos del agente y prueba las vistas de cada rol, ejecuta cada consulta de referencia por el guardia en CI, establece el límite de tiempo en el guardia y en el almacén, registra cada rechazo, estimación y reparación junto a su respuesta, y evalúa el camino con su propia cola larga de preguntas de referencia después de cada cambio.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.12
  • El SQL protegido es la alternativa, no el valor por defecto, para las preguntas que ninguna métrica cubre, escrito con las cuatro capas de contexto del capítulo 4.
  • La base de datos es el límite de seguridad. El SQL del agente se ejecuta en modo solo lectura sobre agent_warehouse(): un archivo que contiene los siete data marts permitidos o, si existe una política por rol, las vistas de ese rol sobre ellos. En un almacén con roles, eso significa un rol de solo lectura con SELECT sobre vistas seguras, o políticas de acceso a filas y de enmascaramiento.
  • El analizador, el temporizador y la comprobación de costo son una capa didáctica y de defensa en profundidad, no el límite.
  • Lo que se ejecuta es el SQL del guardián, analizado y regenerado por sqlglot, con todas las columnas calificadas y un límite de filas añadido: una sola sentencia, una consulta en la raíz y ninguna sentencia de escritura en todo el árbol.
  • La lista de permitidos son las tablas de la base de datos, nombradas una por una, con los nombres de CTE resueltos por alcance, el catálogo de DuckDB rechazado, solo las funciones listadas permitidas, SIMILAR TO y GLOB rechazados, el anidamiento limitado y nada más que tablas y subconsultas en FROM. Dos preguntas de oro no pueden responderse dentro de ella.
  • Cuatro límites para cada consulta: como máximo 1,000 filas y 50,000 caracteres, rechazando la consulta en lugar de cortarla; un plan cuyo paso más grande EXPLAIN estima en no más de 10 millones de filas, como regla práctica, sin ningún paso sin estimar; y un único plazo de 5 segundos sobre las comprobaciones, el plan y la ejecución, aplicado terminando el proceso trabajador, que ejecuta cada consulta con un cursor nuevo.
  • Una reparación, a partir del rechazo del guardián o del error de DuckDB, con un prompt que permite al modelo negarse a responder. Las respuestas reparadas se evalúan por separado.
  • Transpilar la salida del guardián, sin sus comillas, lanzando un error ante lo que sqlglot no puede traducir y listando las funciones que pasó sin cambios.
  • Promover una pregunta a métrica cuando se repite, cuando su cifra se reporta o cuando el SQL protegido obtiene mal su definición.

Este capítulo, en esta edición

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

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

Cita esta sección

Formato

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

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

En esta página

Capítulo 7 de 11: Let the agent write SQL inside guards

  1. Dale al agente una base de datos con solo lo que puede leer
  2. Give each role a database of views
  3. Analiza el SQL antes de ejecutarlo
  4. Permitir solo consultas de solo lectura sobre tablas conocidas
  5. Bound the rows and the cost
  6. Enforce the deadline by killing a process
  7. Repite los ataques contra el guardia
  8. Repara una vez a partir del error
  9. Transpilar al dialecto del almacén
  10. Cuándo preferir una métrica nueva frente a SQL
  11. Qué sale mal en producción
  12. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos