Expressions

From TaticView
Revision as of 19:38, 20 May 2013 by Jeferson (talk | contribs)
Jump to: navigation, search

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 ou variable in the expression. Used to make reference to data source columns, delimited by double quotes ("). Examples: "City.City", "Product.Product";
  • 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]"