On this page

• Definition
• Behavior
• Examples

Definition

group

Deprecated since version 3.4: Mongodb 3.4 deprecates the group command. Use db.collection.aggregate() with the $group stage or db.collection.mapReduce() instead.

Note

Because group uses JavaScript, it is subject to a number of performance limitations. For most cases the $group operator in the aggregation pipeline provides a suitable alternative with fewer restrictions.

Groups documents in a collection by the specified key and performs simple aggregation functions, such as computing counts and sums. The command is analogous to a SELECT <...> GROUP BY statement in SQL. The command returns a document with the grouped records as well as the command meta-data.

The group command takes the following prototype form:

copy

{
  group:
   {
     ns: <namespace>,
     key: <key>,
     $reduce: <reduce function>,
     $keyf: <key function>,
     cond: <query>,
     finalize: <finalize function>
   }
}

The command accepts a document with the following fields:

Field	Type	Description
ns	string	The collection from which to perform the group by operation.
key	document	The field or fields to group. Returns a “key object” for use as the grouping key.
$reduce	function	An aggregation function that operates on the documents during the grouping operation. These functions may return a sum or a count. The function takes two arguments: the current document and an aggregation result document for that group.
initial	document	Initializes the aggregation result document.
$keyf	function	Optional. Alternative to the key field. Specifies a function that creates a “key object” for use as the grouping key. Use $keyf instead of key to group by calculated fields rather than existing document fields.
cond	document	Optional. The selection criteria to determine which documents in the collection to process. If you omit the cond field, group processes all the documents in the collection for the group operation.
finalize	function	Optional. A function that runs each item in the result set before group returns the final value. This function can either modify the result document or replace the result document as a whole. Unlike the $keyf and $reduce fields that also specify a function, this field name is finalize, not $finalize.

For the shell, MongoDB provides a wrapper method db.collection.group(). However, the db.collection.group() method takes the keyf field and the reduce field whereas the group command takes the $keyf field and the $reduce field.

Behavior

Examples

The following are examples of the db.collection.group() method. The examples assume an orders collection with documents of the following prototype:

{
  _id: ObjectId("5085a95c8fada716c89d0021"),
  ord_dt: ISODate("2012-07-01T04:00:00Z"),
  ship_dt: ISODate("2012-07-02T04:00:00Z"),
  item:
    {
      sku: "abc123",
      price: 1.99,
      uom: "pcs",
      qty: 25
    }
}

db.runCommand(
   {
     group:
       {
         ns: 'orders',
         key: { ord_dt: 1, 'item.sku': 1 },
         cond: { ord_dt: { $gt: new Date( '01/01/2012' ) } },
         $reduce: function ( curr, result ) { },
         initial: { }
       }
   }
)

{ "retval" :
      [ { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc123"},
        { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "abc456"},
        { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "bcd123"},
        { "ord_dt" : ISODate("2012-07-01T04:00:00Z"), "item.sku" : "efg456"},
        { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "abc123"},
        { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "efg456"},
        { "ord_dt" : ISODate("2012-06-01T04:00:00Z"), "item.sku" : "ijk123"},
        { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc123"},
        { "ord_dt" : ISODate("2012-05-01T04:00:00Z"), "item.sku" : "abc456"},
        { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc123"},
        { "ord_dt" : ISODate("2012-06-08T04:00:00Z"), "item.sku" : "abc456"}
      ],
  "count" : 13,
  "keys" : 11,
  "ok" : 1 }

SELECT ord_dt, item_sku
FROM orders
WHERE ord_dt > '01/01/2012'
GROUP BY ord_dt, item_sku

db.runCommand(
   { group:
       {
         ns: 'orders',
         key: { ord_dt: 1, 'item.sku': 1 },
         cond: { ord_dt: { $gt: new Date( '01/01/2012' ) } },
         $reduce: function ( curr, result ) {
                     result.total += curr.