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;

Basic Expression Structures

Value Operands

The value operands are values from a data type that are used in expressions as variables.

• Value type operand: 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;

• Text type operand: Are literal string data operands. These values allow the use of characters chain fields (strings), being delimited by the simple quote (') character. Examples: 'John Snow', 'California', 'Spaghetti';

• Date type operand: Are values that express any date. It is possible to determine a date representing it as a string, being delimited by the simple quote (') character and separated by the bar (/) character. The default supported format is "dd/MM/yyyy". Examples: '01/01/2011', '29/02/2000';

• Boolean type operand: Are values from the true or false kind. Usually used to validate or not a condition. Examples: true e false;

• Identifier type operand: Are values that represents a field or variable in the expression. Used to make reference to data source columns, delimited by double quotes ("). Examples: "City.City", "Product.Product";

• System variable type operand: Are system pre-defined variables. These values are replaced in run-time by pre-determined values, delimited by double quotes (") and preceded by star (#). By now only one variable is available: "#null" that indicates null values or fields.

Arithmetic Expressions

The arithmetic expressions relate two operands (value or another expression) to compose a sum, subtraction, multiplication or division.

• Sum (+): Sum two operands. Represented by the sum (+) character. The expression syntax is <operand/expression> + <operand/expression>. Examples: "Taxes" + "Commissions";

• Subtraction (-): Subtract two operands. Represented by the subtract or hyphen (-) character. The expression syntax is <operand/expression> - <operand/expression>. Examples: "Gross Sale" - "Taxes";

• Multiplication (*): Multiplicate two operands. Represented by the multiplication or star (*) character. The expression syntax is <operand/expression> * <operand/expression>. Examples: "Amount" * "Unit Price";

• Division(/): Divides two operands. Represented by the divide or bar (/) character. The expression syntax is <operand/expression> / <operand/expression>. Examples: "Total Value" / "Amount".

Relational Expressions

The relational expressions compare two operands (value or another expression) two evaluate if a condition is true or false. Usually used with decision functions, like the IF.

• Equal (==): Do the equal comparison expression between two operands. Represented by the equal operator (==). The expression syntax is <expression> == <expression>. Examples: "Unit Price" == "Total Price";

• Different (!=): Do the different comparison expression between two operands. Represented by the different operator (!=). The expression syntax is <expression> != <expression>. Examples: "City.City" != 'New York';

• Greater than (>): Return true if the the first expression is greater than the second expression and false otherwise. Represented by the greater operator (>). The expression syntax is <expression> > <expression>. Examples: "Order Date" > '01/01/2011';

• Greater or equal than (>=): Return true if the the first expression is greater than or equal to the second expression and false otherwise. Represented by the greater or equal operator (>=). The expression syntax is <expression> >= <expression>. Examples: IF("Order Date" >= '01/01/2011';"Order Date";0);

• Lesser than (<): Return true if the the first expression is lesser than the second expression and false otherwise. Represented by the lesser operator (<). The expression syntax is <expression> < <expression>. Examples: "Profit" < '0';

• Lesser or equal than (<=): Return true if the the first expression is lesser than or equal to the second expression and false otherwise. Represented by the lesser or equal operator (<=). The expression syntax is <expression> <= <expression>. Examples: IF("Order Date" <= '01/01/2011';"Order Date";0);

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]"