Tópico
anteriorTópico
seguinte


Classe Total

A classe Total existe como um depositário das funções agregadas. A classe Total contém uma série de funções de agregação. Estas funções são extensões BIRT para JavaScript que resumem um conjunto de linhas. O Motor de relatórios BIRT implementa uma função nas duas seguintes fases:

O BIRT escreve novamente qualquer script que contenha um agregado, criando um script revisto que executa as duas fases. A única altura em que é importante estar atento a este processo é ao proceder à resolução de problemas numa expressão que contenha um agregado. Tenha em consideração o exemplo da apresentação de um valor no pé-de-página de um grupo, em que o valor é uma percentagem do total de todas as contas. A seguinte instrução executa esta acção:

(balance / Total.sum( balance, Total.OVERALL ) ) * 100.0 

No exemplo anterior, Total.OVERALL faz com que BIRT calcule o agregado da soma em todas as linhas, apesar da expressão ser apresentada num total de grupo. Para calcular a expressão no exemplo anterior, o BIRT faz uma transferência para calcular o saldo total e uma segunda transferência para calcular o valor de cada conta.

As regras gerais para a classe Total são:

Acerca de agrupar e filtrar

Todos os agregados permitem dois argumentos opcionais para indicar as opções de filtro e de agrupamento:

Total.<aggregate function> ( ..., filter, group ) 

Acerca do argumento filter

Um argumento filter faculta uma expressão booleana que o BIRT calcula em todas as linhas. O BIRT considera apenas linhas que correspondam ao filtro ao calcular o agregado. Por exemplo, um relatório poderia somar os limites de crédito de clientes activos de forma a determinar a máxima exposição de crédito.

A expressão é executada na fase de transformação de dados. Pode aceder a colunas existentes na linha, a parâmetros, a funções definidas pelo utilizador e ainda a outros recursos, tal como definido na descrição do contexto acima. Por exemplo:

Total.sum( row["CreditLimit"], row["Active"] == 'Y' ); 

Um argumento filter nulo, não definido ou Total.NO_FILTER significa que não é facultado qualquer filtro. Caso a aplicação não faculte qualquer filtro, este adopta a predefinição de não definido. Se facultar um argumento group, deverá indicar um valor em branco ou Total.NO_FILTER para indicar a inexistência de filtro.

Acerca do argumento group

Os relatórios necessitam frequentemente de apresentar os valores totais do actual nível de agrupamento. Por exemplo, suponha que um relatório é agrupado de acordo com clientes e encomendas e que os registos de detalhes representam itens de linha nas encomendas. Cada item de linha possui um preço unitário e uma quantidade, tal como no seguinte agregado:

Total.sum( row["price"] * row["quantity"] ) 

Este agregado soma valores sobre o grupo actual. Caso seja colocado no pé-de-página, apresenta a soma de itens de linha da encomenda em questão. Caso seja colocado no pé-de-página do cliente, apresenta a soma de todos os itens de linha de todas as encomendas para o cliente em questão. Se, por outro lado, for colocado no pé-de-página do relatório, apresenta a soma de todos os itens de linha de todos os clientes.

No entanto, por vezes, a aplicação necessita de aceder a um total de um nível de agrupamento diferente. Por exemplo, poderá querer conhecer o valor total de uma encomenda como uma percentagem de todas as encomendas do cliente. Neste caso, deverá aceder ao total de um grupo que não o grupo actual. Pode fazê-lo utilizando o seguinte argumento de agrupamento:

Total.sum( row.CreditLimit, null, "Customer" ); 

O argumento group pode ser:

Os seguintes exemplos ilustram estes tipos de argumentos de grupo:

Total.sum( row["myCol"] null, null ); // Current group 
Total.sum( row["myCol"], null, "Customer" ); // By name 
Total.sum( row["myCol"], null, "row[`custID']" ); // By group key 
Total.sum( row["myCol"], null, 1 ); // By group index 
Total.sum( row["myCol"], null, "Overall" ); // Grand totals 
Total.sum( row["myCol"], null, 0 ); // Grand totals 

Deverá facultar o argumento de filtro ao utilizar o argumento de agrupamento. Se não necessita de filtro, indique um valor em branco como o valor do filtro. O índice de grupo não é escrito entre aspas. Deverá ser facultado como um número. Ou seja, 1 significa o grupo no nível 1, enquanto que "1" significa o grupo denominado "1".

Propriedades estáticas

OVERALL

Funções

Total.ave

Esta função de agregação calcula o valor da média matemática. Se a expressão for calculada de forma a obter um número, então esta função devolve a média desses mesmos números. Se a expressão for calculada de forma a obter uma data, então função devolve a data média.

Sintaxe

Total.ave( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o valor médio de uma determinada expressão. Devolve um valor em branco caso não existam linhas disponíveis.

Exemplo

A seguinte instrução devolve a idade média de alunos de uma turma:

Total.ave( row.Age ) 

Para devolver a média das datas de aniversário de uma turma, utilize a seguinte instrução:

Total.ave( row.BirthDate ) 

Ver também:

Agregado Total.median

Agregado Total.mode

Agregado Total.movingAve

Agregado Total.stdDev

Agregado Total.variance

Agregado Total.weightedAve

Total.count

Esta função conta o número de linhas existentes no grupo.

Sintaxe

Total.count( [ filter [, group ]] )

Argumentos

Exemplo

Este exemplo conta o número de estudantes do sexo feminino e do sexo masculino existentes numa turma. É necessário criar dois itens de dados. Defina o primeiro de acordo com:

Total.sum( row.sex == 'M' ); 

Defina o segundo de acordo com:

Total.sum( row.sex == 'F' ); 

Ver também:

Agregado Total.countDistinct

Agregado Total.sum

Total.countDistinct

Esta função calcula o número de valores distintos existentes no grupo ou no conjunto de dados. O argumento expr proporciona uma expressão utilizada para agrupar valores. A expressão faz referência a uma coluna de linhas de dados. Os valores nulos são contados como um valor distinto.

Sintaxe

Total.countDistinct ( expr [, filter [, group ]] )

Argumentos

Devoluções

O número de valores distintos existentes no grupo ou no conjunto de dados. Devolve zero caso não existam linhas disponíveis.

Exemplo

Suponha que pretende saber qual o número de países representados por um grupo de estudantes. É possível um item de dados que utilize a seguinte expressão:

Total.countDistinct( row.Country ) 

Nesta instrução, row.Country é uma coluna que contém o nome ou o código do país de origem do estudante. Suponha que algumas linhas contêm um valor em branco, indicando que o país de origem é desconhecido. Utilize a seguinte instrução para excluir as linhas em questão da contagem:

Total.countDistinct( row.Country, row.Country != null ) 

Ver também:

Agregado Total.count

Total.first

Esta função de agregação devolve o primeiro valor apresentado num conjunto de dados. Este é o primeiro valor obtido a partir do conjunto de dados ao obter linhas utilizando a ordem definida para a Tabela ou Lista.

Sintaxe

Total.first( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o primeiro valor apresentado na sequência de linhas ou um valor em branco caso o conjunto de dados não contenha linhas.

Exemplo

Suponha que um relatório apresenta as transacções de um determinado stock ao longo de um período de tempo. A seguinte instrução apresenta a compra mais recente do stock:

Total.first( row.TransDate, row.Action == 'Buy' ); 

Ver também:

Agregado Total.isBottomNPercent

Agregado Total.max

Agregado Total.min

Total.isBottomN

Este função devolve um booleano que indica se um valor de um campo numérico especificado é um dos valores n mais baixos.

Sintaxe

Total.isBottomN( expr, n, [, filter [, group ]] )

Argumentos

Devoluções

A função devolve true ou false. Esta função devolve true se o valor no campo numérico for um dos valores n mais baixos desta coluna.

Exemplo

Suponha que uma coluna de um relatório possui cinco linhas, contendo os valores 1, 2, 3, 4 e 5. Total.isBottomN(expr, 2) testa se o campo representado por expr contém um 1 ou um 2, os dois números mais baixos da coluna.

Ver também:

Total.isBottomNPercent

Total.isTopN

Total.isTopNPercent

Total.isBottomNPercent

Este função devolve um booleano que indica se um valor de um campo numérico especificado possuir uma das percentagens n mais baixas de todos os valores da coluna.

Sintaxe

Total.isBottomNPercent( expr, n, [, filter [, group ]] )

Argumentos

Devoluções

A função devolve true ou false. Esta função devolve true se o valor no campo possuir uma das percentagens n mais baixas de todos os valores da coluna.

Exemplo

Suponha que uma coluna de um relatório possui cinco linhas, contendo os valores 1, 2, 3, 4 e 5. Total.isBottomNPercent(expr, 60) testa se o campo representado por expr contém um 1, um 2, ou um 3, 60% dos números mais baixos da coluna.

Ver também:

Total.isBottomN

Total.isTopN

Total.isTopNPercent

Total.isTopN

Este função devolve um booleano que indica se um valor de um campo numérico especificado é um dos valores n mais altos.

Sintaxe

Total.isTopN( expr, n, [, filter [, group ]] )

Argumentos

Devoluções

A função devolve true ou false. Esta função devolve true se o valor no campo numérico for um dos valores n mais altos desta coluna.

Exemplo

Suponha que uma coluna de um relatório possui cinco linhas, contendo os valores 1, 2, 3, 4 e 5. Total.isTopN(expr, 2) testa se o campo representado por expr contém um 4 ou um 5, os dois números mais altos da coluna.

Ver também:

Total.isTopNPercent

Total.isBottomN

Total.isBottomNPercent

Total.isTopNPercent

Este função devolve um booleano que indica se um valor de um campo numérico especificado possuir uma das percentagens n mais altas de todos os valores da coluna.

Sintaxe

Total.isTopNPercent( expr, n, [, filter [, group ]] )

Argumentos

Devoluções

A função devolve true ou false. Esta função devolve true se o valor no campo possuir uma das percentagens n mais altas de todos os valores da coluna.

Exemplo

Suponha que uma coluna de um relatório possui cinco linhas, contendo os valores 1, 2, 3, 4 e 5. Total.isTopNPercent(expr, 60) testa se o campo representado por expr contém um 3, um 4 ou um 5, 60% dos números mais altos da coluna.

Ver também:

Total.isTopN

Total.isBottomN

Total.isBottomNPercent

Total.last

Esta função devolve o último valor apresentado num conjunto de dados. Este é o último valor obtido a partir do conjunto de dados ao obter linhas utilizando a ordem definida para a Tabela ou Lista.

Sintaxe

Total.last( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o último valor apresentado na sequência de linhas ou um valor em branco caso o conjunto de dados não contenha linhas.

Exemplo

Suponha que um relatório apresenta as transacções de um determinado stock ao longo de um período de tempo. A seguinte instrução apresenta a venda mais recente do stock:

Total.last( row.TransDate, row.Action == 'Sell' ); 

Ver também:

Agregado Total.first

Agregado Total.max

Agregado Total.min

Total.max

Esta função calcula o valor máximo de uma determinada expressão. A expressão é calculada para cada linha e o valor máximo é retido. A função pode funcionar com números, cadeias ou datas.

Sintaxe

Total.max( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o valor máximo de uma determinada expressão. Devolve um valor em branco caso não existam linhas disponíveis.

Exemplo

A seguinte instrução localiza o aluno mais velho de uma turma:

Total.max( row.Age ) 

Ver também:

Agregado Total.first

Agregado Total.isBottomNPercent

Agregado Total.min

Total.median

Esta função de agregação calcula o valor da mediana matemática. Metade dos valores ficam abaixo da mediana e metade acima.

Sintaxe

Total.median( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o valor mediano de uma determinada expressão. Devolve um valor em branco caso não existam linhas disponíveis.

Exemplo

A seguinte instrução devolve a idade mediana de alunos de uma turma:

Total.median( row.Age ) 

E, para devolver a mediana das datas de aniversário de uma turma, utilize a seguinte instrução:

Total.median( row.BirthDate ) 

Ver também:

Agregado Total.ave

Agregado Total.mode

Agregado Total.movingAve

Agregado Total.stdDev

Agregado Total.variance

Agregado Total.weightedAve

Total.min

Esta função de agregação calcula o valor mínimo de uma determinada expressão. A expressão é calculada para cada linha e o valor mínimo é retido. Esta função pode funcionar com qualquer tipo simples: números, cadeias ou datas.

Sintaxe

Total.min( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o valor mínimo de uma determinada expressão. Devolve um valor em branco caso não existam linhas disponíveis.

Exemplo

A seguinte instrução devolve a idade do aluno mais novo de uma turma:

Total.min( row.Age ) 

Ver também:

Agregado Total.first

Agregado Total.isBottomNPercent

Agregado Total.max

Total.mode

Esta função de agregação calcula o valor da moda matemática. A moda é o valor que ocorre mais frequentemente nos dados. Por exemplo, na sequência {1, 2, 3, 2, 4, 7}, 2 é a moda porque surge duas vezes, enquanto que os restantes números só surgem uma vez. Caso um conjunto de dados possuir diversas modas como, por exemplo, na sequência {1,2,3,2,3}, o agregado de moda devolve devolve um valor em branco.

Sintaxe

Total.mode( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o valor da moda de uma determinada expressão. Devolve um valor em branco caso não existam linhas disponíveis, ou caso os dados possuam mais do que uma moda.

Exemplo

A seguinte instrução devolve a idade mais recorrente nos alunos de uma turma:

Total.mode( row.Age ) 

Ver também:

Agregado Total.ave

Agregado Total.median

Agregado Total.movingAve

Agregado Total.stdDev

Agregado Total.variance

Agregado Total.weightedAve

Total.movingAve

Esta função de agregação calcula uma média móvel. O argumento expr proporciona o valor à média e o argumento window proporciona o número de linhas a considerar. A média das linhas é criada de acordo com a ordem determinada pelo contexto, normalmente a ordem especificada por um elemento de ordenação para uma Lista ou Tabela.

Sintaxe

Total.movingAve( expr, window [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o valor de média móvel de uma determinada expressão. Devolve um valor em branco caso não existam linhas disponíveis.

Exemplo

Suponha que um relatório apresenta o preço diário de um stock. Para apresentar a média móvel desse mesmo stock ao longo dos últimos cinco dias, utilize a seguinte instrução:

Total.movingAve( row.price, 5 ); 

Ver também:

Agregado Total.ave

Agregado Total.median

Agregado Total.mode

Agregado Total.stdDev

Agregado Total.variance

Agregado Total.weightedAve

Total.percentile

Esta função examina um conjunto de valores e devolve o valor que constitui um percentil especificado de todos os valores do conjunto. Por exemplo, poderá querer saber que classificação representa 90% de todas as classificações num teste.

Sintaxe

Argumentos

Devoluções

Esta função devolve o valor que corresponde ao percentil especificado no conjunto de valores analisados.

Exemplo

A seguinte instrução devolve o valor da classificação de 50%:

Total.percentile( row.TestScore, 0.5) 

Se o conjunto de classificações de teste na coluna especificada for 10, 20, 30, 40 e 50, esta instrução devolveria 30.

Ver também:

Total.percentRank

Total.percentSum

Total.quartile

Total.percentRank

Esta função calcula a classificação da percentagem de um valor num campo especificado.

Sintaxe

percentRank( expr, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve a classificação da percentagem do valor no campo especificado. O valor de retorno está entre zero e um.

Exemplo

A seguinte instrução devolve a ordenação de acordo com a percentagem de uma classificação entre todas as classificações de uma coluna:

Total.percentRank( row.Scores ) 

Caso as classificações no intervalo de avaliação forem 10, 10, 20 e 50, e a classificação na célula que contém esta instrução for 30, o valor de devolução é .5 visto que metade dos valores é superior a 20 e a outra metade é inferior a 20.

Ver também:

Total.percentile

Total.percentSum

Total.quartile

Total.percentSum

Esta função calculaXXX t.

Sintaxe

percentSum( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve a percentagem da contribuição deste valor para a soma de todos os valores do intervalo.

Exemplo

A seguinte instrução devolve a percentagem da contribuição desta encomenda para a soma de todas as encomendas:

Total.percentSum( row.OrderAmt ) 

Ver também:

Total.percentile

Total.percentRank

Total.quartile

Total.quartile

Esta função calcula o valor existente num conjunto definido de valores para o qual 0%, 25%, 50%, 75% ou 100% dos valores no conjunto são superiores.

Sintaxe

quartile( expr, quartile, [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o valor no conjunto especificado colocado no quartil especificado.

Exemplo

A seguinte instrução devolve a encomenda para a qual 75% é inferior e 25% é superior:

Total.quartile( row.OrderAmt, 3) 

Ver também:

Total.percentile

Total.percentRank

Total.percentSum

Total.rank

Esta função calcula onde se classifica um valor entre um conjunto de valores. O valor da classificação está incluído no intervalo entre 1 e o número de valores existente no conjunto. Se dois valores forem idênticos, possuem a mesma classificação.

Sintaxe

rank( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve um número inteiro que reflecte a classificação de valores e possui um intervalo de 1 para o número de itens existentes no conjunto de valores

Exemplo

A seguinte instrução devolve a classificação do campo OrderAmt entre todas as encomendas existentes na coluna OrderAmt.

Total.rank( row.OrderAmt ) 

Ver também:

Total.percentRank

Total.runningCount

Esta função calcula uma contagem de linhas em execução.

Sintaxe

runningCount( filter [, group ]] )

Argumentos

Devoluções

Esta função devolve a contagem de linhas em execução.

Exemplo

A seguinte instrução devolve a contagem em execução para um relatório:

Total.runningCount( ) 

Ver também:

Agregado Total.count

Agregado Total.percentRank

Total.stdDev

Esta função de agregação calcula o desvio estatístico padrão de uma sequência de números. O desvio padrão é uma medida da distribuição de um conjunto de valores.

Sintaxe

Total.stdDev( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o desvio padrão de uma determinada expressão. Devolve um valor em branco caso não existam linhas disponíveis.

Ver também:

Agregado Total.ave

Agregado Total.median

Agregado Total.mode

Agregado Total.movingAve

Agregado Total.variance

Agregado Total.weightedAve

Total.sum

Esta função de agregação calcula a soma resultante da adição de um valor por cada linha existente no grupo. O valor para cada linha é calculado utilizando a expressão apresentada no argumento expr. A soma é obtida ao adicionar todos estes valores.

Sintaxe

Total.sum( expr [, filter [, group ]] )

Argumentos

Devoluções

A soma da expressão em questão. Devolve zero caso não existam linhas disponíveis.

Exemplo

A seguinte instrução indica o total de encomendas para um cliente:

Total.sum( row.OrderAmt ) 

Ver também:

Agregado Total.count

Agregado Total.percentRank

Total.variance

Esta função de agregação calcula o desvio estatístico de uma sequência de números. A variância é uma medida da distribuição de um conjunto de valores.

Sintaxe

Total.variance( expr [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve a variância de uma determinada expressão. Devolve um valor em branco caso não existam linhas disponíveis.

Ver também:

Agregado Total.ave

Agregado Total.median

Agregado Total.mode

Agregado Total.movingAve

Agregado Total.stdDev

Agregado Total.weightedAve

Total.weightedAve

Esta função de agregação calcula o valor da média matemática ponderada. Se os argumentos expr ou weight se tornarem valores em branco, então a linha é excluída da média.

Sintaxe

Total.weightedAve( expr, weight [, filter [, group ]] )

Argumentos

Devoluções

Esta função devolve o valor da média ponderada de uma determinada expressão. Devolve um valor em branco caso não existam linhas disponíveis.

Exemplo

Suponha que uma aplicação financeira regista lotes de um determinado stock adquirido em diferentes alturas. Cada lote possui um preço de compra diferente e uma série de acções adquiridas ao preço em questão. A seguinte instrução calcula o preço de compra da média ponderada:

Total.weightedAve( row.purchasePrice, row.shareCount ) 

Ver também:

Agregado Total.ave

Agregado Total.median

Agregado Total.mode

Agregado Total.movingAve

Agregado Total.stdDev

Agregado Total.variance


(c)
Copyright Actuate Corporation 2006

Tópico
anteriorTópico
seguinte