db.collection.aggregate()¶

On this page

Definition¶

db.collection.aggregate(pipeline, options)¶

Calculates aggregate values for the data in a collection or a view.

Parameter	Type	Description
`pipeline`	array	A sequence of data aggregation operations or stages. See the aggregation pipeline operators for details. Changed in version 2.6: The method can still accept the pipeline stages as separate arguments instead of as elements in an array; however, if you do not specify the `pipeline` as an array, you cannot specify the `options` parameter.
`options`	document	Optional. Additional options that `aggregate()` passes to the `aggregate` command. New in version 2.6: Available only if you specify the `pipeline` as an array.

The options document can contain the following fields and values:

Field	Type	Description
`explain`	boolean	Optional. Specifies to return the information on the processing of the pipeline. See Return Information on Aggregation Pipeline Operation for an example. New in version 2.6.
`allowDiskUse`	boolean	Optional. Enables writing to temporary files. When set to `true`, aggregation operations can write data to the `_tmp` subdirectory in the `dbPath` directory. See Perform Large Sort Operation with External Sort for an example. New in version 2.6.
`cursor`	document	Optional. Specifies the initial batch size for the cursor. The value of the `cursor` field is a document with the field `batchSize`. See Specify an Initial Batch Size for syntax and example. New in version 2.6.
`maxTimeMS`	non-negative integer	Optional. Specifies a time limit in milliseconds for processing operations on a cursor. If you do not specify a value for maxTimeMS, operations will not time out. A value of `0` explicitly specifies the default unbounded behavior. MongoDB terminates operations that exceed their allotted time limit using the same mechanism as `db.killOp()`. MongoDB only terminates an operation at one of its designated interrupt points.
`bypassDocumentValidation`	boolean	Optional. Available only if you specify the `$out` aggregation operator. Enables `db.collection.aggregate` to bypass document validation during the operation. This lets you insert documents that do not meet the validation requirements. New in version 3.2.
`readConcern`	document	Optional. Specifies the read concern. The option has the following syntax: readConcern: { level: <value> } Possible read concern values are: `"local"`. This is the default read concern level. `"majority"`. Available for replica sets that use WiredTiger storage engine. `"linearizable"`. Available for read operations on the `primary` only. For more formation on the read concern levels, see Read Concern Levels.
`collation`	document	Optional. Specifies the collation to use for the operation. Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. The collation option has the following syntax: collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean> } When specifying collation, the `locale` field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document. If the collation is unspecified but the collection has a default collation (see `db.createCollection()`), the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons. You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort. New in version 3.4.

Returns:

A cursor to the documents produced by the final stage of the aggregation pipeline operation, or if you include the explain option, the document that provides details on the processing of the aggregation operation.

If the pipeline includes the $out operator, aggregate() returns an empty cursor. See $out for more information.

Changed in version 2.6: The db.collection.aggregate() method returns a cursor and can return result sets of any size. Previous versions returned all results in a single document, and the result set was subject to a size limit of 16 megabytes.

Behavior¶

Error Handling¶

Changed in version 2.4: If an error occurs, the aggregate() helper throws an exception. In previous versions, the helper returned a document with the error message and code, and ok status field not equal to 1, same as the aggregate command.

Cursor Behavior¶

In the mongo shell, if the cursor returned from the db.collection.aggregate() is not assigned to a variable using the var keyword, then the mongo shell automatically iterates the cursor up to 20 times. See Iterate a Cursor in the mongo Shell for handling cursors in the mongo shell.

Cursors returned from aggregation only supports cursor methods that operate on evaluated cursors (i.e. cursors whose first batch has been retrieved), such as the following methods:

Examples¶

The following examples use the collection orders that contains the following documents:

{ _id: 1, cust_id: "abc1", ord_date: ISODate("2012-11-02T17:04:11.102Z"), status: "A", amount: 50 }
{ _id: 2, cust_id: "xyz1", ord_date: ISODate("2013-10-01T17:04:11.102Z"), status: "A", amount: 100 }
{ _id: 3, cust_id: "xyz1", ord_date: ISODate("2013-10-12T17:04:11.102Z"), status: "D", amount: 25 }
{ _id: 4, cust_id: "xyz1", ord_date: ISODate("2013-10-11T17:04:11.102Z"), status: "D", amount: 125 }
{ _id: 5, cust_id: "abc1", ord_date: ISODate("2013-11-12T17:04:11.102Z"), status: "A", amount: 25 }

Group by and Calculate a Sum¶

The following aggregation operation selects documents with status equal to "A", groups the matching documents by the cust_id field and calculates the total for each cust_id field from the sum of the amount field, and sorts the results by the total field in descending order:

db.orders.aggregate([
                     { $match: { status: "A" } },
                     { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                     { $sort: { total: -1 } }
                   ])

The operation returns a cursor with the following documents:

{ "_id" : "xyz1", "total" : 100 }
{ "_id" : "abc1", "total" : 75 }

The mongo shell iterates the returned cursor automatically to print the results. See Iterate a Cursor in the mongo Shell for handling cursors manually in the mongo shell.

Return Information on Aggregation Pipeline Operation¶

The following aggregation operation sets the option explain to true to return information about the aggregation operation.

db.orders.aggregate(
                     [
                       { $match: { status: "A" } },
                       { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                       { $sort: { total: -1 } }
                     ],
                     {
                       explain: true
                     }
                   )

The operation returns a cursor with the document that contains detailed information regarding the processing of the aggregation pipeline. For example, the document may show, among other details, which index, if any, the operation used. [1] If the orders collection is a sharded collection, the document would also show the division of labor between the shards and the merge operation, and for targeted queries, the targeted shards.

Note

The intended readers of the explain output document are humans, and not machines, and the output format is subject to change between releases.

The mongo shell iterates the returned cursor automatically to print the results. See Iterate a Cursor in the mongo Shell for handling cursors manually in the mongo shell.

Perform Large Sort Operation with External Sort¶

Aggregation pipeline stages have maximum memory use limit. To handle large datasets, set allowDiskUse option to true to enable writing data to temporary files, as in the following example:

var results = db.stocks.aggregate(
                                   [
                                     { $project : { cusip: 1, date: 1, price: 1, _id: 0 } },
                                     { $sort : { cusip : 1, date: 1 } }
                                   ],
                                   {
                                     allowDiskUse: true
                                   }
                                 )

Specify an Initial Batch Size¶

To specify an initial batch size for the cursor, use the following syntax for the cursor option:

cursor: { batchSize: <int> }

For example, the following aggregation operation specifies the initial batch size of 0 for the cursor:

db.orders.aggregate(
                     [
                       { $match: { status: "A" } },
                       { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                       { $sort: { total: -1 } },
                       { $limit: 2 }
                     ],
                     {
                       cursor: { batchSize: 0 }
                     }
                   )

A batchSize of 0 means an empty first batch and is useful for quickly returning a cursor or failure message without doing significant server-side work. Specify subsequent batch sizes to OP_GET_MORE operations as with other MongoDB cursors.

The mongo shell iterates the returned cursor automatically to print the results. See Iterate a Cursor in the mongo Shell for handling cursors manually in the mongo shell.

Specify a Collation¶

New in version 3.4.

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

A collection myColl has the following documents:

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

The following aggregation operation includes the collation option:

db.myColl.aggregate(
   [ { $match: { status: "A" } }, { $group: { _id: "$category", count: { $sum: 1 } } } ],
   { collation: { locale: "fr", strength: 1 } }
);

Note

If performing an aggregation that involves multiple views, such as with $lookup or $graphLookup, the views must have the same collation.

For descriptions on the collation fields, see Collation Document.

Override `readConcern`¶

The following operation on a replica set specifies a Read Concern of "majority" to read the most recent copy of the data confirmed as having been written to a majority of the nodes.

Note

To use read concern level of "majority",
- you must start the mongod instances with the --enableMajorityReadConcern command line option (or the replication.enableMajorityReadConcern set to true if using a configuration file).
- replica sets must use WiredTiger storage engine and election protocol version 1.
To ensure that a single thread can read its own writes, use "majority" read concern and "majority" write concern against the primary of the replica set.
To use a read concern level of "majority", you cannot include the $out stage.
Regardless of the read concern level, the most recent data on a node may not reflect the most recent version of the data in the system.

db.restaurants.aggregate(
   [ { $match: { rating: { $lt: 5 } } } ],
   { readConcern: { level: "majority" } }
)

[1]	Index Filters can affect the choice of index used. See Index Filters for details.

← Collection Methods db.collection.bulkWrite() →

db.collection.aggregate()¶

Definition¶

Behavior¶

Error Handling¶

Cursor Behavior¶

Examples¶

Group by and Calculate a Sum¶

Return Information on Aggregation Pipeline Operation¶

Perform Large Sort Operation with External Sort¶

Specify an Initial Batch Size¶

Specify a Collation¶

Override readConcern¶

Override `readConcern`¶