Modelo semântico

Selos usados: GA-candidato · Preview · NÃO MEDIDO · Roadmap. Legenda e template (selo + 9 campos) em README.

O modelo semântico é onde você descreve como suas tabelas se ligam e o que os números significam, uma vez, para que todos os visuais falem a mesma língua. Ele vive por dashboard (modelJson) e também pode viver centralizado por workspace com versões imutáveis. É a base que evita "cada gráfico com uma definição diferente de receita".

Exemplos usam o workspace sintético Comércio Aurora Ltda (workspace aurora).

Tabelas e relações#

Selo: GA-candidato

1. O que é — o conjunto de tabelas do modelo e as ligações (chave → chave) entre elas, com cardinalidade.

2. Quando usar — sempre que um dashboard cruza mais de uma tabela (fato vendas + dimensões produtos, clientes, filiais, calendario).

3. Como funciona — cada relação tem lado UM e lado MUITOS e uma cardinalidade 1-1 | 1-N | N-1 | N-N. Ao montar o SQL, o gerador acha o caminho de join por busca no grafo (joinPath) e emite LEFT JOIN fato → dimensão. Há um diagrama visual interativo para desenhar as ligações arrastando.

4. Pré-requisitos — pelo menos duas tabelas no dataset aurora_gold com colunas-chave compatíveis (ex.: vendas.produto_id ↔ produtos.id).

5. Como validar — no editor, abra o diagrama do modelo, ligue vendas.produto_id a produtos.id; crie um visual de barras "receita por produtos.categoria" e confirme que o valor aparece cruzando as duas tabelas.

6. Limites e ressalvas — relações são resolvidas no SQL (não há engine in-memory tipo VertiPaq); o join físico é sempre fato → dimensão.

7. Dados de exemplo (sintéticos)

   vendas.produto_id	valor	produtos.id	produtos.categoria
   10	250	10	Bebidas
   11	90	11	Limpeza

8. Evidência — motor de relações e de caminho de join coberto por suíte determinística e por contrato de relações; o SQL do modelo é congelado pelo conjunto de testes de referência, com resultado idêntico a cada execução.

9. Estado & maturidade — motor provado por um conjunto de testes de referência. Falta para GA: execução comprovada no datalake de produção (hoje NÃO MEDIDO sem o datalake configurado).

Cardinalidade e proteção anti-fan-out#

Selo: GA-candidato

1. O que é — a cardinalidade tem efeito real: quando um join multiplica linhas, somas ficariam infladas — o gerador recusa a agregação em vez de entregar número errado.
2. Quando usar — automático; protege qualquer SUM/COUNT/AVG sobre um join 1-N que duplicaria a medida.
3. Como funciona — hopFansOut/joinDuplicatesRows detectam o "estouro" de linhas no caminho de join; a agregação afetada é bloqueada com mensagem didática. É o que o Power BI resolve pedindo modelagem correta; aqui é guarda automática.
4. Pré-requisitos — cardinalidade declarada na relação.
5. Como validar — crie um join 1-N que duplique linhas (ex.: filiais ligada a vendas por uma chave não única) e tente somar uma coluna da tabela do lado UM; confirme a recusa com aviso em vez de total inflado.
6. Limites e ressalvas — a proteção é sobre agregações que duplicariam; não substitui boa modelagem, apenas evita o erro silencioso.
7. Dados de exemplo (sintéticos) — filiais (2 linhas) × vendas (6 linhas) por cidade: somar filiais.meta direto sobre o join contaria a meta 3× por filial — é o caso bloqueado.
8. Evidência — detecção de fan-out (estouro de linhas no caminho de join) coberta por suíte determinística; comportamento fixado pelo conjunto de testes de referência.
9. Estado & maturidade — GA-candidato; comportamento fixado pelo conjunto de testes de referência.

Direção de filtro bidirecional (opt-in)#

Selo: GA-candidato

1. O que é — por padrão o filtro flui do UM para o MUITOS (dimensão → fato). crossFilter: "both" liga a propagação nos dois sentidos naquela relação.
2. Quando usar — quando filtrar o fato precisa também recortar a dimensão (ex.: mostrar só produtos que tiveram venda no período filtrado).
3. Como funciona — o grafo de join é não-direcionado (o SQL físico não muda ao ligar "both"); o grafo de filtro é direcionado. O modelo detecta ciclo e ambiguidade de propagação e recusa modelos cujo significado ficaria indefinido — nunca gera SQL ambíguo em silêncio.
4. Pré-requisitos — relação com ids estáveis (schema do modelo v2).
5. Como validar — ligue both numa relação, crie um segundo caminho de propagação entre o mesmo par e confirme que o editor acusa ambiguidade/ciclo em vez de aceitar calado.
6. Limites e ressalvas — é opt-in; um modelo todo "single" não sofre nenhuma mudança (comportamento legado congelado).
7. Dados de exemplo (sintéticos) — produtos ↔ vendas com both: filtrar vendas.mes = "2026-07" passa a recortar a lista de produtos exibida.
8. Evidência — detecção pura de ciclo/ambiguidade de propagação coberta por suíte determinística.
9. Estado & maturidade — GA-candidato; adicionado após a auditoria técnica inicial (fecha a lacuna "sem filtro bidirecional").

Papéis de relação (role-playing dimensions)#

Selo: GA-candidato

1. O que é — a mesma dimensão ligada várias vezes ao fato, cada ligação com um papel nomeado (ex.: calendario como "Data do Pedido", "Data de Entrega", "Data de Pagamento").
2. Quando usar — quando o fato tem várias datas (ou várias chaves para a mesma dimensão) e você quer escolher qual usar por visual.
3. Como funciona — uma relação fica ativa e as demais inativas; o visual escolhe o papel uma vez (FieldSpec.relationRole) em vez de repetir USAR_RELACAO. Papéis do mesmo par de tabelas formam um grupo detectado automaticamente.
4. Pré-requisitos — múltiplas relações entre o mesmo par (uma ativa, demais inativas) e ids estáveis (modelo v2).
5. Como validar — ligue calendario a vendas por data_pedido (ativa), data_entrega e data_pagamento (inativas); nomeie os papéis; num visual, troque de "Data do Pedido" para "Data de Entrega" e veja o eixo mudar.
6. Limites e ressalvas — teto de papéis por modelo (MAX_RELATION_ROLES).
7. Dados de exemplo (sintéticos) — vendas com data_pedido=2026-07-01, data_entrega=2026-07-03, data_pagamento=2026-07-10.
8. Evidência — edição de papéis e detecção automática de grupos cobertas por suíte determinística.
9. Estado & maturidade — GA-candidato; fecha a lacuna "sem role-playing".

Relação M:N por ponte explícita#

Selo: GA-candidato

1. O que é — resolve uma relação N-N entre duas tabelas via uma tabela-ponte com FK para as duas, sem dupla contagem.
2. Quando usar — ex.: produtos ↔ promocoes (um produto em várias promoções; uma promoção com vários produtos) ligados por produto_promocao.
3. Como funciona — ao cruzar A → ponte → B, a medida do lado oposto é deduplicada (reduz a ponte a pares distintos antes de somar); medida que vive na própria ponte soma direto (o grão dela é a ponte).
4. Pré-requisitos — a tabela-ponte declarada na relação (BridgeSpec).
5. Como validar — some produtos.preco cruzando por produto_promocao e confirme que cada produto conta uma vez por valor de dimensão, não uma vez por linha da ponte.
6. Limites e ressalvas — exige ponte explícita declarada; N-N sem ponte é tratado como ambíguo.
7. Dados de exemplo (sintéticos) — produto_promocao: (10→"Julho"), (10→"Inverno"), (11→"Julho"); somar preço de produtos não deve triplicar o produto 10.
8. Evidência — resolução da ponte e semântica anti-dupla-contagem cobertas por suíte determinística.
9. Estado & maturidade — GA-candidato; fecha a lacuna "sem M:N".

Colunas calculadas, hierarquias e categoria de dado#

Selo: GA-candidato

1. O que é — colunas derivadas por fórmula (linha a linha), hierarquias de níveis para drill, e categoria de dado (ex.: geografia/UF) por coluna.
2. Quando usar — criar margem = receita - custo como coluna; montar a hierarquia Região > Estado > Cidade para drill; marcar filiais.uf como UF para os mapas.
3. Como funciona — colunas calculadas encadeiam com anti-ciclo (profundidade limitada); hierarquias definem a ordem de drill; a categoria de dado orienta visuais (mapas) e formatação. Há sort-by-column (ordenar mês pelo número).
4. Pré-requisitos — colunas de origem no modelo.
5. Como validar — crie a hierarquia filiais.regiao > filiais.uf > filiais.cidade, jogue num visual de barras e use o botão de drill para descer um nível.
6. Limites e ressalvas — colunas calculadas são avaliadas na materialização; ciclos são barrados por limite de profundidade.
7. Dados de exemplo (sintéticos) — filiais: (SP · Sudeste · São Paulo), (RJ · Sudeste · Rio de Janeiro), (MG · Sudeste · Belo Horizonte).
8. Evidência — hierarquias, sort-by-column, categoria de dado e colunas calculadas cobertas por suíte determinística.
9. Estado & maturidade — GA-candidato.

Calendários configuráveis (fiscal, 4-4-5, fuso, locale)#

Selo: GA-candidato

1. O que é — dimensão de calendário configurável: ano fiscal, 4-4-5 (varejo), fuso e locale pt-BR.
2. Quando usar — empresa cujo ano fiscal não começa em janeiro, ou que fecha em períodos 4-4-5 de varejo; base da inteligência de tempo (YTD etc.).
3. Como funciona — trabalha com data civil (nunca UTC), evitando o bug do fechamento das 22h de 31/12. Ano fiscal é rotulado pelo ano civil em que começa; 4-4-5 usa a regra "closest" (NRF) e a 53ª semana vai inteira para o último período. semana/diaSemana espelham o EXTRACT do datalake para paridade motor puro ↔ SQL.
4. Pré-requisitos — configurar início do ano fiscal e/ou modo 4-4-5 e fuso.
5. Como validar — configure ano fiscal iniciando em 01/04; confirme que ano fiscal 2026 cobre 01/04/2026 → 31/03/2027 num visual por período.
6. Limites e ressalvas — locale vem de tabela fixa (não Intl) para garantir bytes idênticos entre motor e SQL; novo idioma exige nova tabela.
7. Dados de exemplo (sintéticos) — venda em 31/12/2025 22:00 (fuso America/Sao_Paulo) cai no ano/período civil correto, não no ano seguinte.
8. Evidência — calendário (motor puro) e sua tradução para SQL cobertos por suíte determinística, com paridade motor puro ↔ SQL verificada.
9. Estado & maturidade — GA-candidato.

Modelo semântico centralizado por workspace (releases imutáveis)#

Selo: Preview

1. O que é — a definição de tabelas/relações/medidas pode viver uma vez por workspace, com releases imutáveis versionados por checksum, consumidos por N dashboards por referência.
2. Quando usar — quando vários dashboards precisam da mesma definição canônica (a mesma "receita líquida" em todo lugar).
3. Como funciona — o editor escreve no rascunho (draftJson); publicar congela uma cópia em release (version = max+1, checksum sha256). Anti-IDOR: toda query filtra workspaceId; releases não têm update/delete (publicar de novo gera versão nova). Auditado.
4. Pré-requisitos — workspace ativo; papel de dono/admin para publicar.
5. Como validar — publique um modelo, confirme que ganha version e checksum; edite o rascunho e publique de novo — deve criar version+1 sem alterar a anterior.
6. Limites e ressalvas — o "wiring" que faz os dashboards consumirem a versão central por referência é evolução em andamento; por isso Preview (não GA-candidato). O conteúdo do modelo é JSON opaco nesta camada.
7. Dados de exemplo (sintéticos) — release v1 (checksum sha256:…) com a medida central "Receita"; v2 adiciona "Ticket médio".
8. Evidência — armazenamento de releases, governança (releases imutáveis) e vínculo dashboard↔modelo cobertos por suíte determinística.
9. Estado & maturidade — Preview; falta consolidar o consumo por referência em todos os dashboards e a validação humana ponta a ponta.

Estado & evidência: capacidades acima derivadas da matriz de estados do produto (teto Preview). O SQL do modelo é fixado pelo conjunto de testes de referência, com resultado idêntico a cada execução. Execução no datalake de produção é NÃO MEDIDO nesta documentação (depende do datalake configurado). Nenhum recurso é GA de produto.