David · Data Architect

Capa semántica y métricas certificadas

Cómo David define entidades, relaciones y métricas una sola vez, y cómo eso evita la duplicación silenciosa y las cifras contradictorias.

Actualizado el 4 de octubre de 2026

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 y todas las respuestas salen de ahí.

#Las piezas

Pieza	Qué define	Ejemplo
Entidad	Una cosa del negocio, su tabla de origen y su granularidad (qué representa una fila).	Orden: una fila por `order_id`.
Relación	Cómo se unen dos entidades y con qué cardinalidad.	Una orden tiene muchos pagos (1 a N).
Métrica	La fórmula, la entidad sobre la que se agrega y sus filtros.	`ventas_netas = SUM(items.precio) - devoluciones`.
Dimensión	Por qué se puede desglosar.	Sucursal, mes, vendedor, canal.
Dueño	Quién en tu empresa responde por la definición.	Control de gestión.

#Un ejemplo completo

semantic/ventas.yaml (ejemplo de referencia)

entidades:
  ordenes:
    tabla: public.orders
    grano: order_id
    columna_tenant: company_id

  items:
    tabla: public.order_items
    grano: order_id + product_id
    relacion: { con: ordenes, tipo: muchos_a_uno }
    regla: PRE_AGREGAR_ANTES_DE_UNIR   # N ítems por orden

  pagos:
    tabla: public.order_payments
    grano: order_id + payment_sequential
    relacion: { con: ordenes, tipo: muchos_a_uno }
    regla: PRE_AGREGAR_ANTES_DE_UNIR   # N pagos por orden

metricas:
  venta_bruta:
    formula: SUM(items.price)
    grano: order_id
    dueno: control_de_gestion
  total_pagado:
    formula: SUM(pagos.payment_value)
    grano: order_id
    dueno: tesoreria

reglas:
  - nunca_unir_dos_tablas_de_hechos_directamente
  - cada_metrica_se_agrega_en_su_grano_antes_del_join

#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

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.