Aba Expressões (Fórmulas Calculadas)

A aba Expressões permite criar métricas e colunas calculadas que combinam dados de diferentes Tabelas ou aplicam lógica de negócio personalizada. É nela que dados brutos se transformam em indicadores de desempenho (KPIs), percentuais, categorizações e outras métricas avançadas.

TIP

Utilize Expressões para cálculos que dependem de mais de uma Tabela. Para cálculos simples dentro de uma única Tabela, prefira criar colunas calculadas diretamente no HorusDW — assim a métrica ficará disponível para todas as Aplicações.

---

🖥️ Visão Geral da Interface

A interface de Expressões é composta por:

1. Barra de Ferramentas — Busca, filtros por tipo/comportamento, ordenação e modo desenvolvedor
2. Lista de Expressões — Tabela com todas as Expressões criadas, exibindo label, tipo, comportamento e máscara
3. Janela de Edição — Modal que abre ao criar ou editar uma Expressão, com duas abas: Editor e Documentação

Recursos da Lista

Recurso	Descrição
Busca	Filtra por label, código da Expressão ou descrição breve
Filtro por Tipo	Número, Texto ou Data
Filtro por Comportamento	Medida (agrega valores) ou Agrupador (categoriza dados)
Ordenação	Por nome (A-Z), recentes ou tipo
Modo Desenvolvedor	Exibe o código SQL inline na lista para visualização rápida

---

➕ Criando uma Nova Expressão

Manualmente

1. Clique no botão "Nova Expressão" (botão azul localizado no canto inferior direito da página)
2. Na janela que abre, preencha os campos na aba Editor
3. Opcionalmente, documente a Expressão na aba Documentação
4. Clique em Salvar Expressões (botão azul localizado no canto superior direito da página, ícone de disquete)

🤖 Com Inteligência Artificial

1. Clique no botão "Gerar Automaticamente"
2. Preencha:
   • Nome: Como a Expressão será chamada
   • Tipo de Dado: Número, Data ou Texto
   • Comportamento: Medida ou Agrupador
   • Modelo de IA: Selecione o modelo desejado (GPT-4, Claude, etc.)
   • Descrição: Explique em linguagem natural o que deve ser calculado
3. Clique em Gerar
4. A janela de edição abrirá com a Expressão gerada para revisão e ajuste

---

📝 Campos da Expressão

Aba Editor

Campo	Descrição	Valores
Label	Nome de exibição da Expressão	Texto livre
Descrição Breve	Explicação curta do propósito (máx. 150 caracteres)	Texto livre
Tipo	Tipo de dado retornado	Número, Data, Texto
Comportamento	Como a Expressão se comporta	Medida (agrega valores) ou Agrupador (categoriza dados)
Máscara	Formatação do valor (apenas para Número)	Moeda, Porcentagem, Decimais, etc.
Código	Fórmula SQL da Expressão	Editor Mônaco com autocomplete

NOTE

A Descrição Breve é exibida na lista de Expressões e serve para documentar rapidamente o propósito da Expressão. É um recurso interno para desenvolvedores, não exibido para usuários finais da Aplicação.

Aba Documentação

A aba Documentação oferece um editor de texto rico (WYSIWYG) para documentar a Expressão em detalhes:

• Explique a lógica de negócio por trás do cálculo
• Documente dependências e premissas
• Registre decisões de implementação
• Adicione exemplos de uso

IMPORTANT

A documentação é um recurso interno para desenvolvedores. Ela não é exibida para usuários finais, mas é essencial para manter o projeto organizado e facilitar manutenções futuras.

🎭 Máscaras Disponíveis para Números

Máscara	Exemplo
Número Inteiro	1.234
Moeda (BRL)	R$ 1.234,56
Moeda (USD)	$ 1,234.56
Moeda (GBP)	£ 1,234.56
Porcentagem	12,34%
1 a 4 decimais	1.234,5678
Segundos	3h 20m 10s
Minutos	02:30 (180 minutos)
Tamanho de Arquivo	1,5 GB

---

📐 Sintaxe de Fórmulas

Referenciando Colunas e Expressões

O que referenciar	Sintaxe	Exemplo
Coluna de Tabela	[Tabela]."Coluna"	[Fato Vendas]."VALOR_TOTAL"
Expressão de Tabela	[Tabela].[Expressão]	[Funcionários].[Tempo de Casa]
Outra Expressão	["Nome da Expressão"]	["Faturamento Realizado"]

Funções SQL Disponíveis

O sistema utiliza Apache Doris SQL, que suporta:

-- Agregações
SUM(...), COUNT(...), AVG(...), MIN(...), MAX(...), COUNT(DISTINCT ...)

-- Operadores matemáticos
+, -, *, /

-- Lógica condicional
CASE WHEN ... THEN ... ELSE ... END

Exemplos Práticos

Soma simples:

SUM([Fato Vendas]."VALOR_TOTAL")

Reutilizando Expressões:

["Faturamento Realizado"] / ["Meta de Faturamento"]

Categorização com CASE:

CASE 
    WHEN [Vendas]."VALOR" > 1000 THEN 'Alto'
    WHEN [Vendas]."VALOR" > 500 THEN 'Médio'
    ELSE 'Baixo'
END

---

🔧 Recursos Avançados

🔀 Relacionamentos Secundários com use()

Utilize use() quando for necessário analisar dados usando uma chave de Relacionamento diferente da padrão definida no Modelo de Dados.

IMPORTANT

Para utilizar use(), é necessário primeiro configurar o Relacionamento Alternativo na aba Tabelas. A coluna alternativa deve estar cadastrada como Relacionamento Secundário entre as duas Tabelas.

Sintaxe:

use([TabelaReferência], [TabelaDados].COLUNA_ALTERNATIVA) EXPRESSÃO

Parâmetros:

• TabelaReferência: A Tabela de Dimensão com a qual deseja se relacionar (Calendário, Filial)
• TabelaDados.COLUNA_ALTERNATIVA: A coluna da Tabela de Fatos cadastrada como Relacionamento Secundário

Como configurar:

1. Acesse a aba Tabelas
2. Selecione o Relacionamento entre as duas Tabelas
3. Clique em "+ Adicionar Chave" para incluir colunas alternativas
4. O primeiro Relacionamento é o padrão; os demais ficam disponíveis para use()

Exemplo — Análise pela data de fechamento ao invés de data de abertura:

use([Calendário], [Oportunidades].DATA_GANHO) SUM([Oportunidades].VALOR)

Neste exemplo, ao invés de utilizar a coluna padrão de data das Oportunidades, o sistema relacionará os dados pela coluna DATA_GANHO, permitindo analisar o valor das oportunidades pela data em que foram ganhas.

---

📊 Expressões Analíticas com ${...}

Utilize Expressões Analíticas quando for necessário calcular valores com filtros diferentes dos aplicados na visualização. Isso é essencial para comparações temporais (ano anterior, mês anterior) ou cálculos de participação.

Sintaxe:

${ EXPRESSÃO, FILTRO1, FILTRO2, ... }

Componentes:

• EXPRESSÃO: O cálculo a ser realizado (SUM([Vendas]."VALOR"))
• FILTROS: Condições que substituem os filtros visuais para esta Expressão

Operadores suportados nos filtros:

Operador	Exemplo
=	[Tabela]."Coluna" = 'valor'
!=	[Tabela]."Coluna" != 'valor'
IN	[Tabela]."Coluna" IN ('a', 'b', 'c')
NOT IN	[Tabela]."Coluna" NOT IN ('x', 'y')
LIKE	[Tabela]."Coluna" LIKE '%texto%'
NOT LIKE	[Tabela]."Coluna" NOT LIKE '%excluir%'
>, <, >=, <=	[Tabela]."Coluna" > 100
BETWEEN	[Tabela]."DATA" BETWEEN '2024-01-01' AND '2024-12-31'

---

Lendo Filtros Aplicados pelo Usuário

Dentro de Expressões Analíticas, é possível ler os valores dos filtros aplicados na visualização utilizando a sintaxe <...>:

Sintaxe básica:

<[Tabela]."Coluna", valor_padrão>

Se o usuário aplicou um filtro na coluna especificada, retorna o valor filtrado. Caso contrário, retorna o valor_padrão.

Para campos de data com intervalo:

Modificador	Descrição	Exemplo
:START	Início do período filtrado	<[Calendário]."DATA":START, CURRENT_DATE>
:END	Fim do período filtrado	<[Calendário]."DATA":END, CURRENT_DATE>
(sem modificador)	Valor exato do filtro	<[Dim Filial]."NOME", 'Todas'>

Como funciona com diferentes tipos de filtros:

• Filtro BETWEEN: :START retorna a data inicial, :END retorna a data final
• Filtro RELATIVE ("Últimos 30 dias"): Calcula as datas automaticamente
• Filtro IN com datas: :START retorna a menor data, :END retorna a maior
• Sem filtro aplicado: Retorna o valor padrão especificado

---

📈 Exemplos de Expressões Analíticas

Vendas do mesmo período no ano anterior:

${
    SUM([Fato Vendas]."Valor Total"),
    [Calendário]."DATA" BETWEEN 
        ADDYEARS(<[Calendário]."DATA":START, CURRENT_DATE>, -1) 
        AND 
        ADDYEARS(<[Calendário]."DATA":END, CURRENT_DATE>, -1)
}

Acumulado do ano (YTD):

${
    SUM([Fato Vendas]."Valor Total"),
    [Calendário]."DATA" BETWEEN 
        YEARSTART(<[Calendário]."DATA":START, CURRENT_DATE>) 
        AND 
        <[Calendário]."DATA":END, CURRENT_DATE>
}

Vendas do mês anterior:

${
    SUM([Fato Vendas]."Valor Total"),
    [Calendário]."DATA" BETWEEN 
        MONTHSTART(ADDMONTHS(<[Calendário]."DATA":START, CURRENT_DATE>, -1)) 
        AND 
        MONTHEND(ADDMONTHS(<[Calendário]."DATA":END, CURRENT_DATE>, -1))
}

Variação percentual ano a ano:

(
    SUM([Fato Vendas]."Valor Total") 
    - 
    ${
        SUM([Fato Vendas]."Valor Total"),
        [Calendário]."DATA" BETWEEN 
            ADDYEARS(<[Calendário]."DATA":START, CURRENT_DATE>, -1) 
            AND 
            ADDYEARS(<[Calendário]."DATA":END, CURRENT_DATE>, -1)
    }
) 
/ 
${
    SUM([Fato Vendas]."Valor Total"),
    [Calendário]."DATA" BETWEEN 
        ADDYEARS(<[Calendário]."DATA":START, CURRENT_DATE>, -1) 
        AND 
        ADDYEARS(<[Calendário]."DATA":END, CURRENT_DATE>, -1)
}

---

📅 Funções de Data Disponíveis

Estas funções são utilizadas dentro de Expressões Analíticas para manipular datas:

Funções de Adição/Subtração

Função	Descrição	Exemplo
ADDDAYS(data, dias)	Adiciona dias em data	ADDDAYS(TODAY(), 7)
ADDMONTHS(data, meses)	Adiciona meses em data	ADDMONTHS(TODAY(), -1)
ADDYEARS(data, anos)	Adiciona anos em data	ADDYEARS(TODAY(), -1)
SUBDAYS(data, dias)	Subtrai dias da data	SUBDAYS(TODAY(), 30)
SUBMONTHS(data, meses)	Subtrai meses da data	SUBMONTHS(TODAY(), 3)
SUBYEARS(data, anos)	Subtrai anos da data	SUBYEARS(TODAY(), 1)

Funções de Início/Fim de Período

Função	Descrição	Exemplo
MONTHSTART(data)	Primeiro dia do mês	MONTHSTART(TODAY()) → 2024-12-01
MONTHEND(data)	Último dia do mês	MONTHEND(TODAY()) → 2024-12-31
YEARSTART(data)	Primeiro dia do ano	YEARSTART(TODAY()) → 2024-01-01
YEAREND(data)	Último dia do ano	YEAREND(TODAY()) → 2024-12-31
QUARTERSTART(data)	Primeiro dia do trimestre	QUARTERSTART(TODAY())
QUARTEREND(data)	Último dia do trimestre	QUARTEREND(TODAY())
WEEKSTART(data)	Primeiro dia da semana (domingo)	WEEKSTART(TODAY())
WEEKEND(data)	Último dia da semana (sábado)	WEEKEND(TODAY())

Funções de Extração

Função	Descrição	Retorno
DAYOFWEEK(data)	Dia da semana	0 (domingo) a 6 (sábado)
DAYOFMONTH(data)	Dia do mês	1 a 31
MONTH(data)	Mês do ano	1 a 12
YEAR(data)	Ano	Ex: 2024
DATEDIFF(data1, data2)	Diferença em dias entre datas	Número inteiro

Constantes e Funções Gerais

Função/Constante	Descrição
TODAY()	Data de hoje
CURRENT_DATE	Data atual (constante)
MIN(valor1, valor2, ...)	Menor valor entre os argumentos
MAX(valor1, valor2, ...)	Maior valor entre os argumentos

TIP

FIRSTDAYOFMONTH e LASTDAYOFMONTH são aliases para MONTHSTART e MONTHEND respectivamente.

---

✅ Validações

O editor valida automaticamente:

• Referências inválidas — Colunas ou Expressões que não existem no modelo
• Campos obrigatórios — Label, Tipo e Fórmula devem estar preenchidos
• Expressões circulares — Uma Expressão não pode referenciar a si mesma

Erros aparecem em vermelho abaixo do campo com problema.

---

💡 Dicas de Uso

1. Utilize o autocomplete — O editor sugere Tabelas, colunas e Expressões durante a digitação
2. Teste incrementalmente — Crie Expressões simples primeiro, depois combine em Expressões mais complexas
3. Documente as Expressões — Utilize a aba Documentação para registrar a lógica de negócio
4. Adicione descrições breves — Facilita encontrar Expressões na busca e entender rapidamente seu propósito
5. Prefira reutilização — Crie Expressões básicas e combine-as em Expressões mais complexas
6. Atenção aos tipos — Certifique-se de que as colunas usadas em comparações são do tipo correto
7. Utilize o modo desenvolvedor — Ative para visualizar o código das Expressões diretamente na lista