Saltar al contenido
GUREN AI Docs

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.

Actualizado el

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.

PilarQué defineEjemplo
1. Reglas de negocioLas 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étricasCada 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 certificadosLas 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. AnclasPreguntas 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:

capa semántica de referencia (extracto)
{
  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.

consulta ingenua: infla los totales
-- 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;
consulta que compila David: agrega cada tabla en su grano
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

  1. Definir

    Escribimos la fórmula con el dueño de la métrica, en lenguaje de negocio y en la capa semántica.
  2. Reconciliar

    Comparamos el resultado con una fuente de verdad (el ERP, un cierre contable ya auditado) para períodos conocidos.
  3. Aprobar

    El dueño aprueba la definición. Desde ahí, la métrica queda marcada como certificada.
  4. 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.