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#
-
Qué es — el conjunto de tablas del modelo y los vínculos (clave → clave) entre ellas, con cardinalidad.
-
Cuándo usarlo — siempre que un dashboard cruza más de una tabla (hecho
vendas+ dimensionesprodutos,clientes,filiais,calendario). -
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 emiteLEFT JOINhecho → dimensión. Hay un diagrama visual interactivo para dibujar los vínculos arrastrando. -
Requisitos previos — al menos dos tablas en el dataset
prd_aurora_goldcon columnas clave compatibles (p. ej.,vendas.produto_id↔produtos.id). -
Cómo validar — en el editor, abre el diagrama del modelo, vincula
vendas.produto_idconprodutos.id; crea un visual de barras "ingresos porprodutos.categoria" y confirma que el valor aparece cruzando las dos tablas. -
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.
-
Datos de ejemplo (sintéticos)
vendas.produto_id valor produtos.id produtos.categoria 10 250 10 Bebidas 11 90 11 Limpeza -
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#
- 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.
- Cuándo usarlo — automático; protege cualquier SUM/COUNT/AVG sobre un join 1-N que duplicaría la medida.
- Cómo funciona —
hopFansOut/joinDuplicatesRowsdetectan 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. - Requisitos previos — cardinalidad declarada en la relación.
- Cómo validar — crea un join 1-N que duplique filas (p. ej.,
filiaisvinculada avendaspor 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. - Límites y salvedades — la protección es sobre agregaciones que duplicarían; no sustituye un buen modelado, solo evita el error silencioso.
- Datos de ejemplo (sintéticos) —
filiais(2 filas) ×vendas(6 filas) porcidade: sumarfiliais.metadirecto sobre el join contaría la meta 3× por sucursal — es el caso bloqueado. - 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)#
- 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. - 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).
- 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.
- Requisitos previos — relación con ids estables (schema del modelo v2).
- Cómo validar — activa
bothen 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. - Límites y salvedades — es opt-in; un modelo todo en "single" no sufre ningún cambio (comportamiento heredado congelado).
- Datos de ejemplo (sintéticos) —
produtos↔vendasconboth: filtrarvendas.mes = "2026-07"pasa a recortar la lista deprodutosmostrada. - Evidencia — detección pura de ciclos/ambigüedad de propagación cubierta por una suite determinística.
Roles de relación (role-playing dimensions)#
- Qué es — la misma dimensión vinculada varias veces al hecho, cada vínculo con
un rol con nombre (p. ej.,
calendariocomo "Data do Pedido" (fecha del pedido), "Data de Entrega" (fecha de entrega), "Data de Pagamento" (fecha de pago)). - 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.
- 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 repetirUSAR_RELACAO. Los roles del mismo par de tablas forman un grupo detectado automáticamente. - Requisitos previos — múltiples relaciones entre el mismo par (una activa, las demás inactivas) e ids estables (modelo v2).
- Cómo validar — vincula
calendarioavendaspordata_pedido(activa),data_entregaydata_pagamento(inactivas); nombra los roles; en un visual, cambia de "Data do Pedido" a "Data de Entrega" y mira cómo cambia el eje. - Límites y salvedades — tope de roles por modelo (
MAX_RELATION_ROLES). - Datos de ejemplo (sintéticos) —
vendascondata_pedido=2026-07-01,data_entrega=2026-07-03,data_pagamento=2026-07-10. - 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#
- Qué es — resuelve una relación N-N entre dos tablas mediante una tabla puente con FK hacia las dos, sin doble conteo.
- Cuándo usarlo — p. ej.,
produtos↔promocoes(un producto en varias promociones; una promoción con varios productos) vinculados porproduto_promocao. - 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).
- Requisitos previos — la tabla puente declarada en la relación (
BridgeSpec). - Cómo validar — suma
produtos.precocruzando porproduto_promocaoy confirma que cada producto cuenta una vez por valor de dimensión, no una vez por fila del puente. - Límites y salvedades — exige un puente explícito declarado; un N-N sin puente se trata como ambiguo.
- Datos de ejemplo (sintéticos) —
produto_promocao: (10→"Julho"), (10→"Inverno"), (11→"Julho"); sumar el precio deprodutosno debe triplicar el producto 10. - 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#
- 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.
- Cuándo usarlo — crear
margem = receita - custocomo columna; armar la jerarquíaRegião > Estado > Cidadepara el drill; marcarfiliais.ufcomo UF para los mapas. - 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).
- Requisitos previos — columnas de origen en el modelo.
- 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. - Límites y salvedades — las columnas calculadas se evalúan en la materialización; los ciclos se bloquean por un límite de profundidad.
- Datos de ejemplo (sintéticos) —
filiais: (SP · Sudeste · São Paulo), (RJ · Sudeste · Rio de Janeiro), (MG · Sudeste · Belo Horizonte). - 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)#
- Qué es — dimensión de calendario configurable: año fiscal, 4-4-5 (retail), zona horaria y locale pt-BR.
- 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.).
- 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/diaSemanareflejan elEXTRACTdel datalake para la paridad motor puro ↔ SQL. - Requisitos previos — configurar el inicio del año fiscal y/o el modo 4-4-5 y la zona horaria.
- Cómo validar — configura el año fiscal empezando el 01/04; confirma que el
año fiscal 2026cubre 01/04/2026 → 31/03/2027 en un visual por período. - 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. - 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.
- 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)#
- 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.
- Cuándo usarlo — cuando varios dashboards necesitan la misma definición canónica (los mismos "ingresos netos" en todas partes).
- 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 porworkspaceId; los releases no tienen update/delete (publicar de nuevo genera una versión nueva). Auditado. - Requisitos previos — workspace activo; rol de dueño/admin para publicar.
- Cómo validar — publica un modelo, confirma que recibe
versiony checksum; edita el borrador y publica de nuevo — debe crearversion+1sin alterar la anterior. - 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.
- Datos de ejemplo (sintéticos) — release v1 (checksum
sha256:…) con la medida central "Receita"; v2 agrega "Ticket médio". - Evidencia — almacenamiento de releases, gobernanza (releases inmutables) y vínculo dashboard↔modelo cubiertos por una suite determinística.