Diagnóstico visual e erros comuns

Selo de estado: Preview (teto atual do produto) · Curso ACD-310 — Modelo semântico e modelagem dimensional · Aula 10 de 10 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai diagnosticar e corrigir os três defeitos mais comuns de um modelo semântico: chave órfã, chave nula e ambiguidade de propagação.

Vídeo#

Identificador no manifesto: acd-310-10-diagnostico-de-relacoes · duração-alvo 6 min · tela do produto: /dashboards.

Roteiro:

00:00–01:00 — Por que "o visual não bate" quase sempre é um dos três defeitos · tela: /dashboards/[id] (visual com número suspeito)
01:00–02:30 — Chave órfã: vendas.produto_id sem par em produtos.id · tela: /dashboards/[id] (diagnóstico visual de relações)
02:30–03:30 — Chave nula: linhas de vendas sem filial_id preenchido · tela: /dashboards/[id] (contagem de linhas não casadas)
03:30–05:00 — Ambiguidade: dois caminhos de propagação entre o mesmo par de tabelas · tela: /dashboards/[id] (aviso de ciclo/ambiguidade)
05:00–06:00 — Método geral de diagnóstico: isolar dado × modelo × fórmula × visual · tela: /dashboards/[id] (checklist de isolamento)

Conteúdo#

Esta aula fecha o curso revisitando, de um único lugar, os defeitos que as aulas 2 a 9 já mencionaram de passagem — agora como diagnóstico, não como conceito novo. A referência de apoio é o catálogo Troubleshooting: modelo, fórmula e visual, e a capacidade por trás da tela é o diagnóstico visual de relações, coberta por um corpus de casos de borda testado.

Os três defeitos mais comuns

Defeito	O que é	Sintoma típico	Correção
Chave órfã	Um valor de chave no fato que não tem par na dimensão (ex.: `vendas.produto_id = 99` mas `produtos` não tem `id = 99`).	A linha "desaparece" de visuais agrupados pela dimensão, mas aparece em totais que não cruzam a dimensão.	Corrigir a origem do dado (pipeline/Silver) ou adicionar o produto faltante na dimensão.
Chave nula	A coluna-chave do fato está vazia para algumas linhas.	Essas linhas ficam fora de qualquer corte pela dimensão correspondente, mas entram em `SOMA`/`CONT` gerais.	Tratar o nulo na origem (ver Qualidade e quarentena) antes de chegar ao Gold.
Ambiguidade de propagação	Dois caminhos de filtro possíveis entre o mesmo par de tabelas (ex.: duas relações bidirecionais formando um ciclo).	O modelo recusa a configuração, em vez de deixar o significado indefinido.	Desativar um dos caminhos ou trocar um deles para direção single — ver aula 5.

Note a diferença de postura entre os três: órfã e nula são defeitos de dado que o modelo deixa passar (porque não há nada "errado" na estrutura, só no conteúdo); ambiguidade é um defeito de estrutura que o modelo recusa de propósito, como você já viu na aula 5.

Diagnóstico geral: isole antes de corrigir

Quando um número "não bate", a pergunta certa não é "qual é o erro", é "em qual camada está o erro":

É do dado (origem/pipeline)? Reproduza com um filtro mínimo e confira se a linha suspeita existe na origem.
É do modelo (referência)? Confirme no diagrama que a coluna/chave citada existe com o nome esperado — um erro de digitação na chave de uma relação produz exatamente o sintoma de chave órfã.
É da fórmula (sintaxe/contexto de filtro)? Veja a mensagem do editor de fórmula — erros de sintaxe e de contexto aparecem em português, não como um código genérico.
É do visual (layout/filtro)? Confirme se algum filtro do dashboard está recortando mais do que você esperava.

Nota

O comportamento do motor de BI é congelado por um conjunto de testes de referência: se um número muda de um dia para o outro, a causa quase sempre é que os dados mudaram — não que a fórmula ficou diferente. Antes de suspeitar do motor, confirme a origem do dado.

Como isso aparece no produto

O diagnóstico visual de relações vive no editor do dashboard (/dashboards/[id]), junto ao diagrama do modelo: ele sinaliza chaves sem par, contagens de linhas não casadas e, quando aplicável, o aviso de ciclo/ambiguidade com o caminho completo — a mesma informação que a aula 8 mostrou para dependência de medidas, agora aplicada a relações.

Ligando com o resto do curso

O bloqueio de fan-out (aula 4) não é um dos três defeitos desta aula, mas tem a mesma filosofia: o produto prefere recusar/avisar a entregar um número errado em silêncio.
A ambiguidade é a mesma que a aula 5 descreveu para filtro bidirecional — aqui você aprende a reconhecer o sintoma e corrigir, não só a causa.
Um modelo bem diagnosticado é, também, um modelo mais seguro para a IA citar (aula 1): menos ambiguidade estrutural significa menos chance de a IA confundir qual caminho usar.

Erros comuns ao diagnosticar

Culpar a fórmula quando o problema é a chave. Uma fórmula sintaticamente perfeita ainda produz números errados se a relação que ela depende tiver chaves órfãs ou nulas.
Tentar "forçar" a ambiguidade em vez de resolvê-la. Não existe uma forma de contornar a recusa sem efetivamente desfazer um dos caminhos conflitantes — a aula 5 mostra como.
Não isolar com um filtro mínimo antes de investigar. Tentar diagnosticar um dashboard inteiro de uma vez mistura sintomas de camadas diferentes.

Faça você mesmo#

No workspace de treino Aurora Varejo (abra /dashboards no console, editor de um painel, diagrama do modelo):

Insira (ou identifique, se já existir no dataset de treino) uma linha de vendas com um produto_id que não existe em produtos — uma chave órfã proposital.
Observe o diagnóstico visual de relações apontando a chave sem par.
Confirme o sintoma num visual agrupado por produtos.categoria: a linha órfã não aparece ali, mas aparece num KPI de total geral.
Corrija adicionando o produto faltante à dimensão (ou removendo a linha órfã), e confirme que o diagnóstico limpa o aviso.
Repita o exercício com uma linha de vendas sem filial_id preenchido, e observe como ela some de um visual "receita por filial", mas continua no total geral.
Se o seu modelo tiver uma relação bidirecional (aula 5), tente ativar um segundo caminho bidirecional entre o mesmo par de tabelas e confirme a recusa por ambiguidade.

Você terminou quando conseguir provocar os três defeitos de propósito, reconhecer o sintoma de cada um sem ajuda e corrigi-los de volta ao estado limpo.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

suporte/troubleshooting-modelo-formula-visual

Capacidades ensinadas#

C05.6 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".