David · Data Architect
Capa semántica y métricas certificadas
Los cuatro pilares de la capa semántica de David (reglas, glosario, joins certificados y anclas), los dominios con mínimo privilegio y cómo se evita la duplicación silenciosa.
La capa semántica es el diccionario de tu negocio escrito para una máquina: qué es una orden, cómo se relaciona con sus pagos y cómo se calcula cada métrica. Se define una vez, la valida tu equipo, se versiona como código y todas las respuestas salen de ahí.
#Los cuatro pilares
La capa semántica de David sigue el Nivel 2 del Enterprise Brain descrito en la investigación: cuatro pilares que, juntos, permiten responder sin improvisar.
| Pilar | Qué define | Ejemplo |
|---|---|---|
| 1. Reglas de negocio | Las excepciones y criterios que hoy viven en la cabeza de los expertos, escritos y versionados. | “El GMV excluye órdenes canceladas y no incluye flete.” |
| 2. Glosario de métricas | Cada métrica con su fórmula canónica, su tabla de hechos, sus filtros, su fecha de referencia, sus sinónimos y su dueño. | gmv = SUM(price) sobre ítems, dueño: finanzas. |
| 3. Esquemas y joins certificados | Las tablas y columnas permitidas, y cómo se unen, con su cardinalidad (muchos a uno o uno a uno). | Ítems → órdenes: muchos a uno. |
| 4. Anclas | Preguntas reales de tu equipo con su solicitud estructurada correcta, curadas por expertos. | “GMV por estado en 2017” → métrica, dimensión y rango. |
A esto se suman las dimensiones (por qué se puede desglosar: estado, categoría, mes, medio de pago) y los dominios: subagentes con permiso de mínimo privilegio sobre un subconjunto de tablas, como Finanzas, Comercial u Operaciones.
#Un ejemplo completo
Así se ve, de forma resumida, la capa semántica de referencia que usa la demo pública, construida sobre un conjunto de datos abierto de 100.000 órdenes de e-commerce:
{
name: 'olist-demo',
version: '2026-10-26',
tables: {
olist_orders: { columns: ['order_id', 'customer_id', 'order_status', 'order_purchase_timestamp', …] },
olist_order_items: { columns: ['order_id', 'order_item_id', 'product_id', 'price', 'freight_value', …] },
olist_order_payments: { columns: ['order_id', 'payment_sequential', 'payment_type', 'payment_value', …] }
},
joins: [
{ from: 'olist_order_items', to: 'olist_orders', on: [['order_id', 'order_id']], cardinality: 'many_to_one' },
{ from: 'olist_order_payments', to: 'olist_orders', on: [['order_id', 'order_id']], cardinality: 'many_to_one' }
],
metrics: {
gmv: {
label: 'GMV', table: 'olist_order_items', aggregate: 'SUM', expression: 'price',
filters: [{ table: 'olist_orders', column: 'order_status', op: 'not in', value: ['canceled', 'unavailable'] }],
time: { table: 'olist_orders', column: 'order_purchase_timestamp' },
synonyms: ['ventas brutas', 'valor bruto', 'gross merchandise value'], owner: 'finanzas'
},
payments_total: {
label: 'Pagos recibidos', table: 'olist_order_payments', aggregate: 'SUM', expression: 'payment_value',
time: { table: 'olist_orders', column: 'order_purchase_timestamp' }, owner: 'finanzas'
}
},
dimensions: {
customer_state: { label: 'Estado del cliente', table: 'olist_customers', column: 'customer_state' },
payment_type: { label: 'Medio de pago', table: 'olist_order_payments', column: 'payment_type' }
},
rules: [
{ id: 'r3', metrics: ['payments_total'], text: 'Una orden puede tener varios pagos: los pagos se suman en su propia tabla, nunca cruzados con ítems.' }
],
anchors: [
{ question: 'GMV por estado en 2017', request: { metrics: ['gmv'], dimensions: ['customer_state'], dateRange: { from: '2017-01-01', to: '2018-01-01' } } }
],
domains: {
finance: { label: 'Finanzas', tables: ['olist_orders', 'olist_order_items', 'olist_order_payments', …] },
operations: { label: 'Operaciones', tables: ['olist_orders', 'olist_order_reviews', …] }
}
}#Recuperación en dos etapas
El modelo de lenguaje nunca recibe la capa semántica completa ni tus datos. Primero ve un índice liviano (nombres y descripciones de métricas y dimensiones) para elegir qué pedir; después, David trae solo las definiciones y reglas de lo elegido. Así se reduce el riesgo de confusión y el modelo no ve columnas ni SQL.
#La duplicación silenciosa
Imagina una orden con 3 ítems y 2 pagos. Si una consulta une ítems y pagos directamente, cada ítem se cruza con cada pago: 3 × 2 = 6 filas. Los totales se multiplican y la base de datos no muestra ningún error.
-- Une todo de una vez: cada ítem se repite por cada pago
SELECT o.order_id,
SUM(i.price) AS total_items, -- multiplicado por la cantidad de pagos
SUM(p.payment_value) AS total_pagado -- multiplicado por la cantidad de ítems
FROM orders o
JOIN order_items i ON o.order_id = i.order_id
JOIN order_payments p ON o.order_id = p.order_id
GROUP BY o.order_id;WITH items AS (
SELECT order_id, SUM(price) AS total_items
FROM order_items GROUP BY order_id
),
pagos AS (
SELECT order_id, SUM(payment_value) AS total_pagado
FROM order_payments GROUP BY order_id
)
SELECT o.order_id, i.total_items, p.total_pagado
FROM orders o
LEFT JOIN items i ON o.order_id = i.order_id
LEFT JOIN pagos p ON o.order_id = p.order_id;#Certificar una métrica
Definir
Escribimos la fórmula con el dueño de la métrica, en lenguaje de negocio y en la capa semántica.Reconciliar
Comparamos el resultado con una fuente de verdad (el ERP, un cierre contable ya auditado) para períodos conocidos.Aprobar
El dueño aprueba la definición. Desde ahí, la métrica queda marcada como certificada.Vigilar
Si la fuente cambia (una columna nueva, un cambio de plan de cuentas), la métrica vuelve a revisión antes de seguir respondiendo.
#Qué pasa si la pregunta no cabe en la capa
Si alguien pregunta por algo que no está definido, David no improvisa una fórmula: dice qué falta (“no hay una definición de margen por cliente”), propone cómo definirla y la deja para aprobación de su dueño. Si la pregunta es ambigua entre dos métricas definidas, pide una aclaración. Ver Cómo responde una pregunta.