Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Actualizado el 2026-10-04

Modelo semántico

Las tablas, relaciones y medidas que los visuales ven como campos.

En esta página (8)

El modelo semántico es donde describes cómo se vinculan tus tablas y qué significan los números, una sola vez, para que todos los visuales hablen el mismo idioma. Vive por dashboard (modelJson) y también puede vivir centralizado por workspace con versiones inmutables. Es la base que evita "cada gráfico con una definición diferente de ingresos".

Los ejemplos usan el workspace sintético Comércio Aurora Ltda (workspace aurora).


Tablas y relaciones#

  1. Qué es — el conjunto de tablas del modelo y los vínculos (clave → clave) entre ellas, con cardinalidad.

  2. Cuándo usarlo — siempre que un dashboard cruza más de una tabla (hecho vendas + dimensiones produtos, clientes, filiais, calendario).

  3. Cómo funciona — cada relación tiene un lado UNO y un lado MUCHOS y una cardinalidad 1-1 | 1-N | N-1 | N-N. Al armar el SQL, el generador encuentra el camino de join buscando en el grafo (joinPath) y emite LEFT JOIN hecho → dimensión. Hay un diagrama visual interactivo para dibujar los vínculos arrastrando.

  4. Requisitos previos — al menos dos tablas en el dataset prd_aurora_gold con columnas clave compatibles (p. ej., vendas.produto_id ↔ produtos.id).

  5. Cómo validar — en el editor, abre el diagrama del modelo, vincula vendas.produto_id con produtos.id; crea un visual de barras "ingresos por produtos.categoria" y confirma que el valor aparece cruzando las dos tablas.

  6. Límites y salvedades — las relaciones se resuelven en el SQL (no hay motor en memoria tipo VertiPaq); el join físico siempre es hecho → dimensión.

  7. Datos de ejemplo (sintéticos)

    vendas.produto_idvalorprodutos.idprodutos.categoria
    1025010Bebidas
    119011Limpeza
  8. Evidencia — motor de relaciones y de camino de join cubierto por una suite determinística y por un contrato de relaciones; el SQL del modelo está congelado por el conjunto de pruebas de referencia, con resultado idéntico en cada ejecución.


Cardinalidad y protección anti-fan-out#

  1. Qué es — la cardinalidad tiene un efecto real: cuando un join multiplica filas, las sumas quedarían infladas — el generador rechaza la agregación en lugar de entregar un número incorrecto.
  2. Cuándo usarlo — automático; protege cualquier SUM/COUNT/AVG sobre un join 1-N que duplicaría la medida.
  3. Cómo funciona — hopFansOut/joinDuplicatesRows detectan la "explosión" de filas en el camino de join; la agregación afectada se bloquea con un mensaje didáctico. Es lo que Power BI resuelve pidiendo un modelado correcto; aquí es una protección automática.
  4. Requisitos previos — cardinalidad declarada en la relación.
  5. Cómo validar — crea un join 1-N que duplique filas (p. ej., filiais vinculada a vendas por una clave no única) e intenta sumar una columna de la tabla del lado UNO; confirma el rechazo con un aviso en lugar de un total inflado.
  6. Límites y salvedades — la protección es sobre agregaciones que duplicarían; no sustituye un buen modelado, solo evita el error silencioso.
  7. Datos de ejemplo (sintéticos) — filiais (2 filas) × vendas (6 filas) por cidade: sumar filiais.meta directo sobre el join contaría la meta 3× por sucursal — es el caso bloqueado.
  8. Evidencia — detección de fan-out (explosión de filas en el camino de join) cubierta por una suite determinística; comportamiento fijado por el conjunto de pruebas de referencia.

Dirección de filtro bidireccional (opt-in)#

  1. Qué es — por defecto el filtro fluye de UNO a MUCHOS (dimensión → hecho). crossFilter: "both" activa la propagación en los dos sentidos en esa relación.
  2. Cuándo usarlo — cuando filtrar el hecho también tiene que recortar la dimensión (p. ej., mostrar solo los productos que tuvieron ventas en el período filtrado).
  3. Cómo funciona — el grafo de join no es dirigido (el SQL físico no cambia al activar "both"); el grafo de filtro es dirigido. El modelo detecta ciclos y ambigüedad de propagación y rechaza modelos cuyo significado quedaría indefinido — nunca genera SQL ambiguo en silencio.
  4. Requisitos previos — relación con ids estables (schema del modelo v2).
  5. Cómo validar — activa both en una relación, crea un segundo camino de propagación entre el mismo par y confirma que el editor señala ambigüedad/ciclo en lugar de aceptarlo en silencio.
  6. Límites y salvedades — es opt-in; un modelo todo en "single" no sufre ningún cambio (comportamiento heredado congelado).
  7. Datos de ejemplo (sintéticos) — produtos ↔ vendas con both: filtrar vendas.mes = "2026-07" pasa a recortar la lista de produtos mostrada.
  8. Evidencia — detección pura de ciclos/ambigüedad de propagación cubierta por una suite determinística.

Roles de relación (role-playing dimensions)#

  1. Qué es — la misma dimensión vinculada varias veces al hecho, cada vínculo con un rol con nombre (p. ej., calendario como "Data do Pedido" (fecha del pedido), "Data de Entrega" (fecha de entrega), "Data de Pagamento" (fecha de pago)).
  2. Cuándo usarlo — cuando el hecho tiene varias fechas (o varias claves hacia la misma dimensión) y quieres elegir cuál usar en cada visual.
  3. Cómo funciona — una relación queda activa y las demás inactivas; el visual elige el rol una vez (FieldSpec.relationRole) en lugar de repetir USAR_RELACAO. Los roles del mismo par de tablas forman un grupo detectado automáticamente.
  4. Requisitos previos — múltiples relaciones entre el mismo par (una activa, las demás inactivas) e ids estables (modelo v2).
  5. Cómo validar — vincula calendario a vendas por data_pedido (activa), data_entrega y data_pagamento (inactivas); nombra los roles; en un visual, cambia de "Data do Pedido" a "Data de Entrega" y mira cómo cambia el eje.
  6. Límites y salvedades — tope de roles por modelo (MAX_RELATION_ROLES).
  7. Datos de ejemplo (sintéticos) — vendas con data_pedido=2026-07-01, data_entrega=2026-07-03, data_pagamento=2026-07-10.
  8. Evidencia — edición de roles y detección automática de grupos cubiertas por una suite determinística.

Relación M:N mediante puente explícito#

  1. Qué es — resuelve una relación N-N entre dos tablas mediante una tabla puente con FK hacia las dos, sin doble conteo.
  2. Cuándo usarlo — p. ej., produtos ↔ promocoes (un producto en varias promociones; una promoción con varios productos) vinculados por produto_promocao.
  3. Cómo funciona — al cruzar A → puente → B, la medida del lado opuesto se deduplica (reduce el puente a pares distintos antes de sumar); una medida que vive en el propio puente suma directo (su granularidad es el puente).
  4. Requisitos previos — la tabla puente declarada en la relación (BridgeSpec).
  5. Cómo validar — suma produtos.preco cruzando por produto_promocao y confirma que cada producto cuenta una vez por valor de dimensión, no una vez por fila del puente.
  6. Límites y salvedades — exige un puente explícito declarado; un N-N sin puente se trata como ambiguo.
  7. Datos de ejemplo (sintéticos) — produto_promocao: (10→"Julho"), (10→"Inverno"), (11→"Julho"); sumar el precio de produtos no debe triplicar el producto 10.
  8. Evidencia — resolución del puente y semántica anti-doble-conteo cubiertas por una suite determinística.

Columnas calculadas, jerarquías y categoría de dato#

  1. Qué es — columnas derivadas por fórmula (fila por fila), jerarquías de niveles para el drill, y categoría de dato (p. ej., geografía/UF) por columna.
  2. Cuándo usarlo — crear margem = receita - custo como columna; armar la jerarquía Região > Estado > Cidade para el drill; marcar filiais.uf como UF para los mapas.
  3. Cómo funciona — las columnas calculadas se encadenan con protección anticiclos (profundidad limitada); las jerarquías definen el orden del drill; la categoría de dato orienta los visuales (mapas) y el formato. Hay sort-by-column (ordenar el mes por el número).
  4. Requisitos previos — columnas de origen en el modelo.
  5. Cómo validar — crea la jerarquía filiais.regiao > filiais.uf > filiais.cidade, ponla en un visual de barras y usa el botón de drill para bajar un nivel.
  6. Límites y salvedades — las columnas calculadas se evalúan en la materialización; los ciclos se bloquean por un límite de profundidad.
  7. Datos de ejemplo (sintéticos) — filiais: (SP · Sudeste · São Paulo), (RJ · Sudeste · Rio de Janeiro), (MG · Sudeste · Belo Horizonte).
  8. Evidencia — jerarquías, sort-by-column, categoría de dato y columnas calculadas cubiertas por una suite determinística.

Calendarios configurables (fiscal, 4-4-5, zona horaria, locale)#

  1. Qué es — dimensión de calendario configurable: año fiscal, 4-4-5 (retail), zona horaria y locale pt-BR.
  2. Cuándo usarlo — una empresa cuyo año fiscal no empieza en enero, o que cierra en períodos 4-4-5 de retail; base de la inteligencia de tiempo (YTD, etc.).
  3. Cómo funciona — trabaja con la fecha civil (nunca UTC), evitando el error del cierre de las 22 h del 31/12. El año fiscal se etiqueta con el año civil en que comienza; el 4-4-5 usa la regla "closest" (NRF) y la semana 53 va completa al último período. semana/diaSemana reflejan el EXTRACT del datalake para la paridad motor puro ↔ SQL.
  4. Requisitos previos — configurar el inicio del año fiscal y/o el modo 4-4-5 y la zona horaria.
  5. Cómo validar — configura el año fiscal empezando el 01/04; confirma que el año fiscal 2026 cubre 01/04/2026 → 31/03/2027 en un visual por período.
  6. Límites y salvedades — el locale viene de una tabla fija (no de Intl) para garantizar bytes idénticos entre el motor y el SQL; un idioma nuevo exige una tabla nueva.
  7. Datos de ejemplo (sintéticos) — una venta el 31/12/2025 a las 22:00 (zona horaria America/Sao_Paulo) cae en el año/período civil correcto, no en el año siguiente.
  8. Evidencia — el calendario (motor puro) y su traducción a SQL cubiertos por una suite determinística, con paridad motor puro ↔ SQL verificada.

Modelo semántico centralizado por workspace (releases inmutables)#

  1. Qué es — la definición de tablas/relaciones/medidas puede vivir una sola vez por workspace, con releases inmutables versionados por checksum, consumidos por N dashboards por referencia.
  2. Cuándo usarlo — cuando varios dashboards necesitan la misma definición canónica (los mismos "ingresos netos" en todas partes).
  3. Cómo funciona — el editor escribe en el borrador (draftJson); publicar congela una copia en un release (version = max+1, checksum sha256). Anti-IDOR: toda consulta filtra por workspaceId; los releases no tienen update/delete (publicar de nuevo genera una versión nueva). Auditado.
  4. Requisitos previos — workspace activo; rol de dueño/admin para publicar.
  5. Cómo validar — publica un modelo, confirma que recibe version y checksum; edita el borrador y publica de nuevo — debe crear version+1 sin alterar la anterior.
  6. Límites y salvedades — el "wiring" que hace que los dashboards consuman la versión central por referencia todavía está en curso. El contenido del modelo es JSON opaco en esta capa.
  7. Datos de ejemplo (sintéticos) — release v1 (checksum sha256:…) con la medida central "Receita"; v2 agrega "Ticket médio".
  8. Evidencia — almacenamiento de releases, gobernanza (releases inmutables) y vínculo dashboard↔modelo cubiertos por una suite determinística.

Enlaces relacionados