Expressions
Expressions allows to manually create and edit Filters rules by using programming language. Important: After manually editing the expression the others operators cannot be used until you clear all the filters;
Contents
Basic expression structures
Value Operands
The value operands are values from a data type that are used in expressions as variables.
- Value type operands: Are numeric values of the float type (Real numbers domain). These values allow the use of a integer and a fraction part, separated by the dot character (decimal separator). Examples: 1, 1.05, 2.55
- Operando do texto
São dados do tipo literal de texto
Estes operandos permitem a utilização de campos de cadeias de caracteres (ou strings), sendo que o delimitador de string é o caractere de aspas-simples (').
Exemplos: 'Fulano de Tal', 'RS'
- Operando do tipo data
Valores que expressam qualquer data.
É possível determinar uma string que convertida para um literal de data, sendo que o delimitador é caractere de aspas-simples, o separador de campos é o caractere barra (/) e o formato suportado por padrão é 'dd/MM/yyyy' (dia, mês e ano).
Exemplos: '01/01/2011', '29/02/2000'
- Operando do tipo booleano
Representam valores do tipo boolean ou verdadeiro e falso (true e false)
São comumente utilizados em expressões relacionais para validação de uma condição ou teste como verdadeiro ou falso. Assim como os numéricos, não possuem delimitadores de valor.
Exemplos: true e false
- Operando do tipo identificador
Operandos que representam algum campo ou identificador variável da expressão.
São muito úteis para fazer referência a outros de um componente. Delimitados por aspas-duplas (").
Exemplo: "F12_01", "Data do Pedido"
No caso da nova geração (SadigNG), estes campos são utilizados para obter campos de um DataMart ou dimensão específica, como: "Data.mês" ou "Vendas.Vendedor"
- Operando do tipo variável do sistema
São operandos que representam variáveis pré-definidas do sistema e que não podem ser confundidas com textos ou identificadores
Estes operandos são substituídos em tempo de execução por valores ou identificações pré-determinadas. São delimitados por aspas-duplas (") e tem como prefixo o caractere sustenido (#).
Até o momento, apenas dois valores são possíveis "#null" para indicar valores ou campos nulos e "#?", que funciona como coringa e é substituído em tempo de execução por algum valor (apenas para os produtos do SadigNG).
O valor é comumente utilizado em expressões para verificar de um campo do componente está nulo ou não.
- Operando de variável global
São operandos que representam variáveis globais ou valores pré-determinados ou computados antes de resolver a expressão.
Estes operandos são úteis para representar valores que relacionam várias linhas de dados ou expressões que devem estar prontos (pré-computados) para ser utilizados na expressão. São delimitados por aspas-duplas (") e precedidos pelo caractere arroba (@).
Exemplos: "@row", "@sum[F12_01]", "@prev[F12_01]"
Algumas variáveis globais pré-definidas no SadigPainéis:
"@row": indica o número da linha atual de um campo de expressão dentro de uma série de valores (numa tabela ou gráfico).
"@sum[<coluna>]": representa a soma dos dados das linhas de uma mesma coluna. Útil para cálculos do tipo participação individual.
"@avg[<coluna>]": representa a média dos dados das linhas de uma mesma coluna.
"@count[<coluna>]": conta a quantidade de linhas
"@min[<coluna>]": retorna o menor valores dentre todos os valores de uma coluna.
"@max[<coluna>]": retorna o maior valores dentre todos os valores de uma coluna.
"@prev[<coluna>]": retorna o valor da linha anterior para uma coluna. Útil para cálculos do tipo variação entre linhas.
Expressões aritméticas
São elementos de expressão que relacionam dois operandos (de valor ou de outra expressão) para compor uma expressão aritmética de soma, substração, multiplicação ou divisão.
- Soma (+)
Realiza a operação de soma entre dois operandos. Representada pelo caractere de soma (+). A sintaxe da expressão é: <expressão> + <expressão>
Exemplos: "F12_01" + "F12_02", "F12_01" + "F14_01", "F12_01" + 100.0, ("F12_01" - "F12_02") + "F14_01".
- Subtração (-)
Realiza a operação de subtração entre dois operandos. Representada pelo caractere de subtração ou hífen (-). A sintaxe da expressão é: <expressão> - <expressão>
Exemplos: "F12_01" - "F12_02", "F12_01" - "F14_01", "F12_01" - 100.0, ("F12_01" + "F12_02") - "F14_01".
- Multiplicação (*)
Realiza a operação de multiplicação entre dois operandos. Representada pelo caractere de multiplicação ou asterisco (*). A sintaxe da expressão é: <expressão> * <expressão>
Exemplos: "F12_01" * "F12_02", "F12_01" * "F14_01", "F12_01" * 100.0, ("F12_01" - "F12_02") * "F14_01".
- Divisão (/)
Realiza a operação de divisão entre dois operandos. Representada pelo caractere de divisão ou barra (/). A sintaxe da expressão é: <expressão> / <expressão>
Exemplos: "F12_01" / "F12_02", "F12_01" / "F14_01", "F12_01" / 100.0, ("F12_01" - "F12_02") / "F12_02".
- Obs.: Note que nas expressões aritméticas é possível relacionar dois operandos de valor, ou um operando de valor e um identificador (coluna de dados) ou quaisquer duas sub-expressões que resultem em um identificador ou um valor numérico.
Expressões relacionais
São elementos de expressão que relacionam dois operandos (de qualquer tipo ou de outra expressão) para compor uma expressão relacional, cujo o objetivo é avaliar dois operandos e resultar um resultado verdadeiro ou falso da relação entre os dois. Expressões relacionais são: igual (==), diferente (!=) maior que (>), menor que (<), maior ou igual a (>=) e menor ou igual a (<=). Geralmente, utilizadas em funções de decisão, como IF.
- Igual (==)
Realiza a operação de comparação de igualdade entre dois operandos. Representada pelos operador igual (==). A sintaxe da expressão é: <expressão> == <expressão>
Exemplos: "F12_01" == "F12_02", "F12_01" == "F14_01", "F12_01" == 100.0, ("F12_01" - "F12_02") == "F14_01".
- Diferente (!=)
Realiza a operação de comparação de diferença entre dois operandos. Representada pelos operador diferente (!=). A sintaxe da expressão é: <expressão> != <expressão>
Exemplos: "F12_01" != "F12_02", "F12_01" != "F14_01", "F12_01" != 100.0, ("F12_01" - "F12_02") != "F14_01".
- Maior que (>)
Retorna o resultado da comparação do primeiro operando em relação ao segundo, no caso se o primeiro é maior que o segundo. Representada pelo operador maior (>). A sintaxe da expressão é: <expressão> > <expressão>
Exemplos:IF("Data" > '01/01/2011';F12_01;0), IF(F12_01 > "@avg[F12_01]";'Acima';'Abaixo').
- Menor que (<)
Retorna o resultado da comparação do primeiro operando em relação ao segundo, no caso se o primeiro é menor que o segundo. Representada pelo operador menor (<). A sintaxe da expressão é: <expressão> < <expressão>
Exemplos:IF("Data" < DAY_FROM_TODAY(0);F12_01;0), IF(F12_01 < 1;1;F12_01).
- Maior ou igual a (>=)
Retorna o resultado da comparação do primeiro operando em relação ao segundo, no caso se o primeiro é maior ou igual ao segundo. Representada pelo operador maior-ou-igual(>=). A sintaxe da expressão é: <expressão> >= <expressão>
Exemplos:IF("Data" >= '01/01/2011';F12_01;0), IF(F12_01 >= "@avg[F12_01]";'Acima';'Abaixo').
- Menor ou igual a (<=)
Retorna o resultado da comparação do primeiro operando em relação ao segundo, no caso se o primeiro é menor ou igual ao segundo. Representada pelo operador menor-ou-igual(<=). A sintaxe da expressão é: <expressão> <= <expressão>
Exemplos:IF("Data" <= DAY_FROM_TODAY(0);F12_01;0), IF(F12_01 <= 1;1;F12_01).
Expressões lógicas
São elementos de expressão que agrupam dois operandos (do tipo booleano ou de outra expressão) para compor uma expressão lógica, cujo o objetivo é avaliar dois operandos booleanos num resultado verdadeiro ou falso da relação entre os dois. Expressões lógicas suportadas são: and (&&), or (||) e not (!). Geralmente, utilizadas em funções de decisão, como IF e em conjunto com expressões relacionais.
- And (&&)
Realiza a operação lógica de AND entre dois valores booleanos. Assim, os dois operandos devem ser verdadeiros para que o resultado da expressão seja verdadeiro. Representada pelos operador and (&&). A sintaxe da expressão é: <expressão> && <expressão>
Exemplos: IF(BETWEEN("Data", '01/01/2011', '31/12/2011') && (Vendedor == 'Fulano');F12_01;0), IF((F12_01!="#null") && (Data<DAY_FROM_TODAY(0));1;0).
- Or (||)
Realiza a operação lógica de OR entre dois valores booleanos. Assim, se um dos dois operandos é verdadeiro o resultado da expressão será verdadeiro. Representada pelos operador or (||). A sintaxe da expressão é: <expressão> || <expressão>
Exemplos: IF(BETWEEN("Data", '01/01/2011', '31/12/2011') || (Vendedor == 'Fulano');F12_01;0), IF((F12_01!="#null") || (Data<DAY_FROM_TODAY(0));1;0).
- Not (!)
Realiza a operação lógica de negação para um valor booleano. Assim, se o operador está verdadeiro, o not converte para falso (e vice-versa). Representada pelos operador not (!). A sintaxe da expressão é: ! <expressão>
Exemplos: IF(!BETWEEN("Data", '01/01/2011', '31/12/2011');F12_01;0).
Funções Auxiliares
As funções são tipos de elementos de expressão (ou seja operandos) que permitem que se execute qualquer computação possível sobre uma expressão, desde que, é claro, se implemente uma classe para cada objetivo. Atualmente, o framework de expressões possui diversas expressões implementadas. Elas são categorizadas em "Funções Básicas" e "Funções de Data".
Uma questão importante sobre as funções é que elas possuem parâmetros. Estes parâmetros possuem tipo e quantidade coerentes com a operação que a função implementa e, portanto, deve-se respeitar a ordem e os tipos de dados destes parâmetros para que a função funcione corretamente. Toda função possui uma identificação da sua operação principal e, dentro de parênteses, uma lista de parâmetros separados por ponto-e-vírgula (;). É possível também que uma função não tenha parâmetros. Sintaxe padrão das funções: nome_da_funcao([param1[;param2;...;paranN]]).
Funções Básicas
São funções padrão do sistema e implementam operações utilitárias básicas e a funcionalidade de alguns comandos de programação.
- Abs
Retorna o valor absoluto de um valor base. Sintaxe: ABS(<expressão>)
Aceita apenas um parâmetro e o tipo de dados que processa é um número.
Exemplo: ABS(F12_01-F12_02)
- Avg
Retorna a média de uma lista de valores. Sintaxe: AVG(<expressão1>;<expressão2>[;<expressão3>;...;<expressãoN>])
Aceita vários parâmetros e o tipo de dados que processa é um número.
Pode ser utilizada para retornar a média de valores entre colunas de uma mesma linha de uma tabela.
Exemplo: ABS(F12_01;F12_02;F12_03)
- Between
Verifica de um valor está dentro dos limites de valores parametrizados. Sintaxe: BETWEEN(<expressão_a_testar>;<expressão_lim_inferior>;<expressao_lim_superior>)
Exige exatamente três parâmetros (de qualquer tipo, desde sejam do mesmo tipo entre si) e o tipo que retorna é um booleano, verdadeiro caso o valor esteja dentro dos limites; falso, caso contrário.
Exemplos: BETWEEN("Data";'01/01/2011';'31/12/2011'), BETWEEN(F12_03;F12_01;F12_02)
- If then else
Faz um teste sobre uma expressão booleana e retorna um valor para o caso da expressão ser verdadeira e outro para o caso dela ser falsa. Sintaxe: IF(<expressão_teste>;<expressão_para_verdadeiro>;<expressão_para_falso>).
Exige exatamente três parâmetros uma expressão booleana e retorno de qualquer tipo, desde que seja o mesmo para as duas cláusulas.
Muito utilizada para testes lógicos para ter duas opções de execução de uma expressão.
Exemplos: IF(BETWEEN("Data";'01/01/2011';'31/12/2011');F12_01;0.0), IF("Região"=='SUL';F12_01;F12_01+F14_01), IF(F12_01==0;0;F12_01/"@sum[F12_01]")
- Log
Calcula o logaritmo de um número numa determinada base. Sintaxe: LOG(<expressão_número>[;<expressão_base>]).
No mínimo é no máximo dois parâmetros. Se apenas um elemento for passado por parâmetro, o algoritmo calcula logaritmo neperiano; caso o segundo seja informado, calcula logaritmo na respectiva base.
Exemplo: LOG(F12_01)
- Max
Retorna o maior entre dois números. Sintaxe: MAX(<expressão_valor1>;<expressão_valor1>);
Exatamente dois parâmetros são exigidos. Processa elemento numéricos e retorna um número.
Exemplo: F12_01/MAX(F14_01;100.0)
- Min
Retorna o menor entre dois números. Sintaxe: MIN(<expressão_valor1>;<expressão_valor1>);
Exatamente dois parâmetros são exigidos. Processa elemento numéricos e retorna um número.
Exemplo: F12_01/MIN(F14_01;100.0)
- Pow
Calcula a operação de potenciação. Sintaxe: POW(<expressão_base>[;<expressão_expoente>])
No mínimo um e no máximo dois parâmetros. Calcula a potenciação de um número dado um expoente numérico. Se este expoente não passado por parâmetro utiliza por padrão 2, portanto, executa número ao quadrado.
Exemplo: POW(F12_01-F12_02)+POW(F12_03-F12_04)
- Random
Retorna um número aleatório entre dois limites. Sintaxe: RANDOM(<expressão_lim_inferior>;<expressão_lim_superior>)
Exatamente dois parâmetros, informando, respectivamente, o limite inferior e o superior do número aleatório a ser gerado.
Exemplo: RANDOM(0.0;1.0)
- Sqrt
Calcula a operação de raiz quadrada. Sintaxe: SQRT(<expressão_base>)
Exatamente um parâmetro. Calcula a raiz quadrada de um número.
Exemplo: SQRT(POW(F12_01-F12_02)+POW(F12_03-F12_04))
Funções de Data
As funções de data são operações que tomam como base parâmetros ou resultado do tipo data.
- Algumas constantes estão definidas assim:
Constante Propósito Valor definido DATE_FIELD_YEAR Indica a parte do ano de uma data 0 DATE_FIELD_MONTH Indica a parte do mês de uma data 1 DATE_FIELD_DAY Indica a parte dia de uma data 2 DATE_FIELD_FORTNIGHT Indica a parte da quinzena de uma data 3 DATE_FIELD_WEEK Indica dia da semana de uma data 5
- Date part
Retorna uma parte de uma data. Sintaxe: DATE_PART(<expressão_data>;<expressão_const_parte>)
Exatamente dois parâmetros, sendo que o primeiro é da data de referência e o segundo parte de interesse. Note que a parte deve ser uma das constantes numéricos definidas acima: 0, 1, 2, 3 ou 5.
Exemplo: DATE_PART("Data";0) - retorna o ano da coluna "Data" da linha atual da tabela.
- Day from today
Retorna uma data a partir de hoje e número de dias para frente ou para trás. Sintaxe: DAY_FROM_TODAY(<expressão_num_dias>)
Exatamente um parâmetro, que é o número modificador para o dia de hoje.
Exemplo: DAY_FROM_TODAY(-1) - retorna a data relativa a "ontem".
- First day of
Retorna o primeiro dia de um agrupamento. Sintaxe: FIRST_DAY_OF(<expressão_const_parte_agrupamento>;<expressão_data_base>) ou FIRST_DAY_OF(<expressão_const_parte_agrupamento>;<expressão_campo_mod_data_base>;<expressão_valor_mod_data_base>)
Duas variações de parâmetros (2 ou 3):
Se dois parâmetros são passados para a função, o primeiro é o campo do agrupamento que se está interessado em obter a primeira data (somente 0, 1, 3 ou 5). E o segundo, é data base para servir como âncora.
Se três parâmetros são passados para a função, o primeiro é o campo do agrupamento que se está interessado em obter a primeira data (somente 0, 1, 3 ou 5). O segundo é campo que modifica a data base a partir de hoje (0, 1, 2, 3 ou 5) e o terceiro em quanto este campo modificador deve ser alterado.
Exemplos:
FIRST_DAY_OF(0;DAY_FROM_TODAY(0)) - primeiro dia do ano (0) a partir de hoje (DAY_FROM_TODAY(0)).
FIRST_DAY_OF(1;"Data") - primeiro dia do mês (1) a partir da coluna "Data" da linha atual da tabela ("Data").
FIRST_DAY_OF(1;0;-1) - primeiro dia do mês atual (1) no ano passado (0;-1).
- Last day of
Retorna o último dia de um agrupamento. Sintaxe: LAST_DAY_OF(<expressão_const_parte_agrupamento>;<expressão_data_base>) ou LAST_DAY_OF(<expressão_const_parte_agrupamento>;<expressão_campo_mod_data_base>;<expressão_valor_mod_data_base>)
Duas variações de parâmetros (2 ou 3):
Se dois parâmetros são passados para a função, o primeiro é o campo do agrupamento que se está interessado em obter a primeira data (somente 0, 1, 3 ou 5). E o segundo, é data base para servir como âncora.
Se três parâmetros são passados para a função, o primeiro é o campo do agrupamento que se está interessado em obter a primeira data (somente 0, 1, 3 ou 5). O segundo é campo que modifica a data base a partir de hoje (0, 1, 2, 3 ou 5) e o terceiro em quanto este campo modificador deve ser alterado.
Exemplos:
LAST_DAY_OF(0;DAY_FROM_TODAY(0)) - último dia do ano (0) a partir de hoje (DAY_FROM_TODAY(0)).
LAST_DAY_OF(1;"Data") - último dia do mês (1) a partir da coluna "Data" da linha atual da tabela ("Data").
LAST_DAY_OF(1;0;-1) - último dia do mês atual (1) no ano passado (0;-1).
- New date
Cria um objeto de data a partir de um dia, um mês e um ano. Sintaxe: NEW_DATE(<expressão_dia>;<expressão_mês>;<expressão_ano>)
Exatamente três parâmetros, sendo que o primeiro é um número válido para um dia (1 a 31), o segundo para um mês (1 a 12) e o terceiro é um ano. A data é criada do ano para dia, portanto, o dia deve ser válido para o mês solicitado e também considerando-se o ano no caso de 29/02 (deve ser ano bissexto).
Exemplo: NEW_DATE(1;4;DATE_PART("Data";0)) - cria o dia primeiro de abril do ano determinado pela coluna "Data" da linha atual da tabela.
- Num of days
Retorna o número de dias entre duas datas. Sintaxe: NUM_OF_DAYS(<expressão_data1>;<expressão_data2>)
Exatamente dois parâmetros, sendo que ambos devem ser do tipo data.
Exemplos:
NUM_OF_DAYS(FIRST_DAY_OF(0;"Data");"Data") - Retorna o número de dias entre o primeiro dia do ano baseado no ano da coluna "Data" está, até data da coluna "Data".
NUM_OF_DAYS(FIRST_DAY_OF(1;"Data"); LAST_DAY_OF(1;"Data")) - Retorna o número de dias do mês em que a coluna "Data" está.
- Num of months
Retorna o número de meses entre duas datas. Sintaxe: NUM_OF_MONTHS(<expressão_data1>;<expressão_data2>)
Exatamente dois parâmetros, sendo que ambos devem ser do tipo data.
Exemplos:
NUM_OF_MONTHS(FIRST_DAY_OF(0;"Data");"Data") - Retorna o número de meses entre o primeiro dia do ano baseado no ano da coluna "Data" está, até data da coluna "Data".
- Previous date
Retorna a anterior mais próxima dado um dia e um mês. Sintaxe: PREVIOUS_DATE(<expressão_dia>;<expressão_mês>)
Exatamente dois parâmetros, sendo o primeiro o dia do mês e o segundo o mês. Cabe destacar que, no caso dos parâmetros serem 29 e fevereiro, o algoritmo considerará o último dia do mês. Portanto, se o ano atual não bissexto, o dia será modificado para 28 e depois será feito cálculo de data anterior.
Exemplos:
PREVIOUS_DATE(1;4) - Retorna o 01/04 anterior mais próximo, ou seja, até "01/04/ano atual" retorna o "01/04/ano anterior", depois disso retorna "01/04/ano atual".
Exemplos
Alguns exemplos de expressões com operandos:
Acrescentar 5% no valor de um campo: "F12_01" * 1.05
Retorno de valor booleano para identificar se uma data está dentro de limite máximo: "Data" <= "30/06/2011"
Obter uma participação individual para uma coluna: "F12_01" / "@sum[F12_01]"
Calcular uma variação percentual entre duas linhas de uma coluna: ("F12_01"-"@prev[F12_01]") / "@prev[F12_01]"
