• Reference >
• mongo Shell Methods >
• Collection Methods >
• db.collection.aggregate()

db.collection.aggregate()

Definition

db.collection.aggregate(pipeline, options)

mongo Shell Method

This page documents the mongo shell method, and does not refer to the MongoDB Node.js driver (or any other driver) method. For corresponding MongoDB driver API, refer to your specific MongoDB driver documentation instead.

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. 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. 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. Not available in multi-document transactions.
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. Starting in MongoDB 4.2, the profiler log messages and diagnostic log messages includes a usedDisk indicator if any aggregation stage wrote data to temporary files due to memory restrictions.
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.
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. Applicable only if you specify the $out or $merge aggregation stages. 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. Starting in MongoDB 3.6, the readConcern option has the following syntax: readConcern: { level: <value> } Possible read concern levels are: "local". This is the default read concern level for read operations against primary and read operations against secondaries when associated with causally consistent sessions. "available". This is the default for reads against secondaries when when not associated with causally consistent sessions. The query returns the instance’s most recent data. "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. Starting in MongoDB 4.2, the $out stage cannot be used in conjunction with read concern "linearizable". That is, if you specify "linearizable" read concern for db.collection.aggregate(), you cannot include the $out stage in the pipeline. The $merge stage cannot be used in conjunction with read concern "linearizable". That is, if you specify "linearizable" read concern for db.collection.aggregate(), you cannot include the $merge stage in the pipeline.
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: copy 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.
hint	string or document	Optional. The index to use for the aggregation. The index is on the initial collection/view against which the aggregation is run. Specify the index either by the index name or by the index specification document. Note The hint does not apply to $lookup and $graphLookup stages. New in version 3.6.
comment	string	Optional. Users can specify an arbitrary string to help trace the operation through the database profiler, currentOp, and logs. New in version 3.6.
writeConcern	document	Optional. A document that expresses the write concern to use with the $out or $merge stage. Omit to use the default write concern with the $out or $merge stage.

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.

Behavior

Error Handling

If an error occurs, the aggregate() helper throws an exception.

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:

cursor.hasNext() cursor.next() cursor.toArray() cursor.forEach()

cursor.map() cursor.objsLeftInBatch() cursor.itcount() cursor.pretty()

See also

For more information, see Aggregation Pipeline, Aggregation Reference, Aggregation Pipeline Limits, and aggregate.

Sessions

New in version 4.0.

For cursors created inside a session, you cannot call getMore outside the session.

Similarly, for cursors created outside of a session, you cannot call getMore inside a session.

Session Idle Timeout

Starting in MongoDB 3.6, MongoDB drivers and the mongo shell associate all operations with a server session, with the exception of unacknowledged write operations. For operations not explicitly associated with a session (i.e. using Mongo.startSession()), MongoDB drivers and the mongo shell creates an implicit session and associates it with the operation.

If a session is idle for longer than 30 minutes, the MongoDB server marks that session as expired and may close it at any time. When the MongoDB server closes the session, it also kills any in-progress operations and open cursors associated with the session. This includes cursors configured with noCursorTimeout or a maxTimeMS greater than 30 minutes.

For operations that return a cursor, if the cursor may be idle for longer than 30 minutes, issue the operation within an explicit session using Session.startSession() and periodically refresh the session using the refreshSessions command. See Session Idle Timeout for more information.

Transactions

db.collection.aggregate() can be used inside multi-document transactions.

However, the following stages are not allowed within transactions:

• $collStats
• $currentOp
• $indexStats
• $listLocalSessions
• $listSessions
• $out
• $merge
• $planCacheStats

You also cannot specify the explain option.

• For cursors created outside of a transaction, you cannot call getMore inside the transaction.
• For cursors created in a transaction, you cannot call getMore outside the transaction.

Important

In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for multi-document transactions.

For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.

Client Disconnection

For db.collection.aggregate() operation that do not include the $out or $merge stages:

Starting in MongoDB 4.2, if the client that issued the db.collection.aggregate() disconnects before the operation completes, MongoDB marks the db.collection.aggregate() for termination (i.e. killOp on the operation).

Examples

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

copy

{ _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:

copy

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:

copy

{ "_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 example uses db.collection.explain() to view detailed information regarding the execution plan of the aggregation pipeline.

copy

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

The operation returns a document that details 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.

You can view more verbose explain output by passing the executionStats or allPlansExecution explain modes to the db.collection.explain() method.

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

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:

copy

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

Starting in MongoDB 4.2, the profiler log messages and diagnostic log messages includes a usedDisk indicator if any aggregation stage wrote data to temporary files due to memory restrictions.

Specify an Initial Batch Size

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

copy

cursor: { batchSize: <int> }

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

copy

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:

copy

{ _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:

copy

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.

Hint an Index

New in version 3.6.

Create a collection foodColl with the following documents:

copy

db.foodColl.insert([
   { _id: 1, category: "cake", type: "chocolate", qty: 10 },
   { _id: 2, category: "cake", type: "ice cream", qty: 25 },
   { _id: 3, category: "pie", type: "boston cream", qty: 20 },
   { _id: 4, category: "pie", type: "blueberry", qty: 15 }
])

Create the following indexes:

copy

db.foodColl.createIndex( { qty: 1, type: 1 } );
db.foodColl.createIndex( { qty: 1, category: 1 } );

The following aggregation operation includes the hint option to force the usage of the specified index:

copy

db.foodColl.aggregate(
   [ { $sort: { qty: 1 }}, { $match: { category: "cake", qty: 10  } }, { $sort: { type: -1 } } ],
   { hint: { qty: 1, category: 1 } }
)

Override readConcern

Use the readConcern option to specify the read concern for the operation.

You cannot use the $out or the $merge stage in conjunction with read concern "linearizable". That is, if you specify "linearizable" read concern for db.collection.aggregate(), you cannot include either stages in the pipeline.

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", replica sets must use WiredTiger storage engine.

  You can disable read concern "majority" for a deployment with a three-member primary-secondary-arbiter (PSA) architecture; however, this has implications for change streams (in MongoDB 4.0 and earlier only) and transactions on sharded clusters. For more information, see Disable Read Concern Majority.

• 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.

• Starting in MongoDB 4.2, you can specify read concern level "majority" for an aggregation that includes an $out stage.

  In MongoDB 4.0 and earlier, you cannot include the $out stage to use "majority" read concern for the aggregation.

• 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.

copy

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

Specify a Comment

A collection named movies contains documents formatted as such:

copy

{
  "_id" : ObjectId("599b3b54b8ffff5d1cd323d8"),
  "title" : "Jaws",
  "year" : 1975,
  "imdb" : "tt0073195"
}

The following aggregation operation finds movies created in 1995 and includes the comment option to provide tracking information in the logs, the db.system.profile collection, and db.currentOp.

copy

db.movies.aggregate( [ { $match: { year : 1995 } } ], { comment : "match_all_movies_from_1995" } ).pretty()

On a system with profiling enabled, you can then query the system.profile collection to see all recent similar aggregations, as shown below:

copy

db.system.profile.find( { "command.aggregate": "movies", "command.comment" : "match_all_movies_from_1995" } ).sort( { ts : -1 } ).pretty()

This will return a set of profiler results in the following format:

copy

{
  "op" : "command",
  "ns" : "video.movies",
  "command" : {
    "aggregate" : "movies",
    "pipeline" : [
      {
        "$match" : {
          "year" : 1995
        }
      }
    ],
    "comment" : "match_all_movies_from_1995",
    "cursor" : {

    },
    "$db" : "video"
  },
  ...
}

An application can encode any arbitrary information in the comment in order to more easily trace or identify specific operations through the system. For instance, an application might attach a string comment incorporating its process ID, thread ID, client hostname, and the user who issued the command.

←   Collection Methods db.collection.bulkWrite()  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.