`;` e vírgula decimal, `VAR/RETORNAR`, branco honesto

Selo de estado: Preview (teto atual do produto) · Curso ACD-320 — Fórmulas pt-BR: de SOMA a CALCULAR · Aula 1 de 13 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai reconhecer sintaxe e o que difere do DAX.

Vídeo#

Identificador no manifesto: acd-320-01-sintaxe-brasileira · duração-alvo 6 min · tela do produto: /dashboards.

Roteiro:

Conteúdo#

Todo mundo que chega do Excel ou do Power BI já sabe escrever uma fórmula — o problema é que meio teclado vai parar no lugar errado nas primeiras tentativas aqui. Esta aula resolve isso antes de qualquer função: a sintaxe do motor de fórmulas do ingestia.bi, o que ela tem de igual ao DAX e o que ela muda de propósito.

Separador de argumentos: ;, não ,

No Excel/DAX em português o separador já costuma ser ;; em inglês costuma ser ,. Aqui a regra é fixa e não depende do idioma do seu Excel: todo argumento é separado por ;.

DIVIDIR(SOMA(valor); CONTD(pedido_id); 0)

Se você escrever com vírgula, o motor não "adivinha" — ele erra na hora, com uma mensagem de caractere inesperado:

SE(valor > 100, 1, 0)

Erro: Caractere inesperado: ",". A vírgula não separa argumento nenhum aqui — ela não existe na gramática da fórmula fora de um texto entre aspas.

Decimal com vírgula, milhar com ponto

Números seguem o padrão brasileiro: 0,33 é um terço, 1.234,56 é mil duzentos e trinta e quatro reais e cinquenta e seis centavos.

SOMA(valor) * 0,1

Isso vale só para números escritos na fórmula — uma coluna chamada valor continua sendo o que o dado tiver. A função TEXTO (aula 4) é quem formata o número de SAÍDA no padrão pt-BR para exibição.

Nomes de coluna: identificador simples, nunca tabela.coluna

Aqui está a diferença que mais pega quem vem de SQL ou de tutorial desatualizado: uma coluna é citada pelo nome simples, sem o nome da tabela na frente.

SOMA(valor)

SOMA(vendas.valor)

Erro: Caractere inesperado: ".". O ponto não é um operador da linguagem — o motor já sabe em qual tabela valor está porque ele opera sobre as linhas que o visual está mostrando, não sobre um catálogo de tabelas soltas. (Se você viu vendas.valor em algum material antigo, está desatualizado — ignore.)

A mesma regra vale para medidas: uma medida da biblioteca central é citada com MEDIDA('Nome') — nunca entre colchetes.

DIVIDIR(MEDIDA('Receita'); MEDIDA('Pedidos'))

DIVIDIR([Receita]; [Pedidos])

Erro: Caractere inesperado: "[". Colchetes são sintaxe do DAX/Power BI — aqui o nome de uma medida vai como texto entre aspas simples, argumento de MEDIDA(...). A aula 2 cria as medidas Receita e Pedidos na biblioteca; a partir daí qualquer fórmula do curso pode citá-las assim.

VAR … RETORNAR: nomear um valor pra não repetir a conta

Quando uma fórmula usa o mesmo cálculo duas vezes, declare uma variável — ela é calculada uma única vez, no contexto em que foi declarada, e todo uso dela depois reaproveita o mesmo valor:

VAR meta = 1000; RETORNAR DIVIDIR(SOMA(valor); meta)

Pode haver mais de um VAR em sequência, sempre terminando em RETORNAR (aceita o alias em inglês return):

VAR receita = SOMA(valor); VAR custo = SOMA(custo); RETORNAR DIVIDIR(receita - custo; receita)

Esqueceu o RETORNAR? O motor avisa exatamente o que falta, em português — nunca um erro genérico:

VAR meta = 1000; DIVIDIR(SOMA(valor); meta)

Erro guiado: "Depois dos VAR falta o RETORNAR — ex.: VAR meta = 1000; RETORNAR SOMA(receita) / meta".

Branco honesto: o motor nunca inventa um zero

Esta é a regra de design mais importante da linguagem, e ela difere do que muita planilha faz por padrão: quando falta dado para uma conta, o resultado é vazio (branco), não zero.

• Dividir por zero → vazio (não erro, não zero): DIVIDIR(100; 0; 0) dá 0 só porque você pediu explicitamente a alternativa 0 no 3º argumento — sem ela, 100 / 0 dá vazio.
• Um grupo sem nenhuma linha → a medida fica vazia, nunca aparece como "0" fingindo que o grupo não vendeu nada.
• SE sem o senão devolve vazio, não 0 nem FALSO.

Por quê isso importa: um zero inventado é indistinguível de um zero real ("vendeu zero") na tela — e isso já causou decisão errada em painel de BI desde sempre. Um branco é visualmente diferente e convida a perguntar "por que não há dado aqui?" em vez de aceitar um número que não existe.

Comparação com o DAX

A linguagem se inspira no DAX e mantém nomes em inglês como aliases (SUM funciona igual a SOMA), mas a sintaxe de superfície muda: separador ; sempre (o DAX varia por locale), decimal com vírgula sempre, coluna pelo nome simples (sem tabela), medida via MEDIDA('Nome') (não [Nome]). Quem já escreveu DAX vai reconhecer VAR/RETURN — aqui é VAR/RETORNAR, com a mesma regra de uma avaliação só por variável.

Estado da capacidade

O sistema de tipos do motor (C06.1) está em Preview — teto atual do produto. O parser é determinístico e sem eval: todo erro de sintaxe tem mensagem em português, e a mesma fórmula sempre compila para a mesma árvore.

Faça você mesmo#

No workspace de treino Aurora Varejo (abra /dashboards no console):

1. Abra qualquer dashboard de treino e entre no editor de fórmulas (crie uma medida nova ou edite uma coluna calculada).
2. Digite SOMA(valor,custo) — sem salvar — e leia o erro de caractere inesperado.
3. Corrija para SOMA(valor) e confirme que valida.
4. Escreva VAR meta = 1000; RETORNAR DIVIDIR(SOMA(valor); meta) e confirme que valida.
5. Experimente DIVIDIR(SOMA(valor); 0) sem 3º argumento e observe que o resultado fica vazio, não 0.

Você terminou quando a fórmula VAR meta = 1000; RETORNAR DIVIDIR(SOMA(valor); meta) validar sem erro no editor e você conseguir explicar, com suas palavras, por que vendas.valor e [Receita] não compilam.

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#

• formulas/README

Capacidades ensinadas#

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