C# LINQ GroupBy

"Quantos produtos há em cada categoria?" "Quanto vale o estoque de cada seção da loja?" Para responder, primeiro é preciso separar os produtos em montes: um monte para Papelaria, outro para Bolsas, outro para Cozinha. É isso que o GroupBy ("agrupar por") faz: ele reparte uma sequência em grupos, um para cada valor da chave que você escolher. Depois, você pode percorrer cada grupo ou fazer contas com ele.

Todos os programas rodaram com o .NET 10 (C# 14) na máquina da Ana, na pasta ~/cs, com dotnet run arquivo.cs. Eles usam a lista de produtos da lojinha apresentada em O que é LINQ (linhas 1 a 10 de cada arquivo) e o record Produto no fim; os arquivos abaixo mostram só o programa.

List<Produto> produtos =
[
    new("Caderno", "Papelaria", 18.90m, 12),
    new("Lápis", "Papelaria", 2.50m, 40),
    new("Mochila", "Bolsas", 129.90m, 3),
    new("Borracha", "Papelaria", 1.75m, 25),
    new("Estojo", "Bolsas", 24.90m, 0),
    new("Garrafa", "Cozinha", 35.00m, 8),
    new("Caneca", "Cozinha", 22.50m, 5),
];

// … o programa de cada exemplo começa na linha 12 …

record Produto(string Nome, string Categoria, decimal Preco, int Estoque);

A ideia: as caixas com etiqueta

Chegou uma caixa grande com os produtos todos misturados. A Ana pega caixas menores, escreve uma etiqueta em cada uma ("Papelaria", "Bolsas", "Cozinha") e vai pondo cada produto na caixa da sua categoria. Se aparece um produto de uma categoria nova, ela pega mais uma caixa.

1. O primeiro GroupBy

// (a lista de produtos)

var grupos = produtos.GroupBy(p => p.Categoria);

foreach (var grupo in grupos)
{
    Console.WriteLine($"== {grupo.Key}");
    foreach (Produto p in grupo)
    {
        Console.WriteLine($"   {p.Nome} {p.Preco:C}");
    }
}

// (o record Produto)

$ dotnet run groupby.cs
== Papelaria
   Caderno R$ 18,90
   Lápis R$ 2,50
   Borracha R$ 1,75
== Bolsas
   Mochila R$ 129,90
   Estojo R$ 24,90
== Cozinha
   Garrafa R$ 35,00
   Caneca R$ 22,50

A ordem dos grupos: eles saem na ordem em que cada chave apareceu pela primeira vez na lista. O primeiro produto é o Caderno (Papelaria), o terceiro é a Mochila (Bolsas) e o sexto é a Garrafa (Cozinha). Dentro de cada grupo, os produtos também mantêm a ordem original. Para outra ordem, ordene os grupos (seção 2) ou ordene os produtos antes do GroupBy.

List<Produto> produtos =
[
    new("Caderno", "Papelaria", 18.90m, 12),
    new("Lápis", "Papelaria", 2.50m, 40),
    new("Mochila", "Bolsas", 129.90m, 3),
    new("Borracha", "Papelaria", 1.75m, 25),
    new("Estojo", "Bolsas", 24.90m, 0),
    new("Garrafa", "Cozinha", 35.00m, 8),
    new("Caneca", "Cozinha", 22.50m, 5),
];

var grupos = produtos.GroupBy(p => p.Categoria);

foreach (var g in grupos)
{
    Console.WriteLine($"{g.Key}: {g.Count()} produtos");
}

record Produto(string Nome, string Categoria, decimal Preco, int Estoque);

List<Produto> produtos =
[
    new("Caderno", "Papelaria", 18.90m, 12),
    new("Lápis", "Papelaria", 2.50m, 40),
    new("Mochila", "Bolsas", 129.90m, 3),
    new("Borracha", "Papelaria", 1.75m, 25),
    new("Estojo", "Bolsas", 24.90m, 0),
    new("Garrafa", "Cozinha", 35.00m, 8),
    new("Caneca", "Cozinha", 22.50m, 5),
];

var grupos = produtos.GroupBy(p => p.Categoria);

foreach (var g in grupos)
{
    Console.WriteLine($"{g.Key}: {string.Join(", ", g.Select(p => p.Nome))}");
}

record Produto(string Nome, string Categoria, decimal Preco, int Estoque);

2. Um resumo por grupo

O uso mais comum do GroupBy não é listar, e sim resumir: uma linha por grupo, com contas sobre os elementos dele. Como cada grupo é uma sequência, todos os métodos do LINQ funcionam nele: g.Count() conta, g.Sum(…) soma (os dois são o assunto da próxima aula, Agregar):

// (a lista de produtos)

var resumo = produtos
    .GroupBy(p => p.Categoria)
    .OrderBy(g => g.Key)
    .Select(g => new
    {
        Categoria = g.Key,
        Quantos = g.Count(),
        Valor = g.Sum(p => p.Preco * p.Estoque)
    });

foreach (var linha in resumo)
{
    Console.WriteLine($"{linha.Categoria,-10} {linha.Quantos} produtos  {linha.Valor,10:C}");
}

// (o record Produto)

$ dotnet run resumo.cs
Bolsas     2 produtos   R$ 389,70
Cozinha    2 produtos   R$ 392,50
Papelaria  3 produtos   R$ 370,55

.GroupBy(p => p.Categoria)

Faz os 3 grupos.

.OrderBy(g => g.Key)

Ordena os grupos pela chave: agora o g da lambda é um grupo, não um produto. As categorias saem em ordem alfabética.

.Select(g => new { … })

Transforma cada grupo numa linha do relatório, com um tipo anônimo.

g.Count()

Quantos produtos há no grupo.

g.Sum(p => p.Preco * p.Estoque)

A soma, para cada produto do grupo, de preço × quantidade: o valor do estoque da categoria. Em Bolsas: 129,90 × 3 + 24,90 × 0 = 389,70.

É o mesmo que uma tabela dinâmica de planilha, ou o GROUP BY da linguagem SQL dos bancos de dados: agrupar e depois agregar (contar, somar, tirar a média) cada grupo.

3. Outras formas de agrupar

Agrupar só uma parte: o seletor de elemento

Um segundo parâmetro no GroupBy diz o que entra em cada grupo. Com p => p.Nome, cada grupo guarda só os nomes, em vez dos produtos inteiros. O mesmo agrupamento na sintaxe de consulta vem logo abaixo:

// (a lista de produtos)

var nomesPorCategoria = produtos.GroupBy(p => p.Categoria, p => p.Nome);

foreach (var g in nomesPorCategoria)
{
    Console.WriteLine($"{g.Key}: {string.Join(", ", g)}");
}

var consulta =
    from p in produtos
    group p.Nome by p.Categoria into g
    orderby g.Key
    select $"{g.Key} ({g.Count()})";

Console.WriteLine(string.Join(" | ", consulta));

// (o record Produto)

$ dotnet run elementos.cs
Papelaria: Caderno, Lápis, Borracha
Bolsas: Mochila, Estojo
Cozinha: Garrafa, Caneca
Bolsas (2) | Cozinha (2) | Papelaria (3)

• GroupBy(p => p.Categoria, p => p.Nome): a chave é a categoria; os elementos, os nomes. Cada g é um IGrouping<string, string>, e string.Join(", ", g) junta os nomes direto.
• Na sintaxe de consulta, group p.Nome by p.Categoria diz "agrupe os nomes pela categoria". O into g ("para dentro de g") dá nome a cada grupo e deixa a consulta continuar (com orderby, select…). Sem o into, o group tem de ser a última cláusula.

Agrupar por uma chave calculada

A chave não precisa ser uma propriedade: pode ser qualquer conta. Abaixo, faixas de preço com uma expressão switch e uma chave bool:

// (a lista de produtos)

var porFaixa = produtos.GroupBy(p => p.Preco switch
{
    < 10m => "até R$ 10",
    < 50m => "R$ 10 a R$ 50",
    _ => "acima de R$ 50"
});

foreach (var g in porFaixa)
{
    Console.WriteLine($"{g.Key}: {string.Join(", ", g.Select(p => p.Nome))}");
}

var situacao = produtos.GroupBy(p => p.Estoque == 0);
foreach (var g in situacao)
{
    Console.WriteLine($"Em falta? {g.Key}: {g.Count()} produto(s)");
}

// (o record Produto)

$ dotnet run faixas.cs
R$ 10 a R$ 50: Caderno, Estojo, Garrafa, Caneca
até R$ 10: Lápis, Borracha
acima de R$ 50: Mochila
Em falta? False: 6 produto(s)
Em falta? True: 1 produto(s)

A faixa "R$ 10 a R$ 50" veio primeiro porque o primeiro produto da lista (o Caderno, 18,90) caiu nela. Com a chave bool, há no máximo dois grupos: False e True.

Atalhos: CountBy .NET 9 e ToLookup

// (a lista de produtos)

foreach (var par in produtos.CountBy(p => p.Categoria))
{
    Console.WriteLine($"{par.Key}: {par.Value}");
}

ILookup<string, Produto> porCategoria = produtos.ToLookup(p => p.Categoria);
Console.WriteLine(string.Join(", ", porCategoria["Cozinha"].Select(p => p.Nome)));
Console.WriteLine(porCategoria["Brinquedos"].Count());

// (o record Produto)

$ dotnet run countby.cs
Papelaria: 3
Bolsas: 2
Cozinha: 2
Garrafa, Caneca
0                « uma categoria que não existe dá um grupo vazio, sem erro

• CountBy ("contar por") faz o GroupBy e o Count de uma vez, e devolve pares chave/valor (par.Key, par.Value). Existe desde o .NET 9; em código mais antigo, você vai ver GroupBy(…).Select(g => new { g.Key, Total = g.Count() }). Há também o AggregateBy, para somas e outras contas por chave.
• ToLookup ("tabela de consulta") agrupa na hora (não é adiado) e deixa buscar um grupo pela chave, com colchetes, como um dicionário: porCategoria["Cozinha"]. Use quando for consultar os grupos várias vezes, por chave.

Quando dá errado

// (a lista de produtos, linhas 1 a 10)

var grupos = produtos.GroupBy(p => p.Categoria);
foreach (var g in grupos)
{
    Console.WriteLine(g.Nome);
}

// (o record Produto)

$ dotnet run grupo-erro.cs
/home/ana/cs/grupo-erro.cs(15,25): error CS1061: ‘IGrouping<string, Produto>’ não contém uma definição para "Nome" e não foi possível encontrar nenhum método de extensão "Nome" que aceite um primeiro argumento do tipo ‘IGrouping<string, Produto>’ (você está se esquecendo de usar uma diretiva ou uma referência de assembly?)

Ocorreu uma falha no build. Corrija os erros de build e execute novamente.

// (a lista de produtos)

var grupos = produtos.GroupBy(p => p.Categoria);
foreach (var g in grupos)
{
    Console.WriteLine(g);
}

// (o record Produto)

$ dotnet run imprimir-grupo.cs
System.Linq.Grouping`2[System.String,Produto]
System.Linq.Grouping`2[System.String,Produto]
System.Linq.Grouping`2[System.String,Produto]

// (a lista de produtos, linhas 1 a 10)

var porCategoria = produtos.ToDictionary(p => p.Categoria);
Console.WriteLine(porCategoria.Count);

// (o record Produto)

$ dotnet run dicionario-erro.cs
Unhandled exception. System.ArgumentException: An item with the same key has already been added. Key: Papelaria
   at System.Collections.Generic.Dictionary`2.TryInsert(TKey key, TValue value, InsertionBehavior behavior)
   at System.Collections.Generic.Dictionary`2.Add(TKey key, TValue value)
   at System.Linq.Enumerable.SpanToDictionary[TSource,TKey](ReadOnlySpan`1 source, Func`2 keySelector, IEqualityComparer`1 comparer)
   at System.Linq.Enumerable.ToDictionary[TSource,TKey](IEnumerable`1 source, Func`2 keySelector, IEqualityComparer`1 comparer)
   at Program.<Main>$(String[] args) in /home/ana/cs/dicionario-erro.cs:line 12

Referência

Exercícios

List<Produto> produtos =
[
    new("Caderno", "Papelaria", 18.90m, 12),
    new("Lápis", "Papelaria", 2.50m, 40),
    new("Mochila", "Bolsas", 129.90m, 3),
    new("Borracha", "Papelaria", 1.75m, 25),
    new("Estojo", "Bolsas", 24.90m, 0),
    new("Garrafa", "Cozinha", 35.00m, 8),
    new("Caneca", "Cozinha", 22.50m, 5),
];

var grupos = produtos.GroupBy(p => p.Categoria);

foreach (var g in grupos)
{
    Console.WriteLine($"{g.Key}: ?");
}

record Produto(string Nome, string Categoria, decimal Preco, int Estoque);

List<Produto> produtos =
[
    new("Caderno", "Papelaria", 18.90m, 12),
    new("Lápis", "Papelaria", 2.50m, 40),
    new("Mochila", "Bolsas", 129.90m, 3),
    new("Borracha", "Papelaria", 1.75m, 25),
    new("Estojo", "Bolsas", 24.90m, 0),
    new("Garrafa", "Cozinha", 35.00m, 8),
    new("Caneca", "Cozinha", 22.50m, 5),
];

var grupos = produtos
    .GroupBy(p => p.Categoria)
    .OrderBy(g => g.Key);

foreach (var g in grupos)
{
    Console.WriteLine($"{g.Key}: {g.Sum(p => p.Preco * p.Estoque):C}");
}

record Produto(string Nome, string Categoria, decimal Preco, int Estoque);

Resumo

• GroupBy(p => chave) reparte uma sequência em grupos, um para cada valor da chave.
• Cada grupo (IGrouping<TChave, T>) tem a etiqueta Key e é uma sequência dos seus elementos: percorra com foreach ou use o LINQ nele (g.Count(), g.Sum(…)).
• Os grupos saem na ordem em que cada chave apareceu; para ordenar, .OrderBy(g => g.Key).
• Agrupar e depois resumir com Select faz uma linha de relatório por grupo.
• O segundo parâmetro escolhe o que entra no grupo; a chave pode ser calculada (faixas, bool).
• Sintaxe de consulta: group p by chave into g. Atalhos: CountBy (.NET 9) e ToLookup.
• Chave com vários elementos é grupo, não dicionário: ToDictionary com chave repetida dá ArgumentException.

Próxima aula: Agregar (Count, Sum, Average).