OPTIONS

$group (aggregation)

$group

Groups documents together for the purpose of calculating aggregate values based on a collection of documents. In practice, $group often supports tasks such as average page views for each page in a website on a daily basis.

Important

The output of $group is not ordered.

The output of $group depends on how you define groups. Begin by specifying an identifier (i.e. an _id field) for the group you’re creating with this pipeline. For this _id field, you can specify various expressions, including a single field from the documents in the pipeline, a computed value from a previous stage, a document that consists of multiple fields, and other valid expressions, such as constant or subdocument fields. You can use $project operators in expressions for the _id field.

The following example of an _id field specifies a document that consists of multiple fields:

{ $group: { _id : { author: '$author', pageViews: '$pageViews', posted: '$posted' } } }

Every $group expression must specify an _id field. In addition to the _id field, $group expression can include computed fields. These other fields must use one of the following accumulators:

With the exception of the _id field, $group cannot output nested documents.

Tip

Use $project as needed to rename the grouped field after a $group operation.

Variables

Changed in version 2.6.

You can use variables in expressions for the $group phase. See $let and $map.

The system variables $$CURRENT and $$ROOT are also available directly. See Group Documents by author for an example.

$group Operator and Memory

The $group stage has a limit of 100 megabytes of RAM. By default, if the stage exceeds this limit, $group will produce an error. However, to allow for the handling of large datasets, set the allowDiskUse option to true to enable $group operations to write to temporary files. See the allowDiskUse option in db.collection.aggregate() method and the aggregate command for details.

Changed in version 2.6: MongoDB introduces a limit of 100 megabytes of RAM for the $group stage.

Examples

Calculate Count and Sum

Consider the following example:

db.article.aggregate(
    { $group : {
        _id : "$author",
        docsPerAuthor : { $sum : 1 },
        viewsPerAuthor : { $sum : "$pageViews" }
    }}
);

This aggregation pipeline groups by the author field and computes two fields, docsPerAuthor and viewsPerAuthor, per each group. The docsPerAuthor field is a counter field that uses the $sum operator to add 1 for each document with a given author. The viewsPerAuthor field is the sum of the values in the pageViews field for each group.

Pivot Data

A collection books contains the following documents:

{ "_id" : 8751, "title" : "The Banquet", "author" : "Dante", "copies" : 2 }
{ "_id" : 8752, "title" : "Divine Comedy", "author" : "Dante", "copies" : 1 }
{ "_id" : 8645, "title" : "Eclogues", "author" : "Dante", "copies" : 2 }
{ "_id" : 7000, "title" : "The Odyssey", "author" : "Homer", "copies" : 10 }
{ "_id" : 7020, "title" : "Iliad", "author" : "Homer", "copies" : 10 }

Group title by author

The following aggregation operation pivots the data in the books collection to have titles grouped by authors.

db.books.aggregate(
   [
     { $group : { _id : "$author", books: { $push: "$title" } } }
   ]
)

The operation returns the following documents:

{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }
{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }

Group Documents by author

The following aggregation operation uses the $$ROOT system variable to group the documents by authors. The resulting documents must not exceed the BSON Document Size limit.

db.books.aggregate(
   [
     { $group : { _id : "$author", books: { $push: "$$ROOT" } } }
   ]
)

The operation returns the following documents:

{
  "_id" : "Homer",
  "books" :
     [
       { "_id" : 7000, "title" : "The Odyssey", "author" : "Homer", "copies" : 10 },
       { "_id" : 7020, "title" : "Iliad", "author" : "Homer", "copies" : 10 }
     ]
}

{
  "_id" : "Dante",
  "books" :
     [
       { "_id" : 8751, "title" : "The Banquet", "author" : "Dante", "copies" : 2 },
       { "_id" : 8752, "title" : "Divine Comedy", "author" : "Dante", "copies" : 1 },
       { "_id" : 8645, "title" : "Eclogues", "author" : "Dante", "copies" : 2 }
     ]
}