Cláusula Aggregate (Visual Basic)

Artigo
04/07/2023

Aplica uma ou mais funções de agregação a uma coleção.

Sintaxe

Aggregate element [As type] In collection _  
  [, element2 [As type2] In collection2, [...]]  
  [ clause ]  
  Into expressionList

Partes

Termo	Definição
`element`	Obrigatórios. Variável usada para iterar por meio dos elementos da coleção.
`type`	Opcional. O tipo de `element`. Se nenhum tipo for especificado, o de `element` é inferido de `collection`.
`collection`	Obrigatórios. Refere-se à coleção na qual a operação deve ocorrer.
`clause`	Opcional. Uma ou mais cláusulas de consulta, como `Where`, para refinar o resultado da consulta, com o objetivo de aplicar a cláusula ou as cláusulas de agregação.
`expressionList`	Obrigatórios. Uma ou mais expressões delimitadas por vírgulas que identificam uma função de agregação a ser aplicada à coleção. Você pode aplicar um alias a uma função de agregação para especificar um nome de membro para o resultado da consulta. Se nenhum alias for fornecido, o nome da função de agregação será usado. Para obter exemplos, confira a seção sobre funções de agregação posteriormente neste tópico.

Comentários

A cláusula Aggregate pode ser usada para incluir funções de agregação nas consultas. As funções de agregação realizam verificações e cálculos sobre um conjunto de valores e retornam um valor único. Você pode acessar o valor calculado usando um membro do tipo de resultado da consulta. As funções de agregação padrão que você pode usar são All, Any, Average, Count, LongCount, Max, Min e Sum. Essas funções são familiares aos desenvolvedores, que conhecem as agregações em SQL. Elas são descritos na próxima seção deste tópico.

O resultado de uma função agregada é incluído no resultado da consulta como um campo do tipo de resultado dela. Você pode fornecer um alias para o resultado da função de agregação para especificar o nome do membro do tipo de resultado da consulta que conterá o valor agregado. Se nenhum alias for fornecido, o nome da função de agregação será usado.

A cláusula Aggregate pode iniciar uma consulta ou pode ser incluída como uma cláusula adicional em uma consulta. Se a cláusula Aggregate iniciar uma consulta, o resultado será um valor único, que é o resultado da função agregada especificada na cláusula Into. Se mais de uma função de agregação for especificada na cláusula Into, a consulta retornará um único tipo com uma propriedade separada para referenciar o resultado de cada função de agregação na cláusula Into. Se a cláusula Aggregate for incluída como cláusula adicional em uma consulta, o tipo retornado na coleção de consultas terá uma propriedade separada para referenciar o resultado de cada função de agregação na cláusula Into.

Funções de Agregação

Veja a seguir as funções de agregação padrão que podem ser usadas com a cláusula Aggregate.

Todos

Retorna true se todos os elementos na coleção atenderem a uma condição especificada; caso contrário, retornará false. A seguir, é mostrado um exemplo:

Dim customerList1 = Aggregate order In orders
                    Into AllOrdersOver100 = All(order.Total >= 100)

Qualquer

Retorna true se qualquer elemento na coleção atender a uma condição especificada; caso contrário, retornará false. A seguir, é mostrado um exemplo:

Dim customerList2 = From cust In customers
                    Aggregate order In cust.Orders
                    Into AnyOrderOver500 = Any(order.Total >= 500)

Média

Calcula a média de todos os elementos na coleção ou calcula uma expressão fornecida para todos os elementos da coleção. A seguir, é mostrado um exemplo:

Dim customerOrderAverage = Aggregate order In orders
                           Into Average(order.Total)

Contagem

Conta o número de elementos na coleção. Você pode fornecer uma expressão opcional Boolean para contar apenas o número de elementos na coleção que atendam a uma condição. A seguir, é mostrado um exemplo:

Dim customerOrderAfter1996 = From cust In customers
                             Aggregate order In cust.Orders
                             Into Count(order.OrderDate > #12/31/1996#)

Grupo

Refere-se aos resultados da consulta que são agrupados como resultado de uma cláusula Group By ou Group Join. A função Group é válida somente na cláusula Into de Group By ou Group Join. Para obter mais informações e exemplos, confira Cláusula Group By e Cláusula Group Join.

LongCount

Conta o número de elementos na coleção. Você pode fornecer uma expressão opcional Boolean para contar apenas o número de elementos na coleção que atendam a uma condição. Retorna o resultado como um Long. Para obter um exemplo, confira a função de agregação Count.

Max

Calcula o valor máximo da coleção ou uma expressão fornecida para todos os elementos da coleção. A seguir, é mostrado um exemplo:

Dim customerMaxOrder = Aggregate order In orders
                       Into MaxOrder = Max(order.Total)

Min

Calcula o valor mínimo da coleção ou uma expressão fornecida para todos os elementos da coleção. A seguir, é mostrado um exemplo:

Dim customerMinOrder = From cust In customers
                       Aggregate order In cust.Orders
                       Into MinOrder = Min(order.Total)

Somar

Calcula a soma de todos os elementos na coleção ou uma expressão fornecida para todos os elementos da coleção. A seguir, é mostrado um exemplo:

Dim customerTotals = From cust In customers
                     Aggregate order In cust.Orders
                     Into Sum(order.Total)

Exemplo

O exemplo a seguir mostra como usar a cláusula Aggregate para aplicar funções de agregação a um resultado de consulta.

Public Sub AggregateSample()
    Dim customers = GetCustomerList()

    Dim customerOrderTotal =
        From cust In customers
        Aggregate order In cust.Orders
        Into Sum(order.Total), MaxOrder = Max(order.Total),
        MinOrder = Min(order.Total), Avg = Average(order.Total)

    For Each customer In customerOrderTotal
        Console.WriteLine(customer.cust.CompanyName & vbCrLf &
                         vbTab & "Sum = " & customer.Sum & vbCrLf &
                         vbTab & "Min = " & customer.MinOrder & vbCrLf &
                         vbTab & "Max = " & customer.MaxOrder & vbCrLf &
                         vbTab & "Avg = " & customer.Avg.ToString("#.##"))
    Next
End Sub

Como criar funções de agregação definidas pelo usuário

Você pode incluir as próprias funções de agregação personalizadas em uma expressão de consulta adicionando métodos de extensão ao tipo IEnumerable<T>. Em seguida, o método personalizado pode executar um cálculo ou uma operação na coleção enumerável que fez referência à função de agregação. Para obter mais informações sobre os métodos de extensão, consulte Métodos de extensão.

Por exemplo, o exemplo a seguir mostra uma função de agregação personalizada que calcula o valor mediano de uma coleção de números. Há duas sobrecargas do método de extensão Median. A primeira sobrecarga aceita, como entrada, uma coleção de tipo IEnumerable(Of Double). Se a função de agregação Median for chamada para um campo de consulta do tipo Double, esse método será chamado. A segunda sobrecarga do método Median pode ser passada por qualquer tipo genérico. A sobrecarga genérica do método Median usa um segundo parâmetro que faz referência à expressão lambda Func(Of T, Double) para projetar um valor para um tipo (de uma coleção) como o valor correspondente do tipo Double. Em seguida, ele delega o cálculo do valor mediano para a outra sobrecarga do método Median. Para obter mais informações sobre expressões lambda, consulte Expressões lambda.

Imports System.Runtime.CompilerServices

Module UserDefinedAggregates

    ' Calculate the median value for a collection of type Double.
    <Extension()>
    Function Median(ByVal values As IEnumerable(Of Double)) As Double
        If values.Count = 0 Then
            Throw New InvalidOperationException("Cannot compute median for an empty set.")
        End If

        Dim sortedList = From number In values
                         Order By number

        Dim medianValue As Double

        Dim itemIndex = CInt(Int(sortedList.Count / 2))

        If sortedList.Count Mod 2 = 0 Then
            ' Even number of items in list.
            medianValue = ((sortedList(itemIndex) + sortedList(itemIndex - 1)) / 2)
        Else
            ' Odd number of items in list.
            medianValue = sortedList(itemIndex)
        End If

        Return medianValue
    End Function

    ' "Cast" the collection of generic items as type Double and call the 
    ' Median() method to calculate the median value.
    <Extension()>
    Function Median(Of T)(ByVal values As IEnumerable(Of T),
                          ByVal selector As Func(Of T, Double)) As Double
        Return (From element In values Select selector(element)).Median()
    End Function

End Module

O exemplo a seguir mostra consultas de exemplo que chamam a função de agregação Median em uma coleção de tipos Integere uma coleção de tipo Double. A consulta que chama a função de agregação Median na coleção de tipos Double chama a sobrecarga do método Median que aceita, como entrada, uma coleção de tipo Double. A consulta que chama a função de agregação Median na coleção de tipos Integer chama a sobrecarga genérica do método Median.

Module Module1

    Sub Main()
        Dim numbers1 = {1, 2, 3, 4, 5}

        Dim query1 = Aggregate num In numbers1 Into Median(num)

        Console.WriteLine("Median = " & query1)

        Dim numbers2 = {1.9, 2, 8, 4, 5.7, 6, 7.2, 0}

        Dim query2 = Aggregate num In numbers2 Into Median()

        Console.WriteLine("Median = " & query2)
    End Sub

End Module

Compartilhar via