Docs4dev
Docs
mongodb / v3.6 / reference / reference-method-db.collection.aggregate.html

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, most aggregation operations can write data to the _tmp subdirectory in the dbPath directory with the following exceptions:

  • $graphLookup stage
  • $addToSet accumulator expression used in the $group stage (Starting in version 3.6.17)
  • $push accumulator expression used in the $group stage (Starting in version 3.6.17)

For an example of allowDiskUse, see Perform Large Sort Operation with External Sort.

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 readConcern option has the following syntax:

Changed in version 3.6.

readConcern: { level: <value> }

Possible read concern levels are:

For more formation on the read concern levels, see Read Concern Levels.

For "local" (default) or "majority" read concern level, you can specify the afterClusterTime option to have the read operation return data that meets the level requirement and the specified after cluster time requirement. For more information, see Read Operations and Causally Consistent Sessions.
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.
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.
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

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:

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.

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