/ /

$group (estágio de agregação )

Definição

$group

A etapa $group combina múltiplos documentos que possuem os mesmos campos, campo ou expressão em um único documento, conforme uma chave de agrupamento. O resultado é um documento por chave de grupo exclusiva.

A group key is often a field, or group of fields. The group key can also be the result of an expression. Use the _id field in the $group pipeline stage to set the group key. See below for usage examples.

Na saída do estágio $group, o campo _id é definido como a chave de grupo desse documento.

The output documents can also contain additional fields that are set using accumulator expressions.

Observação

$group does not order its output documents.

Compatibilidade

Você pode utilizar o $group para implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

The $group stage has the following prototype form:

{
 $group:
   {
     _id: <expression>, // Group key
     <field1>: { <accumulator1> : <expression1> },
     ...
   }
 }

Campo	Descrição
`_id`	Obrigatório. A expressão `_id` especifica a chave do grupo. Se você especificar um valor `_id` nulo ou qualquer outro valor constante, o estágio `$group` retornará um único documento que agrega valores em todos os documentos de entrada. Veja o exemplo Agrupar nulo.
`field`	Opcional. Computado usando os operadores acumuladores.

The _id and the accumulator operators can accept any valid expression. For more information on expressions, see Expressions.

Considerações

Desempenho

$group é um estágio de bloqueio, que faz com que o pipeline espere que todos os dados de entrada sejam recuperados para o estágio de bloqueio antes de processar os dados. Um estágio de bloqueio pode reduzir o desempenho porque reduz o processamento paralelo de um pipeline com vários estágios. Um estágio de bloqueio também pode usar quantidades substanciais de memória para grandes conjuntos de dados.

Operador acumulador

O operador <accumulator> deve ser um dos seguintes operadores acumuladores:

Nome	Descrição
`$accumulator`	Retorna o resultado de uma função de acumulador definida pelo usuário.
`$addToSet`	Retorna uma array de valores de expressão exclusivos para cada grupo. A ordem dos elementos da array é indefinida.
`$avg`	Retorna uma média de valores numéricos.
`$bottom`	Retorna o elemento inferior de um grupo de acordo com a ordem de classificação especificada.
`$bottomN`	Retorna uma agregação dos campos `n` inferiores dentro de um grupo, de acordo com a ordem de classificação especificada.
`$count`	Retorna o número de documentos em um grupo. Diferente do estágio `$count` do pipeline.
`$first`	Retorna o resultado de uma expressão para o primeiro documento em um grupo.
`$firstN`	Retorna uma agregação dos primeiros `n` elementos dentro de um grupo. Só faz sentido quando os documentos estão em uma ordem definida. Diferente do operador de array `$firstN`.
`$last`	Retorna o resultado de uma expressão para o último documento em um grupo.
`$lastN`	Retorna o resultado da avaliação de uma expressão especificada sobre os últimos n elementos em um grupo.
`$max`	Retorna o valor de expressão mais alto para cada grupo.
`$maxN`	Retorna uma agregação dos `n` elementos com valor máximo em um grupo. Diferente do operador de array `$maxN`.
`$median`	Retorna uma aproximação do valor da mediana (50º percentil) dos documentos em um grupo. Novidades na versão 7.0.
`$mergeObjects`	Retorna um documento criado combinando os documentos de entrada de cada grupo.
`$min`	Retorna o valor de expressão mais baixo para cada grupo.
`$minN`	Retorna uma agregação dos `n` elementos com valor mínimo em um grupo. Distinto do operador de array `$minN` .
`$percentile`	Retorna uma array de valores escalares que correspondem aos valores percentuais especificados. Novidades na versão 7.0.
`$push`	Retorna uma matriz de valores de expressão para documentos em cada grupo.
`$stdDevPop`	Retorna o desvio padrão da população dos valores de documentos em um grupo.
`$stdDevSamp`	Retorna o desvio padrão da amostra dos valores de documentos em um grupo.
`$sum`	Retorna uma soma de valores numéricos. Ignora valores não numéricos.
`$top`	Retorna o principal elemento de um grupo de acordo com a ordem de classificação especificada.
`$topN`	Retorna uma agregação dos principais campos `n` dentro de um grupo, de acordo com a ordem de classificação especificada.

`$group` e restrições de memória

If the $group stage exceeds 100 megabytes of RAM, MongoDB writes data to temporary files. However, if the allowDiskUse option is set to false, $group returns an error. For more information, refer to aggregation pipeline limits.

`$group` Otimizações de desempenho

This section describes optimizations to improve the performance of $group. There are optimizations that you can make manually and optimizations MongoDB makes internally.

Otimização para retornar o primeiro ou último documento de cada grupo

If a pipeline sorts and groups by the same field and the $group stage only uses the $first or $last accumulator operator, consider adding an index on the grouped field which matches the sort order. In some cases, the $group stage can use the index to quickly find the first or last document of each group.

Exemplo

Se a coleção movies contiver um índice { year: 1, title: 1 }, o pipeline a seguir poderá usar esse índice para localizar o primeiro document de cada grupo:

db.movies.aggregate([
   {
      $sort: { year: 1, title: 1 }
   },
   {
      $group: {
         _id: { year: "$year" },
         title: { $first: "$title" }
      }
   }
])

Mecanismo de execução de consulta baseado em slot

Observação

A partir da versão 7.0.17, o mecanismo de execução de queries baseado em slots não está mais ativado por padrão para versões de patch do 7.0. Se você deseja que suas queries usem o mecanismo de execução de queries baseado em slots, atualize para a versão 8.0, onde está habilitado por padrão.

Starting in version 5.2, MongoDB uses the slot-based execution query engine to execute $group stages if either:

$group é o primeiro estágio do pipeline.
Todos os estágios anteriores do pipeline também podem ser executados pelo mecanismo de execução baseado em slot.

Para mais informações, consulte Otimização do$group.

Exemplos

Contagem do número de documentos em uma coleção

Os exemplos nesta página usam dados do conjunto de dados sample_mflix. Para obter detalhes sobre como carregar este conjunto de dados em sua implantação do MongoDB autogerenciado, consulte Carregar o conjunto de dados de amostra. Se você fez alguma modificação nos bancos de dados de amostra, talvez seja necessário descartar e recriar os bancos de dados para executar os exemplos nesta página.

The following aggregation operation uses the $group stage to count the number of documents in the movies collection:

db.movies.aggregate([
   {
      $group: {
         _id: null,
         count: { $count: {} }
      }
   }
])

[
  {
    _id: null,
    count: 21349
  }
]

Esta operação de agregação é equivalente à seguinte declaração SQL:

SELECT COUNT(*) AS count FROM movies

Dica

Retrieve Distinct Values

A seguinte operação de agregação usa o estágio $group para recuperar os valores distintos de rated da coleção movies:

db.movies.aggregate( [ { $group : { _id : "$rated" } } ] )

[
  {
    _id: 'TV-PG'
  },
  {
    _id: 'PG'
  },
  {
    _id: 'TV-14'
  },
  {
    _id: 'OPEN'
  },
  {
    _id: 'Not Rated'
  },
  {
    _id: 'GP'
  },
  {
    _id: 'TV-Y7'
  },
  {
    _id: 'G'
  },
  {
    _id: 'PG-13'
  },
  {
    _id: null
  },
  {
    _id: 'M'
  },
  {
    _id: 'R'
  },
  {
    _id: 'TV-MA'
  },
  {
    _id: 'APPROVED'
  },
  {
    _id: 'PASSED'
  },
  {
    _id: 'Approved'
  },
  {
    _id: 'AO'
  },
  {
    _id: 'TV-G'
  }
]

Observação

Quando você utiliza $group para recuperar valores distintos em uma coleção fragmentada, se a operação resultar em DISTINCT_SCAN um, o resultado poderá conter documentos órfãos.

O único pipeline semanticamente correto afetado é efetivamente o equivalente lógico de um comando, em que há distinct um $group estágio no início do pipeline ou próximo a ele e o $group não é precedido por um estágio $sort .

Por exemplo, operações $group do seguinte formulário podem resultar em um DISTINCT_SCAN:

{ $group : { _id : "$<field>" } }

Para obter mais informações sobre o comportamento de recuperar valores distintos, consulte o comportamento de comando distinto.

Para ver se a sua operação resulta em um,DISTINCT_SCAN verifique os resultados de explicação da sua operação.

Agrupar por classificação

A seguinte operação de agregação agrupa documentos pelo campo rated , calculando o tempo de execução total por classificação e retornando apenas as classificações com um tempo de execução total maior ou igual a 100000:

db.movies.aggregate(
   [
      // First Stage
      {
         $group: {
            _id: "$rated",
            totalRuntime: { $sum: "$runtime" }
         }
      },
      // Second Stage
      {
         $match: { "totalRuntime": { $gte: 100000 } }
      }
   ]
)

[
  {
    _id: 'PG-13',
    totalRuntime: 250843
  },
  {
    _id: 'R',
    totalRuntime: 582318
  },
  {
    _id: null,
    totalRuntime: 967127
  },
  {
    _id: 'PG',
    totalRuntime: 191204
  }
]

Primeiro estágio:: The $group stage groups the documents by rated to retrieve the distinct rating values. This stage returns the totalRuntime for each rating group.
Segundo estágio:: O estágio $match filtra os resultantes document para retornar somente classificações com totalRuntime maior ou igual a 100000.

Esta operação de agregação é equivalente à seguinte declaração SQL:

SELECT rated,
   Sum(runtime) AS totalRuntime
FROM   movies
GROUP  BY rated
HAVING totalRuntime >= 100000

Dica

$match

Calcular Count, Sum, e Average

Agrupar por ano

O pipeline a seguir calcula o tempo de execução total, o tempo médio de execução e a contagem de filmes para cada ano anterior a 1910:

db.movies.aggregate([
   { $match: { "year": { $lt: 1910 } } },
   {
      $group: {
         _id: "$year",
         totalRuntime: { $sum: "$runtime" },
         averageRuntime: { $avg: "$runtime" },
         count: { $sum: 1 }
      }
   },
   { $sort: { totalRuntime: -1 } }
])

[
  { _id: 1909, totalRuntime: 14, averageRuntime: 14, count: 1 },
  { _id: 1903, totalRuntime: 11, averageRuntime: 11, count: 1 },
  { _id: 1896, totalRuntime: 2, averageRuntime: 1, count: 2 }
]

Primeiro estágio:: O estágio $match filtra os documentos para passar apenas os filmes lançados antes de 1910 para o próximo estágio.
Segundo estágio:: The $group stage groups the documents by year and calculates the total runtime, average runtime, and total count of the documents in each group.
Terceiro estágio:: O estágio $sort classifica os resultados pelo tempo de execução total para cada grupo em ordem decrescente.

Esta operação de agregação é equivalente à seguinte declaração SQL:

SELECT year,
       Sum(runtime) AS totalRuntime,
       Avg(runtime) AS averageRuntime,
       Count(*)     AS count
FROM   movies
WHERE  year < 1910
GROUP  BY year
ORDER  BY totalRuntime DESC

Dica

$match
$sort
db.collection.countDocuments() which wraps the $group aggregation stage with a $sum expression.

Agrupar por `null`

A operação de agregação a seguir especifica um grupo _id de null, calculando o tempo de execução total, o tempo médio de execução e a contagem de todos os documentos na coleção.

db.movies.aggregate([
   {
      $group: {
         _id: null,
         totalRuntime: { $sum: "$runtime" },
         averageRuntime: { $avg: "$runtime" },
         count: { $sum: 1 }
      }
   }
])

[
  {
    _id: null,
    totalRuntime: 2167458,
    averageRuntime: 103.65652797704448,
    count: 21349
  }
]

Esta operação de agregação é equivalente à seguinte declaração SQL:

SELECT Sum(runtime) AS totalRuntime,
       Avg(runtime) AS averageRuntime,
       Count(*)     AS count
FROM   movies

Dica

$count
db.collection.countDocuments() which wraps the $group aggregation stage with a $sum expression.

Dados dinâmicos

Agrupar títulos por ano

A seguinte operação de agregação dinamiza os dados na coleção movies para agrupar títulos por ano:

db.movies.aggregate([
   { $match: { year: { $lt: 1910 } } },
   { $group: { _id: "$year", titles: { $push: "$title" } } },
   { $sort: { _id: 1 } }
])

[
  { _id: 1896, titles: [ 'The Kiss', 'The Kiss' ] },
  { _id: 1903, titles: [ 'The Great Train Robbery' ] },
  { _id: 1909, titles: [ 'A Corner in Wheat' ] }
]

Agrupar document por ano

A seguinte operação de agregação agrupa document por ano:

db.movies.aggregate([
   { $match: { year: { $lt: 1910 } } },
   { $group: { _id: "$year", movies: { $push: "$$ROOT" } } },
   {
      $addFields: {
         totalRuntime: { $sum: "$movies.runtime" }
      }
   },
   { $sort: { _id: 1 } }
])

[
  { _id: 1896, movies: '...', totalRuntime: 2 },
  { _id: 1903, movies: '...', totalRuntime: 11 },
  { _id: 1909, movies: '...', totalRuntime: 14 }
]

Primeiro estágio:: $match filtra os documentos para passar apenas os filmes lançados antes de 1910 para o próximo estágio.
Segundo estágio:: $group uses the $$ROOT system variable to group the entire documents by year.
Terceiro estágio:: $addFields adiciona um campo à saída contendo o tempo de execução total de filmes para cada ano.
Observação
Os documentos resultantes não devem exceder o limite de Tamanho do documento BSON de 16 mebibytes.
Quarto estágio:: $sort classifica os documentos resultantes por _id em ordem crescente.

Os exemplos de C# nesta página utilizam o banco de dados sample_mflix a partir dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de exemplo, consulte Introdução na documentação do driver MongoDB .NET/C#.

A seguinte classe Movie modela os documentos na collection sample_mflix.movies:

[BsonIgnoreExtraElements]
public class Movie
{
    [BsonId]
    public ObjectId Id { get; set; }
    [BsonElement("title")]
    public string Title { get; set; } = null!;
    [BsonElement("year")]
    public int? Year { get; set; }
    [BsonElement("runtime")]
    public int? Runtime { get; set; }
    [BsonElement("rated")]
    public string? Rated { get; set; }
    [BsonElement("metacritic")]
    public int Metacritic { get; set; }
    [BsonElement("plot")]
    public string? Plot { get; set; }
    [BsonElement("type")]
    public string? Type { get; set; }
    [BsonElement("cast")]
    public string[]? Cast { get; set; }
    [BsonElement("directors")]
    public string[]? Directors { get; set; }
    [BsonElement("writers")]
    public string[]? Writers { get; set; }
    [BsonElement("imdb")]
    public ImdbData? Imdb { get; set; }
}

Para usar o driver MongoDB .NET/C# para adicionar um estágio $group a uma agregação pipeline, chame o método UnionWith() em um objeto PipelineDefinition.

O exemplo a seguir cria um estágio de pipeline que agrupa documentos pelo valor de seu campo Rated. A classificação de cada grupo é mostrada em um campo chamado Rating em cada documento de saída. Cada documento de saída também contém campos chamados TotalRuntime, MedianRuntime e NinetiethPercentileRuntime, que armazenam o total, a mediana e o 90º percentil de tempo de execução para filmes em cada grupo.

var pipeline = new EmptyPipelineDefinition<Movie>()
    .Group(
        id: m => m.Rated,
        group: g => new
        {
            Rating = g.Key,
            TotalRuntime = g.Sum(m => m.Runtime),
            MedianRuntime = g.Select(m => m.Runtime).Median(),
            NinetiethPercentileRuntime =
                g.Select(m => m.Runtime).Percentile(new[] { 0.9 })
        }
    );

{ "Rating" : null, "TotalRuntime" : 967127, "MedianRuntime" : 98.0, "NinetiethPercentileRuntime" : [131.0] }
{ "Rating" : "AO", "TotalRuntime" : 274, "MedianRuntime" : 85.0, "NinetiethPercentileRuntime" : [108.0] }
{ "Rating" : "APPROVED", "TotalRuntime" : 74571, "MedianRuntime" : 103.0, "NinetiethPercentileRuntime" : [134.0] }
{ "Rating" : "Approved", "TotalRuntime" : 472, "MedianRuntime" : 93.0, "NinetiethPercentileRuntime" : [109.0] }
{ "Rating" : "G", "TotalRuntime" : 43044, "MedianRuntime" : 89.0, "NinetiethPercentileRuntime" : [125.0] }
{ "Rating" : "GP", "TotalRuntime" : 4864, "MedianRuntime" : 103.0, "NinetiethPercentileRuntime" : [135.0] }
{ "Rating" : "M", "TotalRuntime" : 4107, "MedianRuntime" : 107.0, "NinetiethPercentileRuntime" : [142.0] }
{ "Rating" : "Not Rated", "TotalRuntime" : 116, "MedianRuntime" : 116.0, "NinetiethPercentileRuntime" : [116.0] }
{ "Rating" : "OPEN", "TotalRuntime" : 85, "MedianRuntime" : 85.0, "NinetiethPercentileRuntime" : [85.0] }
{ "Rating" : "PASSED", "TotalRuntime" : 17778, "MedianRuntime" : 98.0, "NinetiethPercentileRuntime" : [123.0] }
{ "Rating" : "PG", "TotalRuntime" : 191204, "MedianRuntime" : 100.0, "NinetiethPercentileRuntime" : [124.0] }
{ "Rating" : "PG-13", "TotalRuntime" : 250843, "MedianRuntime" : 105.0, "NinetiethPercentileRuntime" : [131.0] }
{ "Rating" : "R", "TotalRuntime" : 582318, "MedianRuntime" : 102.0, "NinetiethPercentileRuntime" : [127.0] }
{ "Rating" : "TV-14", "TotalRuntime" : 10527, "MedianRuntime" : 98.0, "NinetiethPercentileRuntime" : [197.0] }
{ "Rating" : "TV-G", "TotalRuntime" : 4653, "MedianRuntime" : 88.0, "NinetiethPercentileRuntime" : [100.0] }
{ "Rating" : "TV-MA", "TotalRuntime" : 7048, "MedianRuntime" : 96.0, "NinetiethPercentileRuntime" : [223.0] }
{ "Rating" : "TV-PG", "TotalRuntime" : 8183, "MedianRuntime" : 90.0, "NinetiethPercentileRuntime" : [169.0] }
{ "Rating" : "TV-Y7", "TotalRuntime" : 244, "MedianRuntime" : 74.0, "NinetiethPercentileRuntime" : [96.0] }

Os exemplos do Node.js nesta página utilizam o banco de dados do sample_mflix a partir dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de exemplo, consulte Introdução na documentação do driver do MongoDB Node.js

Para usar o driver Node.js do MongoDB para adicionar um estágio $group a um pipeline de agregação , use o operador $group em um objeto de pipeline.

O exemplo a seguir cria um estágio de pipeline que agrupa documentos pelo valor de seu campo rated. Cada documento de saída contém um campo rating que armazena a classificação de cada grupo. Cada documento de saída também contém um campo chamado totalRuntime que armazena o tempo de execução total de todos os filmes do grupo. Em seguida, o exemplo executa o agregação pipeline:

const pipeline = [
  {
    $group: {
      _id: "$rated",
      rating: { $first: "$rated" },
      totalRuntime: { $sum: "$runtime" }
    }
  }
];
const cursor = collection.aggregate(pipeline);
return cursor;

Saiba mais

The Group and Total Data tutorial provides an extensive example of the $group operator in a common use case.

Para saber mais sobre os estágios de pipeline relacionados, consulte o guia$addFields.

Voltar

$graphLookup

$indexStats

$group (estágio de agregação )

Definição

Compatibilidade

Sintaxe

Considerações

Desempenho

Operador acumulador

$group e restrições de memória

$group Otimizações de desempenho

Otimização para retornar o primeiro ou último documento de cada grupo

Mecanismo de execução de consulta baseado em slot

Exemplos

Contagem do número de documentos em uma coleção

Retrieve Distinct Values

Agrupar por classificação

Calcular Count, Sum, e Average

Agrupar por ano

Agrupar por null

Dados dinâmicos

Agrupar títulos por ano

Agrupar document por ano

Saiba mais

`$group` e restrições de memória

`$group` Otimizações de desempenho

Agrupar por `null`