Medidas, fórmulas e KPIs

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

Aqui você define os números: medidas reutilizáveis, a linguagem de fórmulas (estilo DAX, em português), grupos de cálculo, parâmetros "e se", KPIs e agrupamentos. Exemplos usam o workspace sintético Comércio Aurora Ltda.

Linguagem de fórmulas (DAX-like em português)#

Selo: GA-candidato

1. O que é — uma linguagem de fórmulas com nomes em português (SOMA, SE, ACUM_ANO, CLASSIFICAR) e aliases em inglês, com contexto de filtro e inteligência de tempo, comparável ao DAX.

2. Quando usar — criar medidas como "Receita YTD", "Variação vs ano anterior", "Ranking de produtos", "Participação no total".

3. Como funciona — parser próprio (tokenizer → AST, sem eval) e três avaliadores: agregado, linha-a-linha e compilação para SQL do datalake. São 102 funções em 7 categorias: matemática, estatística/agregação, lógica, texto, data, contexto de filtro (CALCULAR, TUDO, FILTRAR, REMOVER_FILTROS, iteradores SOMAX/MEDIAX, CLASSIFICAR, PROCV, VALOR_SELECIONADO, PRIMEIROS_N…) e inteligência de tempo (ACUM_ANO, MESMO_PERIODO_ANO_ANTERIOR, DESLOCAR_PERIODO, SALDO_FINAL…). Sintaxe BR: argumentos por ;, decimal com vírgula, VAR … RETORNAR, concatenação com &. Divisão por zero → VAZIO; avaliação preguiçosa no contexto de filtro; DATA − DATA dá erro didático pedindo DATADIF.

4. Pré-requisitos — colunas/medidas no modelo para referenciar.

5. Como validar — crie Receita = SOMA(vendas.valor) e Receita YTD = ACUM_ANO([Receita]; calendario.data); ponha as duas num visual por mês e confirme o acumulado subindo dentro do ano e zerando na virada.

6. Limites e ressalvas — é um DAX-like genuíno (contexto de filtro real), não é DAX completo: não há tabelas virtuais no motor e a relação vive no SQL. Não afirmamos paridade total com DAX.

7. Dados de exemplo (sintéticos)

   mes	Receita	Receita YTD
   2026-01	1000	1000
   2026-02	1500	2500

8. Evidência — motor de fórmulas coberto por ampla suíte determinística (contexto de filtro, ranking, inteligência de tempo, matriz, calendário fiscal, transição) e congelado pelo conjunto de testes de referência, com resultado idêntico a cada execução.

9. Estado & maturidade — GA-candidato; motor fixado pelo conjunto de testes de referência, com resultado idêntico a cada execução.

Editor de fórmulas (autocomplete + validação ao vivo)#

Selo: GA-candidato

1. O que é — editor com autocomplete, validação ao vivo e ajuda/exemplo por função.
2. Quando usar — ao escrever qualquer medida ou coluna calculada.
3. Como funciona — valida enquanto você digita, com FormulaError em pt-BR; trava erros clássicos (ex.: "coluna solta em medida agregada").
4. Pré-requisitos — nenhum além do modelo.
5. Como validar — comece a digitar CLASS… e confirme a sugestão CLASSIFICAR; escreva uma medida inválida e veja o erro em português.
6. Limites e ressalvas — a validação é sintática/semântica local; o custo real da query só aparece na execução.
7. Dados de exemplo (sintéticos) — Ticket médio = DIVIDIR([Receita]; CONT(vendas.id)).
8. Evidência — motor de validação de fórmulas (erros em pt-BR) coberto por suíte determinística; a renderização do editor não tem teste visual.
9. Estado & maturidade — GA-candidato (motor de validação testado; a renderização DOM do editor não tem teste visual).

Como o editor de fórmula aparece na tela

O editor abre por cima do painel, com espaço para a fórmula, a busca e a prévia. Ele é o mesmo para Nova medida (fórmula), Nova coluna calculada e Editar fórmula (ver Campos, medidas e variáveis).

• O nome técnico (só letra, número e _), pelo qual outra fórmula chama esta, e o apelido no cartão, que pode ter espaço, acento e %.
• Como o número aparece: 0,00 · Número, mil/mi · Número curto, % · Percentual, R$ · Moeda, R$ mil/mi · Moeda curta.
• "Buscar função…" procura nas funções por categoria. Cada função mostra também o nome equivalente do Power BI (por exemplo, ARRED e ROUND) — o motor aceita os dois.
• Medidas que já existem ficam à mão para usar na fórmula.
• A prévia usa o mesmo formato do cartão: o que você vê é o que vai aparecer.
• Salvar, Cancelar e, numa fórmula existente, Excluir (com confirmação).

ampliar

A barra de fórmulas

Em edição, logo abaixo da barra de menus, fica uma barra da largura da tela. Clique num campo da lista Valores do painel do visual e ela mostra de onde ele vem: tabela.coluna, a fórmula da medida, ou o aviso de que o dado ainda não chegou. Sem campo escolhido, ela diz "Clique num campo da lista de valores para ver de onde ele vem."

• Arraste a borda de baixo para esticar a barra e ler fórmulas longas.
• Duplo clique na borda volta ao tamanho padrão.
• O × limpa.

ampliar

Biblioteca de medidas centrais#

Selo: GA-candidato

1. O que é — medidas declaradas uma vez no modelo e reutilizadas por referência (outra medida cita MEDIDA('Receita'); o widget cita measureId).
2. Quando usar — para acabar com "ticket médio" digitado em 10 widgets divergindo em silêncio.
3. Como funciona — CRUD com relatório de impacto (quem usa a medida), grafo de dependência e detecção de ciclo com o caminho completo; pastas, descrição, selo certified, hidden. Limpeza no caminho de escrita (cleanModelForSave).
4. Pré-requisitos — modelo do dashboard (ou modelo central do workspace).
5. Como validar — crie a medida central "Receita"; use-a em três visuais; edite a fórmula e confirme, no relatório de impacto, os três visuais listados antes de salvar.
6. Limites e ressalvas — a biblioteca entre dashboards depende do modelo central por workspace (ver Modelo semântico, em Preview).
7. Dados de exemplo (sintéticos) — "Receita" (usada em 3 widgets) → "Ticket médio" que cita MEDIDA('Receita').
8. Evidência — biblioteca de medidas e relatório de impacto (grafo de dependência + detecção de ciclo) cobertos por suíte determinística.
9. Estado & maturidade — GA-candidato; fecha a lacuna "medidas não centralizadas" apontada na auditoria inicial.

Grupos de cálculo (calculation groups)#

Selo: GA-candidato

1. O que é — um grupo (ex.: "Tempo" com itens Realizado / Ano anterior / YTD) que se aplica a qualquer medida sem reescrever a fórmula.
2. Quando usar — oferecer "Realizado × Ano anterior × YTD" para todas as medidas de um seletor único.
3. Como funciona — MEDIDA no item é substituída pela medida-base. Quando dois grupos se aplicam à mesma medida (ex.: "Tempo" × "Moeda"), a ordem segue precedência determinística: maior precedência = função mais externa. Erros nunca são escolha silenciosa: grupo/item inexistente, repetido ou empate de precedência são recusados (como no Power BI).
4. Pré-requisitos — pelo menos uma medida-base e o grupo declarado.
5. Como validar — crie os grupos "Tempo" e "Moeda" com precedências diferentes; aplique ambos a "Receita" e confirme o aninhamento na ordem esperada; force precedências iguais e veja a recusa por empate.
6. Limites e ressalvas — só montagem de texto (nada é avaliado aqui); o conjunto de testes de referência permanece idêntico.
7. Dados de exemplo (sintéticos) — "Tempo"[YTD] × "Moeda"[USD] sobre "Receita".
8. Evidência — grupos de cálculo (precedência determinística, recusa de empate) cobertos por suíte determinística e congelados pelo conjunto de testes de referência.
9. Estado & maturidade — GA-candidato.

Parâmetros (campo, medida e "e se"/what-if)#

Selo: GA-candidato

1. O que é — parâmetros centralizados de três tipos: field (troca qual campo o visual usa), measure (escolhe qual medida central mostrar) e what-if (um número nomeado, "e se o desconto fosse X%").
2. Quando usar — um seletor "ver por: receita · pedidos · ticket" que substitui três visuais quase idênticos; ou simular cenários de desconto.
3. Como funciona — declarados uma vez no modelo com id estável p…; a seleção do leitor viaja na URL/bookmark (não fica no modelo), então renomear o parâmetro não quebra o estado salvo.
4. Pré-requisitos — campos/medidas para oferecer; para what-if, a medida que consome o número.
5. Como validar — crie um field parameter "Ver por" com [receita, pedidos, ticket] e confirme que trocar a opção muda a série do visual; compartilhe a URL e confirme que a escolha é restaurada.
6. Limites e ressalvas — um slicer de parâmetro não recorta linhas (troca campo/medida/valor); recorte de linha é dos outros slicers (ver Filtros e interações).
7. Dados de exemplo (sintéticos) — what-if desconto = 10% aplicado em "Receita líquida = [Receita] * (1 - desconto)".
8. Evidência — parâmetros (field/measure/what-if) e sua aplicação ao visual cobertos por suíte determinística; a seleção do leitor viaja no estado da URL.
9. Estado & maturidade — GA-candidato.

KPIs no modelo#

Selo: GA

1. O que é — o KPI do modelo semântico: um valor-alvo embutido no indicador do painel, com direção e formatação.
2. Quando usar — quando o painel precisa mostrar "realizado contra alvo" no próprio visual.
3. Como funciona — o alvo vive no KPI (modelo semântico) e o visual desenha a comparação. Não depende de tela separada.
4. Limites e ressalvas — o KPI não dispara alerta por si; alertas ficam por visual — ver Exportação e distribuição.
5. Nota histórica — existiu uma tela Metas (scorecard) em /metas, com meta cadastrada à parte (alvo, prazo, responsável). Ela foi removida do produto em 26/09/2026; o acompanhamento de alvo hoje é o KPI do painel.

Agrupamento e binning#

Selo: GA-candidato

1. O que é — agrupar valores em faixas (por largura ou quantidade), listas ou clusters.
2. Quando usar — transformar ticket contínuo em faixas ("0-50", "50-100", "100+") ou agrupar cidades numa lista "Capitais".
3. Como funciona — faixas por largura/quantidade, agrupamento por lista e cluster, aplicáveis a dimensões do visual.
4. Pré-requisitos — a coluna a agrupar no modelo.
5. Como validar — crie faixas de vendas.valor por largura 50 e confirme os baldes num histograma.
6. Limites e ressalvas — binning é sobre o dado do snapshot/consulta do visual.
7. Dados de exemplo (sintéticos) — valores {30, 60, 120} → faixas {"0-50":1, "50-100":1, "100+":1}.
8. Evidência — agrupamento e binning (faixas, listas, clusters) cobertos por suíte determinística.
9. Estado & maturidade — GA-candidato.

Estado & evidência: motor de fórmulas, grupos de cálculo e medidas fixados por conjunto de testes de referência e ampla suíte determinística. Estados derivados da matriz de estados do produto (teto Preview). Execução no datalake de produção é NÃO MEDIDO. Nenhum recurso é GA de produto.