Enruta las preguntas primero a métricas gobernadas

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

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

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

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

Al final de este capítulo, podrás darle al agente las métricas de la capa semántica como herramientas en lugar de las tablas del almacén de datos; hacer que devuelva una solicitud de métrica estructurada que se valida antes de ejecutar nada; hacer que te pregunte de vuelta cuando una pregunta pueda referirse a varias métricas; y medir el cambio en las preguntas doradas.

El capítulo 5 dejó por escrito las definiciones de la tienda una sola vez, como una capa semántica: diez métricas sobre cinco modelos semánticos, compiladas a SQL por el compilador propio del libro en lib/semantic.py. Una persona que conoce la capa puede pedirle los ingresos netos por región en marzo de 2026 y obtener la cifra del equipo de finanzas. El agente todavía no puede hacerlo. El capítulo 1 le dio una sola métrica, y la línea base que debe superar es el SQL basado solo en el esquema, que acierta 2 of 24 preguntas de desarrollo. El capítulo 4 le dio al modelo sus definiciones como texto junto al esquema, pero el modelo seguía escribiendo el SQL, así que cada definición tenía que sobrevivir a su interpretación.

Cuando el modelo escribe la consulta, cualquier definición que malinterprete acaba en el número. Enrutar una pregunta primero a métricas gobernadas significa quitarle al modelo la escritura de la consulta: su tarea se reduce a elegir qué métrica, agrupada por qué, filtrada cómo, y la capa, que las personas poseen y prueban, escribe el SQL. Los proveedores de almacenes de datos describen sus propios asistentes de la misma manera. La guía de Databricks para sus Genie Agents, que responden preguntas, dice que las vistas de métricas funcionan especialmente bien con ellos porque predefinen métricas, dimensiones y agregaciones (Databricks), y Snowflake recomienda las vistas semánticas para Cortex Analyst (Snowflake). Al igual que los consejos de los proveedores del capítulo 4, estas son recomendaciones, no mediciones. Este capítulo mide el patrón con las preguntas doradas de la tienda, con el mismo modelo grabado que los demás capítulos.

Dale al agente métricas, no tablas

Último cambio en la edición 2026.11.12

Las herramientas de un agente determinan en qué puede equivocarse. Si se le dan tablas, un modelo puede unirlas de forma incorrecta, omitir un filtro o elegir el data mart heredado, como el capítulo 2 mostró un fallo a la vez. Si se le dan métricas, aún puede elegir mal la métrica o la dimensión, pero no puede reescribir una definición, porque las definiciones no están entre las cosas que puede tocar. Una herramienta de métricas expone lo que contiene una capa semántica con la forma en que una persona la pide: los nombres de las métricas con sus descripciones, las dimensiones por las que cada una puede agruparse y filtrarse, y las granularidades temporales. Databricks describe sus vistas de métricas de Unity Catalog en los mismos términos, como una separación de "las definiciones de medidas de los campos (también llamados dimensiones) usados para agrupar, filtrar y agregarlas" (Databricks).

El agente de la tienda obtiene sus herramientas de métricas de lib/metric_tools.py, un módulo que este capítulo añade. Su MetricToolbox envuelve una conexión al almacén de datos y la capa semántica del capítulo 5, y ofrece cinco herramientas: list_metrics, describe_metric, query_metric, ask_back y cannot_answer. El prompt, METRICS_FIRST en lib/prompts.py, incluye lo que devuelve list_metrics, de modo que el modelo no gasta una llamada para pedirlo: una línea por métrica, con su descripción y las dimensiones que puede usar. El prompt también indica cómo funciona el año fiscal de la tienda y cómo escribir un periodo como valor de filtro, y nombra las regiones y los canales de venta. No enumera tablas ni columnas.

Veamos primero lo que ve el agente. El ejemplo construye el prompt e imprime la línea de los ingresos netos en el catálogo, luego llama a describe_metric para la tasa de devoluciones, y mide una pregunta dorada, gq-002, los ingresos netos por región en marzo de 2026, con el prompt de solo esquema del capítulo 1 y con este. Ambos tamaños son los recuentos de tokens que informó el entorno de ejecución del modelo cuando se registraron las llamadas.

metric-tools.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Give the agent the semantic layer's metrics instead of the warehouse's tables, and compare what each prompt holds.The prose rests on the metric and table counts and the two prompt token counts, which come from the recordings."""from lib.golden import load_goldenfrom lib.metric_tools import MetricToolbox, catalogfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_prompt, schema_only_messagesfrom lib.warehouse import connect, describe_schemacon = connect()toolbox = MetricToolbox(con)system = metrics_first_prompt(catalog(toolbox.layer))print(f"tools: {', '.join(toolbox.tools)}")print(f"metrics in the prompt: {len(toolbox.layer.metrics)}")print(f"tables in the prompt: {system.count('CREATE TABLE')}")       # a table in the prompt would be written as a CREATE TABLE statementprint(catalog(toolbox.layer).splitlines()[0])                          # the first line: net revenue, with its dimensionsprint(toolbox.call("describe_metric", {"metric": "refund_rate"}).content)# The first call of the same golden question, gq-002, under each prompt, as the recordings measured it.question = next(q for q in load_golden() if q.question_id == "gq-002").questionschema_only = schema_only_messages(describe_schema(con), question)metrics_first = [{"role": "system", "content": system}, {"role": "user", "content": question}]print(f"schema-only prompt tokens: {RecordedModel('schema-only-sql').call_for(schema_only)['prompt_tokens']}")print(f"metrics-first prompt tokens: {RecordedModel('metric-agent-runs').call_for(metrics_first)['prompt_tokens']}")
Salidapython metric-tools.py
tools: list_metrics, describe_metric, query_metric, ask_back, cannot_answer
metrics in the prompt: 10
tables in the prompt: 0
- net_revenue: Revenue in EUR after discounts and before tax, from real orders that weren't cancelled, counted on the order's local business day. Returned orders count; refunds are not subtracted. Dimensions: customer__country, customer__first_order_date, customer__region, order__channel, order__country, order__order_date, order__region, order__status
refund_rate, a ratio metric: Refunded EUR over gross revenue of the same orders: orders placed in the period that weren't cancelled.
Dimensions:
- metric_time__day
- metric_time__week
- metric_time__month
- metric_time__quarter
- metric_time__year
- metric_time__fiscal_year: 2025, 2026, 2027
- metric_time__fiscal_quarter: 2025-Q1, 2025-Q2, 2025-Q3, 2025-Q4, 2026-Q1, 2026-Q2, 2026-Q3, 2026-Q4, 2027-Q1, 2027-Q2
- order__channel: (none), app, marketplace, web
- order__country: AU, CA, DE, ES, FR, GB, JP, NL, SG, US
- order__order_date
- order__region: AMER, APAC, EMEA
- order__status: cancelled, delivered, placed, returned, shipped
schema-only prompt tokens: 827
metrics-first prompt tokens: 1120

El prompt enumera 10 métricas y 0 tablas. La línea de cada métrica es la descripción de su propietario, palabra por palabra del YAML, seguida de las dimensiones a las que puede llegar sin duplicación. La línea de los ingresos netos nombra order__region y customer__region, pero no product__category, porque el modelo de pedidos llega a los productos solo a través de las líneas de pedido, varias por pedido.

describe_metric añade lo que el catálogo omite: las granularidades temporales y los valores de cada dimensión categórica, leídos del almacén de datos cuando se ejecuta la herramienta. Las regiones de la tasa de devoluciones son AMER, APAC y EMEA, y sus trimestres fiscales son etiquetas como 2026-Q1. El prompt ya nombra las regiones y los canales, así que para esos valores la herramienta repite lo que ya se le dijo al modelo. Para los países, los estados de los pedidos y los periodos fiscales, es el único lugar donde el modelo ve cómo los escribe la tienda.

El prompt basado en métricas no es más pequeño. Son 1120 tokens frente a los 827 del prompt de solo esquema, porque una definición requiere más palabras que un nombre de columna. Lo que cambió es lo que contienen los tokens: reglas que una persona escribió y comprobó, en lugar de nombres que el modelo tiene que interpretar.

Regla práctica: Dale al agente las métricas, sus descripciones y las dimensiones que puede usar cada una, y mantén las tablas fuera de sus herramientas hasta que una pregunta las necesite. Incluye el catálogo en el prompt mientras quepa, para que una ejecución no gaste una llamada listando métricas, y deja que una herramienta de descripción devuelva los valores de las dimensiones desde el almacén de datos. Cuando el catálogo supere el prompt, mantén en él los nombres y las descripciones y traslada las dimensiones detrás de la herramienta de descripción.

Pide una solicitud, no SQL

Último cambio en la edición 2026.11.12

Con herramientas de métricas en su lugar, la respuesta del modelo ya no es una consulta sino una solicitud. Una respuesta estructurada es aquella que el código puede interpretar como un objeto tipado y verificar campo por campo. Aquí es una llamada a herramienta en JSON cuyos argumentos se convierten en un MetricRequest, la solicitud de métrica del capítulo 5, que nombra métricas, dimensiones de agrupación, filtros, un orden y un límite. Nada en ella es SQL, así que el modelo no puede añadir nada a una consulta que la capa no haya definido.

La plantilla de chat de Qwen para el modelo con el que este libro hace sus grabaciones pide cada llamada a herramienta como JSON dentro de etiquetas <tool_call>, y devuelve los resultados de las herramientas dentro de etiquetas <tool_response> (plantilla de Qwen). La tarjeta del modelo de Qwen recomienda su biblioteca Qwen-Agent, que "encapsula internamente las plantillas de llamadas a herramientas y los analizadores de llamadas a herramientas" (tarjeta del modelo). En cambio, mantenemos el formato propio del libro: el prompt pide un único objeto JSON sin adornos, {"tool": ..., "arguments": ...}, que run_agent() en lib/agent.py interpreta, como lo ha hecho desde el capítulo 1. Un pequeño analizador propio es más fácil de probar que el de una biblioteca, y ninguna nueva versión de biblioteca puede cambiarlo.

El caso de la tienda es la pregunta dorada gq-003, ingresos netos por canal de venta en el año calendario 2025. El SQL solo con esquema falló en el capítulo 1 al filtrar fct_orders por una columna calendar_year que solo existe en dim_date. La grabación metric-agent-runs contiene las respuestas del mismo modelo al prompt de métricas primero para las 48 preguntas doradas. Fue hecha por recordings/record_metrics_first.py con el archivo de modelo fijado, el muestreo recomendado por Qwen y un reinicio de la semilla antes de cada llamada, como todas las grabaciones de este libro. La ejecución de gq-003, reproducida, muestra la respuesta, la solicitud y lo que la capa hizo con ella.

model-returns-a-request.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""The model returns a metric request, not SQL, and the layer compiles that request. The prose rests on the `matches golden`line, which the example asserts; the schema-only outcome shows the baseline's failure on the same question."""from lib.agent import run_agentfrom lib.golden import golden_result, load_golden, results_match, schema_only_outcomefrom lib.metric_tools import MetricToolbox, catalogfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import MetricRequestfrom lib.warehouse import connect, describe_schemacon = connect()toolbox = MetricToolbox(con)system = metrics_first_prompt(catalog(toolbox.layer))question = next(q for q in load_golden() if q.question_id == "gq-003")model = RecordedModel("metric-agent-runs")trace = run_agent(question.question, system, model, toolbox, max_steps=4)     # the chapter's limit of four model calls per runprint(f"question: {question.question}")print(f"model calls: {sum(step.kind == 'model' for step in trace.steps)}")print(f"reply: {trace.steps[0].content}")                                   # step 0 is the model's first reply, before any tool runsprint(MetricRequest.from_arguments(trace.steps[0].arguments))               # the reply's arguments, parsed into the typed requestprint(trace.answer.provenance.sql)                                          # SQL the layer compiled from the request, not SQL the model wroteprint(trace.answer.show())matches = results_match(trace.answer.rows, golden_result(con, question))assert matches, "the layer's answer to gq-003 should match its golden result"   # the request asks gq-003's own question, net revenue by channel for 2025, so its rows are the golden onesprint(f"matches golden: {'yes' if matches else 'no'}")schema = describe_schema(con)print(f"schema-only outcome: {schema_only_outcome(con, RecordedModel('schema-only-sql'), schema, question)}")
Salidapython model-returns-a-request.py
question: How much net revenue did each sales channel bring in during calendar year 2025?
model calls: 1
reply: {"tool": "query_metric", "arguments": {"metrics": ["net_revenue"], "group_by": ["order__channel"], "filters": {"metric_time__year": 2025}}}
MetricRequest(metrics=('net_revenue',), group_by=('order__channel',), filters={'metric_time__year': 2025}, order_by=(), limit=None)
SELECT
  orders.channel AS order__channel,
  SUM(orders.net_revenue_eur) AS net_revenue
FROM analytics.fct_orders AS orders
WHERE
  orders.status <> 'cancelled'
  AND CAST(DATE_TRUNC('YEAR', CAST(orders.order_date_local AS DATE)) AS DATE) = CAST('2025-01-01' AS DATE)
GROUP BY
  orders.channel
ORDER BY
  order__channel ASC
order__channel  net_revenue
(none)          82,922.75
app             431,258.70
marketplace     227,826.99
web             909,519.42
matches golden: yes
schema-only outcome: error

La ejecución necesitó 1 llamada al modelo. La respuesta nombra net_revenue, agrupa por order__channel y filtra metric_time__year a 2025: las tres partes de la pregunta, cada una asignada a un nombre que la capa define. La capa escribió el SQL. Lee analytics.fct_orders, excluye los pedidos cancelados mediante el filtro propio de la métrica, trunca el día hábil local a su año y agrupa por canal, y sus totales por canal coinciden con los dorados. La misma pregunta bajo SQL solo con esquema termina en error.

La solicitud también hace exacta la procedencia de la respuesta. answer.provenance indica la métrica, los filtros y el SQL que se ejecutó, de modo que una persona que dude del número revisa una solicitud breve y la definición de la métrica, no una consulta que escribió el modelo. Revisar una solicitud requiere un vistazo; revisar el SQL de un modelo exige el mismo cuidado que revisar el de cualquier persona.

Regla práctica: Haz que el modelo devuelva una solicitud de métrica como argumentos estructurados de una herramienta, e interprétala como una solicitud tipada antes de que ocurra cualquier otra cosa. Mantén el formato de respuesta lo bastante simple como para que tu propio código lo interprete, y mantén ese analizador en un solo lugar. Acepta SQL de un modelo solo por una ruta separada y protegida, para preguntas que ninguna métrica cubre.

Valida la solicitud contra la capa

Último cambio en la edición 2026.11.12

Una solicitud analizada está bien formada, lo cual no es lo mismo que ser correcta. Algunos errores fallan de forma evidente: el compilador del capítulo 5 rechaza una métrica que no define, y una dimensión que causaría un fan out. Otros compilan y se ejecutan. Un valor de filtro que ninguna fila contiene, como una región llamada Europe, devuelve un total vacío. Un mes escrito contra una dimensión que contiene días coincide con un solo día. Ambos resultados parecen respuestas. Validar una solicitud significa comprobarla contra las definiciones de la capa y contra los valores del almacén antes de compilarla, y devolver al modelo cada problema junto con lo que sería admitido en su lugar.

validate_request() en lib/metric_tools.py hace eso para la tienda. Comprueba el nombre de cada métrica y sugiere los nombres definidos más cercanos para una mal escrita. Comprueba cada dimensión contra lo que las métricas solicitadas pueden alcanzar, y cuando una no puede, indica las métricas que sí pueden. Comprueba cada valor de filtro categórico contra los valores del almacén, cada filtro sobre metric_time contra su granularidad, de modo que un mes deba ser el primer día de un mes, y cada filtro sobre una dimensión de fecha, que debe ser un único día. query_metric lo ejecuta en cada solicitud. Una solicitud con problemas vuelve al modelo como un error que enumera todos los problemas encontrados una vez conocidas las métricas, de modo que una sola corrección puede resolverlos todos. Una métrica desconocida vuelve por sí sola, antes de que se compruebe cualquier otra cosa.

Una persona podría escribir tres solicitudes que la capa rechaza: pedidos por correo electrónico del cliente, que ningún modelo semántico define; ingresos netos por categoría de producto, que causaría un fan out; e ingresos netos para una región llamada Europe. A continuación viene la primera solicitud del propio modelo para gq-002: el código la ejecuta sin validar para mostrar lo que habría ocurrido, y después sigue su solicitud corregida hasta su respuesta.

reject-unknown-dimension.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Validate a metric request against the layer and the warehouse before it runs, and show what would run without it.The prose rests on the unchecked total and the two `matches golden` lines; the example asserts the two matches."""from lib.agent import run_agentfrom lib.golden import golden_result, load_golden, results_matchfrom lib.metric_tools import MetricToolbox, catalog, validate_requestfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import MetricRequestfrom lib.warehouse import connectcon = connect()toolbox = MetricToolbox(con)layer = toolbox.layerfor label, request in [("no such dimension", MetricRequest(("orders",), group_by=("customer__email",))),                       ("fan-out", MetricRequest(("net_revenue",), group_by=("product__category",))),                       ("no such value", MetricRequest(("net_revenue",), filters={"order__region": "Europe"}))]:    print(f"{label}: {validate_request(layer, con, request)[0]}")print(f"unchecked, region Europe: {layer.query(con, request).rows}")           # `request` is still the Europe filter from the loop# The model's own requests for gq-002, net revenue in each region in March 2026, replayed from the recording.question = next(q for q in load_golden() if q.question_id == "gq-002")system = metrics_first_prompt(catalog(layer))trace = run_agent(question.question, system, RecordedModel("metric-agent-runs"), toolbox, max_steps=4)first, second = (MetricRequest.from_arguments(s.arguments) for s in trace.steps if s.tool == "query_metric")   # its two query callsgolden = golden_result(con, question)unchecked = layer.query(con, first)                # what would have run without validationprint(f"first request filters: {first.filters}")print(f"unchecked total: {sum(row[1] for row in unchecked.rows):,.2f}")           # row[1] is the net revenue columnprint(f"golden total: {sum(row[1] for row in golden):,.2f}")unchecked_matches = results_match(unchecked.rows, golden)assert not unchecked_matches, "the unchecked request should miss the golden result"   # a month written against a daily date dimension matches only its first day, so this total can't cover the monthprint(f"unchecked matches golden: {'yes' if unchecked_matches else 'no'}")print(f"validation said: {trace.steps[1].content}")                               # step 1 is the refusal the layer returnedprint(f"second request filters: {second.filters}")matches = results_match(trace.answer.rows, golden)assert matches, "the second request should match the golden result"              # filtering metric_time at the month's grain covers every day in March, the golden question's periodprint(f"matches golden: {'yes' if matches else 'no'}")
Salidapython reject-unknown-dimension.py
no such dimension: orders can't use dimension 'customer__email'; no metric defines it
fan-out: net_revenue can't use dimension 'product__category'; metrics that can use it: line_net_revenue, units_sold
no such value: no row has order__region = 'Europe'; its values: AMER, APAC, EMEA
unchecked, region Europe: ((None,),)
first request filters: {'order__order_date': '2026-03'}
unchecked total: 4,150.82
golden total: 150,082.83
unchecked matches golden: no
validation said: error: request rejected: order__order_date = '2026-03': a date dimension matches single days only; for a period, filter metric_time at its grain, as metric_time__month = "2026-03" or metric_time__year = 2025
second request filters: {'metric_time__month': '2026-03'}
matches golden: yes

Cada una de las tres solicitudes se rechaza con un mensaje que indica qué hacer en su lugar: ninguna métrica define el correo electrónico de un cliente, otras dos métricas pueden alcanzar la categoría de producto, y las regiones son AMER, APAC y EMEA. Sin la comprobación, la solicitud para Europe se ejecuta y devuelve una fila con un total vacío, que un agente informaría como ausencia de ingresos.

La solicitud del propio modelo es el caso que importa, porque ninguna persona la escribió. Para marzo de 2026 filtró order__order_date, la dimensión de fecha diaria de los pedidos, con "2026-03". El compilador interpreta un mes escrito contra una dimensión diaria como el primer día del mes, así que la solicitud sin validar devuelve solo el 1 de marzo: 4,150.82 euros en las tres regiones, frente a un total de referencia de 150,082.83. Nada en esa respuesta indica que cubre un solo día. La validación rechazó el filtro y nombró la dimensión que debe usarse, metric_time__month. La segunda solicitud del modelo la usó, y su respuesta coincide con el resultado de referencia.

En el conjunto de desarrollo, la validación rechazó 10 solicitudes, y 6 ejecuciones llegaron a una respuesta correcta después de un rechazo. La mayoría de esos rechazos se debieron al filtro de fecha. El prompt dice que un mes se escribe como "2026-03" y enumera metric_time__month entre las granularidades, aunque nunca muestra los dos juntos. El modelo, de todos modos, recurrió a order__order_date, probablemente porque el catálogo lo lista junto a la región. Una comprobación en código detecta ese error siempre; una frase en un prompt lo detecta solo cuando el modelo sigue la frase.

Regla práctica: Valida cada solicitud antes de compilarla: los nombres contra la capa, los valores categóricos contra el almacén, las fechas contra su granularidad. Rechaza con un mensaje que nombre las alternativas permitidas, y devuélvelo al modelo, que normalmente puede corregirse en una sola llamada. Trata cualquier solicitud que compilaría en un resultado vacío o parcial como inválida, no como una respuesta de cero.

Pide aclaración cuando una pregunta sea ambigua

Último cambio en la edición 2026.11.12

La validación detecta las solicitudes que la capa no puede atender. No puede detectar una solicitud válida de algo equivocado. "¿Qué región lo está haciendo mejor?" se traduce en una solicitud válida de ingresos netos por región, y del mismo modo en una de pedidos o de tasa de devoluciones por región, y cada una puede señalar una región distinta. Cuando una pregunta encaja con varias métricas y la elección cambia la respuesta, lo correcto es devolver una pregunta, con las opciones explicadas. El conjunto dorado de la tienda marca estas preguntas como rechazos de tipo ambiguous, y el capítulo 3 puntúa como correcta cualquier respuesta a ellas que no devuelva un resultado.

La herramienta ask_back termina la ejecución con una pregunta para la persona y las opciones que propone el modelo. Una opción que nombra una métrica se muestra con la descripción que la capa da de ella, de modo que la persona elige entre definiciones, no entre palabras: los ingresos pasan a ser ingresos en euros después de descuentos y antes de impuestos, de pedidos que no se cancelaron. La respuesta lleva ask_back como su origen en la procedencia, de modo que una puntuación pueda contar las aclaraciones por separado de los rechazos.

Cuatro preguntas de desarrollo deberían terminar en una pregunta de vuelta o en un motivo: dos son ambiguas, gq-019, sobre nuestros mejores clientes, y gq-020, sobre qué región lo está haciendo mejor, y dos no pueden responderse, una previsión y el coste del envío. La última herramienta de cada ejecución se imprime para las cuatro. Después, el código imprime las preguntas que el agente formuló para gq-019 y gq-005, la respuesta que dio para gq-020, y una comprobación que las ejecuciones grabadas no tenían.

clarify-best-customers.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Ask back when a question could mean several metrics: the layer supplies each option's definition to the person.The prose rests on the tool each dev decline ended with and on the ranking check's count of flagged runs."""from lib.agent import run_agentfrom lib.golden import load_goldenfrom lib.metric_tools import MetricToolbox, catalog, unbounded_rankingfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import MetricRequestfrom lib.warehouse import connectcon = connect()toolbox = MetricToolbox(con)system = metrics_first_prompt(catalog(toolbox.layer))model = RecordedModel("metric-agent-runs")traces = {q.question_id: run_agent(q.question, system, model, MetricToolbox(con, toolbox.layer, role=q.role),                                   max_steps=4) for q in load_golden()}for q in load_golden():    if q.split == "dev" and q.kind == "decline":        last = next(s for s in reversed(traces[q.question_id].steps) if s.kind == "model")     # the run's final model reply        print(f"{q.question_id} ({q.decline_type}): {last.tool}")        print(f"  {q.question}")print("gq-019 asks back:")print(traces["gq-019"].answer.reason)print("gq-005 asks back:")print(traces["gq-005"].answer.reason)answered = next(s for s in reversed(traces["gq-020"].steps) if s.tool == "query_metric")   # its last query, the one that ranprint(f"gq-020 request: {answered.arguments}")print(traces["gq-020"].answer.show())# A check the recorded runs didn't have: refuse a request that ranks its result over no period.# Applied here to the last request of every run, dev and test, that returned a result.final = {question_id: MetricRequest.from_arguments(next(s for s in reversed(t.steps) if s.tool == "query_metric")                                                   .arguments)         for question_id, t in traces.items() if t.answer.answered}flagged = [question_id for question_id, request in final.items() if unbounded_ranking(request)]print(f"runs with a result: {len(final)}")print(f"requests that order their result: {sum(bool(r.order_by) for r in final.values())}")   # an empty order_by means no rankingprint(f"ranking check flags: {', '.join(flagged) or 'none'}")print(f"ranking check on gq-020: {unbounded_ranking(final['gq-020'])}")
Salidapython clarify-best-customers.py
gq-005 (unanswerable): ask_back
  What will our net revenue be next quarter?
gq-019 (ambiguous): ask_back
  Who are our best customers?
gq-020 (ambiguous): query_metric
  Which region is doing best?
gq-021 (unanswerable): cannot_answer
  How much did shipping cost us in fiscal year 2026?
gq-019 asks back:
Do you mean customers by highest net revenue, or by highest number of orders?
- net_revenue: Revenue in EUR after discounts and before tax, from real orders that weren't cancelled, counted on the order's local business day. Returned orders count; refunds are not subtracted.
- orders: The number of real orders, cancelled ones included.
gq-005 asks back:
Do you mean net revenue for the next calendar quarter or the next fiscal quarter?
- calendar quarter
- fiscal quarter
gq-020 request: {'metrics': ['net_revenue'], 'group_by': ['customer__region'], 'order_by': ['net_revenue']}
customer__region  net_revenue
APAC              925,657.84
AMER              1,174,510.02
EMEA              1,690,339.73
runs with a result: 31
requests that order their result: 1
ranking check flags: gq-020
ranking check on gq-020: the request ranks its result but names no period; filter or group by a metric_time grain

Para gq-019, el agente preguntó si "mejor" significa los ingresos netos más altos o los pedidos más numerosos, y la capa añadió la definición de cada métrica. Ese es el comportamiento para el que existe la herramienta, y se puntúa como correcto. Aun así, lee las opciones frente a la capa. Ningún modelo semántico tiene una dimensión que identifique a un cliente, así que ninguna de las dos elecciones lleva a una solicitud que la capa pueda atender. La respuesta honesta habría sido un rechazo: las métricas de la tienda no ordenan clientes.

Para gq-020, el agente no preguntó. Solicitó los ingresos netos por customer__region sin periodo, y devolvió los ingresos de todo el tiempo para cada región, del más pequeño al más grande. Cada nombre de la solicitud es válido, así que la validación la dejó pasar, y la puntuación la cuenta como incorrecta. Para la previsión, gq-005, el agente preguntó si "el próximo trimestre" se refería al trimestre natural o al fiscal, una pregunta cuya respuesta no habría servido de nada, ya que ninguna métrica hace previsiones. Se puntúa como correcta porque no devolvió ninguna cifra, y solo la traza muestra que el motivo era erróneo. La pregunta sobre el envío, gq-021, fue rechazada con el motivo correcto.

Así, la herramienta funciona cuando el modelo la llama, y la decisión del modelo sobre cuándo llamarla no es fiable. Una comprobación en código atrapa el caso de gq-020: rechazar una solicitud que ordena su resultado pero no nombra un periodo. unbounded_ranking() en lib/metric_tools.py es esa comprobación, y el ejemplo la aplica a la última solicitud de cada ejecución grabada, de desarrollo y de prueba, que devolvió un resultado. De esas 31, marca gq-020. Eso demuestra que atrapa este caso, no que nunca se equivoque, porque solo 1 de esas solicitudes ordena su resultado. query_metric todavía no ejecuta la comprobación: las grabaciones se hicieron sin ella, así que añadirla exige volver a grabar.

El caso de gq-019 necesita una comprobación que todavía no hemos construido: rechazar una ask_back cuyas opciones de métrica no puedan agrupar por aquello sobre lo que pregunta la cuestión. Para ello haría falta saber sobre qué pregunta la cuestión, aquí un cliente, y nada en el conjunto de herramientas lo sabe. Tampoco cubriría gq-005, cuyas opciones son periodos, no métricas. Ambas comprobaciones son reglas sobre las preguntas de la tienda, y pertenecen al código, donde una prueba puede sostenerlas, en lugar de a más texto en el prompt.

Regla práctica: Da al agente una herramienta para pedir aclaración, con opciones que nombren las métricas de la capa, y muestra a la persona la definición de cada opción. Pide aclaración solo cuando cada opción lleve a una solicitud que la capa pueda responder; cuando ninguna lo haga, rechaza en su lugar. Lee las aclaraciones en las trazas igual que lees los rechazos, porque una puntuación cuenta como correcta una pregunta inútil.

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

Measure metrics-first on the golden questions

Último cambio en la edición 2026.11.15

So far the book has followed single runs. The measurement that counts is the one chapter 3 set up: every golden question, scored by grade() with results_match(), tuned on the dev split and checked once on the held-out test split, beside the schema-only baseline. We recorded the dev split three times while tuning, and two changes came from those runs. The catalog in the prompt stopped printing each metric's type beside its name, because the model copied the type into its requests; describe_metric still prints it. And a year written as text, such as "2025", became the number it can only mean. Only the final dev recording is kept, and the recording's manifest says the two earlier ones were discarded. The dev numbers below were measured on the split the changes were chosen on, so they're optimistic. The test split was recorded once, after those changes, and nothing changed afterwards.

Each run gets at most four model calls. A run that uses all four model calls without an answer is a failure, and grade() scores it as step limit, apart from the declines the model chose. Every run on both splits, for each approach, is replayed and counted by tool: model calls, refused requests, runs that reached a correct answer after a refusal, and clarifications by kind of question.

metrics-first-score.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Score metrics-first against the schema-only baseline on both splits: dev for tuning, test once for the final number.The prose rests on the correct counts per split and on the step-limit lines, which count runs out of model calls."""from collections import Counter, defaultdictfrom lib.agent import run_agentfrom lib.golden import golden_result, grade, load_golden, schema_only_outcomefrom lib.metric_tools import MetricToolbox, catalogfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import loadfrom lib.warehouse import connect, describe_schemacon, layer = connect(), load()schema, system = describe_schema(con), metrics_first_prompt(catalog(layer))agent_model, sql_model = RecordedModel("metric-agent-runs"), RecordedModel("schema-only-sql")counts, facts, missed = defaultdict(Counter), defaultdict(Counter), defaultdict(list)for q in load_golden():    toolbox = MetricToolbox(con, layer, role=q.role)    trace = run_agent(q.question, system, agent_model, toolbox, max_steps=4)      # four calls at most, as in every run    outcome = grade(q, trace.answer, golden_result(con, q))                       # 'step limit' when the calls ran out    counts[q.split, "metrics-first"][outcome] += 1    counts[q.split, "schema-only"][schema_only_outcome(con, sql_model, schema, q)] += 1    facts[q.split][f"{q.kind} questions"] += 1    facts[q.split][f"{q.kind} correct"] += outcome == "correct"    facts[q.split]["forbidden answered"] += q.kind == "forbidden" and trace.answer.answered   # a forbidden question answered is a leak    facts[q.split]["model calls"] += sum(step.kind == "model" for step in trace.steps)    facts[q.split]["requests rejected"] += len(toolbox.rejected)    facts[q.split]["correct after a rejection"] += bool(toolbox.rejected) and outcome == "correct"    facts[q.split][f"asked back, {q.kind}"] += trace.answer.provenance.source == "ask_back"    if outcome != "correct":        missed[q.split].append(f"{q.question_id} {q.kind} {outcome}")for split in ("dev", "test"):    for approach in ("schema-only", "metrics-first"):     # only an agent run can hit the step limit        for outcome in ("correct", "wrong", "error", "declined") + (("step limit",) if approach != "schema-only" else ()):            print(f"{split} {approach} {outcome}: {counts[split, approach][outcome]} of 24")    # each split holds 24 golden questions    for kind in ("answer", "decline", "forbidden"):        print(f"{split} metrics-first {kind} correct: {facts[split][kind + ' correct']} of {facts[split][kind + ' questions']}")    for fact in ("forbidden answered", "model calls", "requests rejected", "correct after a rejection",                 "asked back, answer", "asked back, decline", "asked back, forbidden"):        print(f"{split} {fact}: {facts[split][fact]}")    print(f"{split} not correct: {', '.join(missed[split])}")
Salidapython metrics-first-score.py
dev schema-only correct: 2 of 24
dev schema-only wrong: 14 of 24
dev schema-only error: 8 of 24
dev schema-only declined: 0 of 24
dev metrics-first correct: 16 of 24
dev metrics-first wrong: 7 of 24
dev metrics-first error: 0 of 24
dev metrics-first declined: 0 of 24
dev metrics-first step limit: 1 of 24
dev metrics-first answer correct: 12 of 17
dev metrics-first decline correct: 3 of 4
dev metrics-first forbidden correct: 1 of 3
dev forbidden answered: 2
dev model calls: 43
dev requests rejected: 10
dev correct after a rejection: 6
dev asked back, answer: 0
dev asked back, decline: 2
dev asked back, forbidden: 0
dev not correct: gq-007 answer step limit, gq-012 answer wrong, gq-016 answer wrong, gq-017 answer wrong, gq-018 answer wrong, gq-020 decline wrong, gq-023 forbidden wrong, gq-024 forbidden wrong
test schema-only correct: 3 of 24
test schema-only wrong: 13 of 24
test schema-only error: 8 of 24
test schema-only declined: 0 of 24
test metrics-first correct: 10 of 24
test metrics-first wrong: 7 of 24
test metrics-first error: 0 of 24
test metrics-first declined: 6 of 24
test metrics-first step limit: 1 of 24
test metrics-first answer correct: 5 of 17
test metrics-first decline correct: 4 of 4
test metrics-first forbidden correct: 1 of 3
test forbidden answered: 2
test model calls: 36
test requests rejected: 6
test correct after a rejection: 0
test asked back, answer: 1
test asked back, decline: 2
test asked back, forbidden: 0
test not correct: gq-028 answer wrong, gq-031 answer wrong, gq-032 answer declined, gq-033 answer declined, gq-034 answer declined, gq-035 answer wrong, gq-036 answer declined, gq-037 answer declined, gq-038 answer wrong, gq-039 answer step limit, gq-040 answer wrong, gq-041 answer declined, gq-046 forbidden wrong, gq-048 forbidden wrong

Metrics-first gets more questions right than schema-only SQL on both splits. On dev, the counts are 16 of 24 against 2 of 24, and on the held-out test split, 10 of 24 against 3 of 24. No metrics-first run ended in an error, because the model never wrote SQL that could fail to run.

That isn't the same as never failing. Runs that used all four calls without an answer ended at the step limit, 1 of 24 on dev and 1 of 24 on test. The dev run is gq-007; the test run, gq-039. The runs took 43 model calls across the dev split. The calls beyond the first in a run went to describing a metric before querying it, and to corrections after a refusal.

The test split is the number to report, and it is much lower than dev. Metrics-first gets 5 of 17 answerable test questions right, against 12 of 17 on dev, and the difference is mostly questions it gave no answer to. Metrics-first declined 6 of 24 test questions, all of which the warehouse can answer, and every one is a gap in the layer. Gross margin, the share of sessions that led to an order, return on marketing spend, discounts given, customers who signed up twice, and one order's refund and its reason all need definitions the layer doesn't hold. The model declined the first five with a reason that names what's missing, which is a metric to write. It didn't decline the last one, gq-036: after a refused request it asked whether the person meant an order ID or a date range. That was 1 clarification on an answerable test question. That question back offers nothing the layer can serve, so a decline was due. Chapter 3 found that marketing and support ask answerable questions only in the test split, and the shop's layer was written around the questions finance and the analyst ask, so nothing tuned on dev could reveal those gaps.

On test questions whose right answer is a decline, the agent declined or asked back in 4 of 4.

This is one model, one sampled reply per call and one synthetic warehouse, so the numbers describe the shop and this setup, not text-to-SQL in general. On a split of 24, one question is about four points of accuracy, and a difference of one or two questions is noise. The gap between the two approaches here is far larger than that.

Working rule: Score metrics-first beside your baseline on the same golden questions, and tune on dev only. Say how many times you recorded the dev split while tuning, and record the test split once, after. Report correct, wrong, error, declined and runs ended by the step limit separately, and count clarifications and refused requests too, because they show where the calls go.

Lee las ejecuciones que no fueron correctas

Último cambio en la edición 2026.11.12

La puntuación indica cuántas ejecuciones fallaron, pero no por qué. El porqué está en las trazas, y es lo que decide qué arreglar: una métrica, una descripción, una comprobación o una regla de acceso. Cada ejecución que no fue correcta se desglosa llamada por llamada: la herramienta y los argumentos que envió el modelo, y la primera línea de lo que se devolvió. También imprime la solicitud para gq-008, una ejecución correcta junto a la que se colocan las respuestas erróneas de desarrollo, y le pide a la capa la solicitud que la ejecución de gq-039 intentaba alcanzar.

metrics-first-misses.py Python 3.12.15 · duckdb 2.0.0 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""Read every metrics-first run that wasn't correct, call by call, and ask the layer what gq-039's run was reaching for.The prose rests on the gq-039 line: the layer's own request for it matches the golden result, and the run never found it."""import jsonfrom lib.agent import run_agentfrom lib.golden import golden_result, grade, load_golden, results_matchfrom lib.metric_tools import MetricToolbox, catalogfrom lib.model import RecordedModelfrom lib.prompts import metrics_first_promptfrom lib.semantic import MetricRequest, loadfrom lib.warehouse import connectcon, layer = connect(), load()system, model, golden = metrics_first_prompt(catalog(layer)), RecordedModel("metric-agent-runs"), load_golden()for q in golden:    trace = run_agent(q.question, system, model, MetricToolbox(con, layer, role=q.role), max_steps=4)    outcome, answer = grade(q, trace.answer, golden_result(con, q)), trace.answer    calls = list(zip(trace.steps[::2], trace.steps[1::2]))      # each model reply, then what its tool returned    if q.question_id == "gq-008":                               # correct, and gq-012's words without the regions        print(f"gq-008 ({outcome}) request: {json.dumps(calls[-1][0].arguments)}")    if outcome == "correct":        continue    print(f"{q.question_id} ({q.split}, {q.kind}, {outcome}): {q.question}")    print(f"{q.question_id} model calls: {len(calls)}")    for number, (reply, result) in enumerate(calls, start=1):        sent = f"{reply.tool} {json.dumps(reply.arguments)}" if reply.tool else reply.content        got = result.content.splitlines()[0][:150]                              # the result's first line, cut to 150 characters        ended = {"metric": f"{len(answer.rows)} row" + "s" * (len(answer.rows) != 1), "none": "declined",                 "ask_back": "asked back"}        if number == len(calls) and answer.provenance.source in ended:            got = ended[answer.provenance.source]        print(f"  {number}. {sent} -> {got}")    if answer.answered:        print(f"{q.question_id} rows: {len(answer.rows)}")# gq-039 is answerable from the layer: the request its run was reaching for, with the order written as "-name".gq039 = next(q for q in golden if q.question_id == "gq-039")request = MetricRequest(("line_net_revenue",), group_by=("product__product_name",),                        filters={"metric_time__year": 2025}, order_by=("-line_net_revenue",), limit=5)print(f"gq-039 from the layer: {request}")# gq-039 is a ranked question, so row order counts in the comparison.matched = results_match(layer.query(con, request).rows, golden_result(con, gq039), gq039.order_matters)assert matched, "the layer's request for gq-039 should match its golden result"   # the request asks gq-039's question, the five products with the most net revenue in 2025, highest firstprint(f"gq-039 from the layer, matches golden: {'yes' if matched else 'no'}")
Salidapython metrics-first-misses.py
gq-007 (dev, answer, step limit): How much net revenue came from orders that included a tent in 2025?
gq-007 model calls: 4
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["product__product_name"], "filters": {"product__product_name": "tent", "metric_time__year": 2025}} -> error: request rejected: net_revenue can't use dimension 'product__product_name'; metrics that can use it: line_net_revenue, units_sold
  2. query_metric {"metrics": ["line_net_revenue"], "group_by": [], "filters": {"product__product_name": "tent", "metric_time__year": 2025}} -> error: request rejected: no row has product__product_name = 'tent'; its values: 120 values
  3. describe_metric "product__product_name" -> error: arguments must be a JSON object
  4. describe_metric "product__product_name" -> error: arguments must be a JSON object
gq-008 (correct) request: {"metrics": ["net_revenue"], "group_by": [], "filters": {"metric_time__year": "2025"}, "order_by": []}
gq-012 (dev, answer, wrong): What was total revenue for each sales region in 2025?
gq-012 model calls: 2
  1. query_metric {"metrics": ["gross_revenue"], "group_by": ["order__region"], "filters": {"order__order_date": "2025"}} -> error: request rejected: order__order_date = '2025': a date dimension matches single days only; for a period, filter metric_time at its grain, as metr
  2. query_metric {"metrics": ["gross_revenue"], "group_by": ["order__region"], "filters": {"metric_time__year": 2025}} -> 3 rows
gq-012 rows: 3
gq-016 (dev, answer, wrong): How many customers placed at least one order in 2025?
gq-016 model calls: 2
  1. describe_metric {"metric": "new_customers"} -> new_customers, a simple metric: Customers whose first order fell in the period.
  2. query_metric {"metrics": ["new_customers"], "group_by": [], "filters": {"metric_time__year": "2025"}, "order_by": [], "limit": null} -> 1 row
gq-016 rows: 1
gq-017 (dev, answer, wrong): What was net revenue in each of our countries in 2025?
gq-017 model calls: 1
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["order__country"], "filters": {"metric_time__year": 2025}} -> 10 rows
gq-017 rows: 10
gq-018 (dev, answer, wrong): How much was refunded, in euros, on orders placed in March 2026?
gq-018 model calls: 2
  1. describe_metric {"metric": "refunds"} -> refunds, a simple metric: Refunded EUR, counted on the local day the refund was made.
  2. query_metric {"metrics": ["refunds"], "group_by": ["metric_time__month"], "filters": {"metric_time__month": "2026-03"}} -> 1 row
gq-018 rows: 1
gq-020 (dev, decline, wrong): Which region is doing best?
gq-020 model calls: 2
  1. describe_metric {"metric": "net_revenue"} -> net_revenue, a simple metric: Revenue in EUR after discounts and before tax, from real orders that weren't cancelled, counted on the order's local bus
  2. query_metric {"metrics": ["net_revenue"], "group_by": ["customer__region"], "order_by": ["net_revenue"]} -> 3 rows
gq-020 rows: 3
gq-023 (dev, forbidden, wrong): What were the most common reasons for refunds in 2025?
gq-023 model calls: 2
  1. describe_metric {"metric": "refunds"} -> refunds, a simple metric: Refunded EUR, counted on the local day the refund was made.
  2. query_metric {"metrics": ["refunds"], "group_by": ["refund__reason"], "filters": {"metric_time__year": 2025}} -> 5 rows
gq-023 rows: 5
gq-024 (dev, forbidden, wrong): What was net revenue in EMEA in March 2026?
gq-024 model calls: 2
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["order__region"], "filters": {"order__region": "EMEA", "order__order_date": "2026-03"}} -> error: request rejected: order__order_date = '2026-03': a date dimension matches single days only; for a period, filter metric_time at its grain, as m
  2. query_metric {"metrics": ["net_revenue"], "group_by": ["order__region"], "filters": {"order__region": "EMEA", "metric_time__month": "2026-03"}} -> 1 row
gq-024 rows: 1
gq-028 (test, answer, wrong): Which country had the highest refund rate in fiscal year 2026?
gq-028 model calls: 2
  1. describe_metric {"metric": "refund_rate"} -> refund_rate, a ratio metric: Refunded EUR over gross revenue of the same orders: orders placed in the period that weren't cancelled.
  2. query_metric {"metrics": ["refund_rate"], "group_by": ["order__country"], "filters": {"metric_time__fiscal_year": 2026}} -> 10 rows
gq-028 rows: 10
gq-031 (test, answer, wrong): How many units did an order contain on average in 2025, counting quantities, not order lines?
gq-031 model calls: 2
  1. describe_metric {"metric": "units_sold"} -> units_sold, a simple metric: Units sold on orders that weren't cancelled.
  2. query_metric {"metrics": ["units_sold"], "group_by": [], "filters": {"metric_time__year": "2025"}, "order_by": []} -> 1 row
gq-031 rows: 1
gq-032 (test, answer, declined): What was our gross margin in euros on products sold in 2025?
gq-032 model calls: 2
  1. describe_metric {"metric": "refund_rate"} -> refund_rate, a ratio metric: Refunded EUR over gross revenue of the same orders: orders placed in the period that weren't cancelled.
  2. cannot_answer {"reason": "The requested gross margin cannot be computed as gross margin is not a directly available metric. Gross margin is derived from gross revenue and net revenue, which are not provided as a single metric. Refund_rate is available but does not represent gross margin."} -> declined
gq-033 (test, answer, declined): What share of sessions in each channel led to an order in 2025?
gq-033 model calls: 1
  1. cannot_answer {"reason": "The metrics available do not include session data or a measure of sessions per channel. Therefore, it is not possible to determine the share of sessions in each channel that led to an order."} -> declined
gq-034 (test, answer, declined): What was the return on marketing spend for paid search in 2025?
gq-034 model calls: 1
  1. cannot_answer {"reason": "The data does not include metrics related to marketing spend or return on marketing spend (ROMS), so it is not possible to calculate the return on marketing spend for paid search in 2025."} -> declined
gq-035 (test, answer, wrong): How many orders did we get in each country in March 2026?
gq-035 model calls: 2
  1. query_metric {"metrics": ["orders"], "group_by": ["order__country"], "filters": {"order__order_date": "2026-03"}} -> error: request rejected: order__order_date = '2026-03': a date dimension matches single days only; for a period, filter metric_time at its grain, as m
  2. query_metric {"metrics": ["orders"], "group_by": ["order__country"], "filters": {"metric_time__month": "2026-03"}} -> 10 rows
gq-035 rows: 10
gq-036 (test, answer, declined): How much was refunded on order 113432, in euros, and why?
gq-036 model calls: 2
  1. query_metric {"metrics": ["refunds"], "filters": {"order__order_date": "113432"}, "group_by": ["refund__reason"]} -> error: request rejected: order__order_date = '113432': a date dimension matches single days only; for a period, filter metric_time at its grain, as me
  2. ask_back {"question": "Do you mean the refund amount for a specific order (by order ID) or for a specific date range?", "options": ["order ID 113432", "a date range"]} -> asked back
gq-037 (test, answer, declined): How many customers signed up twice with the same email address?
gq-037 model calls: 1
  1. cannot_answer {"reason": "The available metrics do not track customer sign-ups or email address uniqueness, so it's not possible to determine how many customers signed up twice with the same email address."} -> declined
gq-038 (test, answer, wrong): What were net revenue and the number of orders on each day of the week in 2025?
gq-038 model calls: 1
  1. query_metric {"metrics": ["net_revenue", "orders"], "group_by": ["order__order_date"], "filters": {"order__order_date": "2025-01-01"}, "order_by": []} -> 1 row
gq-038 rows: 1
gq-039 (test, answer, step limit): Which five products brought in the most net revenue in 2025, from the highest down?
gq-039 model calls: 4
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["product__product_name"], "filters": {"order__order_date": "2025"}, "order_by": ["net_revenue", "-"], "limit": 5} -> error: request rejected: net_revenue can't use dimension 'product__product_name'; metrics that can use it: line_net_revenue, units_sold; order__order_
  2. query_metric {"metrics": ["line_net_revenue"], "group_by": ["product__product_name"], "filters": {"metric_time__year": 2025}, "order_by": ["line_net_revenue", "-"], "limit": 5} -> error: request rejected: can't order by '': it isn't a requested metric or group-by
  3. query_metric {"metrics": ["line_net_revenue"], "group_by": ["product__product_name"], "filters": {"metric_time__year": 2025}, "order_by": ["line_net_revenue", "-"], "limit": 5} -> error: request rejected: can't order by '': it isn't a requested metric or group-by
  4. describe_metric "line_net_revenue" -> error: arguments must be a JSON object
gq-040 (test, answer, wrong): What was revenue in each region in 2024 and in 2025?
gq-040 model calls: 2
  1. describe_metric {"metric": "net_revenue"} -> net_revenue, a simple metric: Revenue in EUR after discounts and before tax, from real orders that weren't cancelled, counted on the order's local bus
  2. query_metric {"metrics": ["net_revenue"], "group_by": ["customer__region"], "filters": {"metric_time__year": ["2024", "2025"]}} -> 3 rows
gq-040 rows: 3
gq-041 (test, answer, declined): How much discount did we give, in euros, in fiscal year 2026?
gq-041 model calls: 1
  1. cannot_answer {"reason": "The provided metrics do not include a metric for discount amounts. While net_revenue and gross_revenue are available, they represent revenue after discounts and before tax, but there is no specific metric to measure the total discount given in euros."} -> declined
gq-046 (test, forbidden, wrong): What was net revenue in APAC in June 2026?
gq-046 model calls: 2
  1. query_metric {"metrics": ["net_revenue"], "group_by": ["order__region"], "filters": {"order__region": "APAC", "order__order_date": "2026-06"}} -> error: request rejected: order__order_date = '2026-06': a date dimension matches single days only; for a period, filter metric_time at its grain, as m
  2. query_metric {"metrics": ["net_revenue"], "group_by": ["order__region"], "filters": {"order__region": "APAC", "metric_time__month": "2026-06"}} -> 1 row
gq-046 rows: 1
gq-048 (test, forbidden, wrong): How many orders did customers in AMER place in 2025?
gq-048 model calls: 1
  1. query_metric {"metrics": ["orders"], "group_by": ["customer__region"], "filters": {"customer__region": "AMER", "metric_time__year": 2025}} -> 1 row
gq-048 rows: 1
gq-039 from the layer: MetricRequest(metrics=('line_net_revenue',), group_by=('product__product_name',), filters={'metric_time__year': 2025}, order_by=('-line_net_revenue',), limit=5)
gq-039 from the layer, matches golden: yes

La ejecución de prueba que alcanzó el límite de pasos no fue un hueco de la capa. gq-039 pide los cinco productos con más ingresos netos en 2025, de mayor a menor, y la capa puede responderla: line_net_revenue agrupado por nombre de producto, ordenado por ["-line_net_revenue"] y limitado a cinco, da las filas de referencia. El modelo seguía escribiendo el orden como ["line_net_revenue", "-"], la validación lo rechazaba cada vez, y la ejecución se quedó sin llamadas.

Las respuestas erróneas del conjunto de prueba son del mismo tipo que las de desarrollo. Para el país con la tasa de devoluciones más alta, el agente devolvió la tasa de todos los países; para los ingresos de 2024 y de 2025, un único total para ambos años; para el promedio de unidades por pedido, el total de unidades; y para cada día de la semana en 2025, agrupó por fecha de pedido y filtró al 1 de enero de 2025, un solo día. Cada una de esas solicitudes era válida, y cada una respondía a una pregunta distinta. La última respuesta errónea, gq-035, vino del responsable regional de AMER, que pidió los pedidos de cada país y recibió los 10 países, el mismo problema con los roles que el gq-017 de desarrollo.

Los fallos de desarrollo se dividen en cuatro grupos, cada uno apuntando a un trabajo distinto. El primero es una métrica casi correcta. gq-012 pide los "ingresos totales" por región y obtiene gross_revenue, cuando el equipo de finanzas se refiere a los netos, mientras que gq-008, las mismas palabras sin regiones, obtuvo los ingresos netos. gq-018 pide las devoluciones de los pedidos de marzo y obtiene refunds, contadas por el día de la devolución, en lugar de order_refunds. El segundo es una pregunta que ninguna métrica cubre, respondida con la más cercana. gq-016 pregunta cuántos clientes hicieron un pedido en 2025 y obtiene el recuento de clientes nuevos. El tercero no puede ver quién pregunta. gq-017, del responsable regional de EMEA, pregunta por "nuestros países" y obtiene todos los 10, y se responden 2 preguntas prohibidas porque nada por debajo del modelo las detiene, que es el trabajo del capítulo 9. Por último, gq-007, los ingresos de los pedidos que incluían una tienda de campaña, necesita un filtro sobre las líneas de pedido que ninguna métrica ofrece. Esa ejecución gastó sus 4 llamadas en un filtro de tienda de campaña, rechazado primero porque los ingresos netos no pueden filtrarse por producto y luego porque no existe ningún producto llamado tent, y en llamadas de describir cuyos argumentos no eran un objeto JSON, y alcanzó el límite de pasos. El capítulo 7 da a este tipo de preguntas una vía de SQL protegida.

Regla práctica: Lee cada ejecución que no fue correcta, llamada por llamada, y clasifícala según lo que necesita: una métrica casi correcta significa que hay que afinar las descripciones o devolver la pregunta para aclararla, una métrica que falta significa que la capa necesita una o que la pregunta necesita SQL protegido, y una respuesta que depende del rol significa reglas de acceso, no instrucciones en el prompt.

Qué sale mal en producción

Último cambio en la edición 2026.11.12

El agente de la tienda responde cerca de la mitad de sus preguntas doradas a partir de las métricas, y menos en la partición de prueba reservada. Sobre una capa semántica real, el agente falla con los nombres, los mensajes, los valores y los roles, y cada uno tiene un síntoma que puedes vigilar.

Dos métricas encajan con las palabras, y el agente elige la otra. En las ejecuciones que no fueron correctas, "ingresos totales" fue a los ingresos netos para gq-008 y a los ingresos brutos para gq-012, y los reembolsos de los pedidos de marzo fueron al día del reembolso en lugar del día del pedido. Una capa con casi duplicados invita a esto. Las notas de la versión de Databricks registran que su agente de creación de paneles, Genie Code, pasó a ser "más propenso a referirse a las vistas de métricas de Unity Catalog existentes en lugar de crear nuevas" al importar informes de Tableau y Power BI, el 2 de julio de 2026, y, el 10 de septiembre de 2026, a preferir las vistas de métricas gobernadas frente a los conjuntos de datos SQL ad hoc al construir un panel (Databricks). Son afirmaciones de un proveedor sobre la creación de paneles, no sobre responder preguntas, pero abordan el mismo problema: definiciones que se multiplican. Mantén una métrica por término de negocio cuando puedas, escribe descripciones que digan cuándo no usar una métrica y conserva preguntas doradas para cada par de casi duplicados.

Una métrica con un nombre cercano responde una pregunta que no cubre. Los clientes nuevos no son los clientes que hicieron un pedido. La solicitud del agente es válida, la respuesta se ejecuta y solo una pregunta dorada muestra que está mal. Escribe preguntas doradas para términos que la capa no define y espera que la respuesta correcta sea una negativa.

Los mensajes de validación forman parte del prompt. El modelo lee cada rechazo, y su siguiente solicitud sigue la redacción. Cambiar un mensaje cambia la conversación, y cada grabación que vio el mensaje antiguo deja de reproducirse. Trata los mensajes como texto del prompt: guárdalos en un solo módulo, pruébalos y vuelve a grabar de forma deliberada cuando cambien.

Los valores de las dimensiones cambian. La validación lee los valores categóricos del almacén cuando se ejecuta la herramienta. Un país nuevo aparece el día en que se carga su primer pedido, y una lista de valores guardada en caché cuando se desplegó el agente lo rechazaría. El prompt de este capítulo tiene esa debilidad a pequeña escala: nombra las regiones y los canales, lo que evita al modelo una llamada de descripción, y quedaría obsoleto el día en que se añada una región. Lee los valores en el momento de la solicitud, o actualiza una caché con la carga que los cambia, y construye cualquier lista que lleve el prompt a partir de la misma fuente.

El agente no puede ver quién pregunta. El "nuestros países" de un responsable regional necesita un filtro según su rol, y una pregunta prohibida necesita un rechazo desde debajo del modelo. Ninguno de los dos pertenece al prompt, donde una pregunta puede convencer al modelo de ignorarlos. Aplica filtros de filas y máscaras de columnas en el compilador, como lo hace el capítulo 9, de modo que ninguna solicitud pueda llegar más allá de ellos.

Pedir aclaración se convierte en la respuesta a todo. Una puntuación cuenta como correcta una pregunta de aclaración ante una pregunta que debería rechazarse, así que la puntuación por sí sola no puede distinguir una pregunta de vuelta útil de una inútil. La pregunta de vuelta de la previsión siguió al prompt: la descripción de ask_back en METRICS_FIRST invita a hacerla cuando una pregunta "encaja con varias métricas o periodos", y "el próximo trimestre" encaja con dos periodos. La pregunta de vuelta de gq-036, sobre una pregunta que ninguna métrica cubre, debería haber sido un rechazo. Cuenta las aclaraciones sobre preguntas respondibles como un coste, léelas en las trazas y escribe la descripción de la herramienta para indicar cuándo no preguntar. Una comprobación que rechaza un ask_back cuyas opciones la capa no puede servir no está probada: todavía no la hemos construido.

Las correcciones cuestan llamadas. Cada rechazo es otra llamada al modelo, y el límite del bucle de cuatro llamadas al modelo por ejecución termina una ejecución que sigue siendo rechazada. En las ejecuciones que no fueron correctas, gq-007 gastó sus llamadas en un filtro de tiendas de campaña y en llamadas de descripción mal formadas, y gq-039 gastó las suyas en un pedido escrito de forma incorrecta. Vigila las llamadas por pregunta, y cuando un tipo de rechazo domine, corrige su causa en el catálogo o en las herramientas en lugar de subir el límite.

Regla práctica: Antes de ampliar la audiencia del agente, mantén una métrica por término de negocio con descripciones que digan cuándo no usarla, revisa los mensajes de validación como revisas los prompts, lee los valores de las dimensiones cuando se ejecutan las solicitudes, aplica los roles por debajo del agente, y cuenta las aclaraciones y los rechazos junto a la puntuación. Empieza por las métricas casi duplicadas, porque producen solicitudes válidas que devuelven números incorrectos.

Decisiones que tomó este capítulo

  • El agente ve métricas, nunca tablas. Sus herramientas son list_metrics, describe_metric, query_metric, ask_back y cannot_answer, sobre la capa semántica del capítulo 5, y su prompt incluye el catálogo de métricas y sus dimensiones.
  • El modelo devuelve una solicitud de métrica, no SQL, como una llamada de herramienta en JSON que run_agent() analiza y convierte en un MetricRequest. El libro conserva su propio formato de respuesta en lugar de las etiquetas <tool_call> de Qwen.
  • Cada solicitud se valida antes de compilarse, contra los nombres de la capa, los valores categóricos del almacén de datos y cada granularidad temporal. Una solicitud rechazada vuelve al modelo junto con las alternativas permitidas.
  • Una solicitud que devolvería un resultado vacío o parcial no es válida, como un periodo escrito sobre una dimensión de fecha diaria.
  • Pedir aclaraciones es una herramienta, cuyas opciones incluyen las definiciones de la capa, y sus respuestas se cuentan aparte de las negativas.
  • El enfoque centrado en métricas se mide en ambas particiones junto a la línea base de solo esquema, ajustado con el conjunto de desarrollo, y la partición de prueba se registra una sola vez tras el ajuste.
  • El catálogo va en el prompt, y describe_metric añade las granularidades temporales y los valores de cada dimensión, leídos del almacén de datos cuando se ejecuta la herramienta.
  • Una ejecución tiene como máximo cuatro llamadas al modelo, lo que deja margen para una descripción y una o dos correcciones, y termina una ejecución que sigue siendo rechazada. Una ejecución que alcanza el límite se puntúa como step limit, es decir, como un fallo, nunca como una negativa.
  • Las preguntas que ninguna métrica cubre se rechazan aquí. El capítulo 7 les da una vía de SQL protegida, y el capítulo 9 aplica los roles que el agente no puede ver.

Este capítulo, en esta edición

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

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

Cita esta sección

Formato

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

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

En esta página

Capítulo 6 de 11: Enruta las preguntas primero a métricas gobernadas

  1. Dale al agente métricas, no tablas
  2. Pide una solicitud, no SQL
  3. Valida la solicitud contra la capa
  4. Pide aclaración cuando una pregunta sea ambigua
  5. Measure metrics-first on the golden questions
  6. Lee las ejecuciones que no fueron correctas
  7. Qué sale mal en producción
  8. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos