aggregate

On this page

aggregate: Performs aggregation operation using the aggregation pipeline. The pipeline allows users to process data from a collection or other source with a sequence of stage-based manipulations.

Syntax

The command has following syntax:

Changed in version 3.6.

{
  aggregate: "<collection>" || 1,
  pipeline: [ <stage>, <...> ],
  explain: <boolean>,
  allowDiskUse: <boolean>,
  cursor: <document>,
  maxTimeMS: <int>,
  bypassDocumentValidation: <boolean>,
  readConcern: <document>,
  collation: <document>,
  hint: <string or document>,
  comment: <string>,
  writeConcern: <document>
}

Tip

Rather than run the aggregate command directly, most users should use the db.collection.aggregate() helper provided in the mongo shell or the equivalent helper in their driver. In 2.6 and later, the db.collection.aggregate() helper always returns a cursor.

Command Fields

The aggregate command takes the following fields as arguments:

Field	Type	Description
`aggregate`	string	The name of the collection or view that acts as the input for the aggregation pipeline. Use `1` for collection agnostic commands.
`pipeline`	array	An array of aggregation pipeline stages that process and transform the document stream as part of the aggregation pipeline.
`explain`	boolean	Optional. Specifies to return the information on the processing of the pipeline.
allowDiskUse	boolean	Optional. Enables writing to temporary files. When set to `true`, most aggregation stages 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)
`cursor`	document	Specify a document that contains options that control the creation of the cursor object. Changed in version 3.6: MongoDB 3.6 removes the use of `aggregate` command without the `cursor` option unless the command includes the `explain` option. Unless you include the `explain` option, you must specify the cursor option. To indicate a cursor with the default batch size, specify `cursor: {}`. To indicate a cursor with a non-default batch size, use `cursor: { batchSize: <num> }`.
`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 `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. copy `readConcern: { level: <value> }` Possible read concern levels are: `"local"`. This is the default read concern level. `"available"`. This is the default for reads against secondaries when Read Operations and Causally Consistent Sessions and “level” are unspecified. 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. 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: 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 `$out` stage. Omit to use the default write concern with the `$out` stage.

For more information about the aggregation pipeline Aggregation Pipeline, Aggregation Reference, and Aggregation Pipeline Limits.

Sessions

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.

Example

Changed in version 3.4: MongoDB 3.6 removes the use of aggregate command without the cursor option unless the command includes the explain option. Unless you include the explain option, you must specify the cursor option.

To indicate a cursor with the default batch size, specify cursor: {}.

To indicate a cursor with a non-default batch size, use cursor: { batchSize: <num> }.

Except for the first two examples which demonstrate the command syntax, the examples in this page use the db.collection.aggregate() helper.

Aggregate Data with Multi-Stage Pipeline

A collection articles contains documents such as the following:

copy

{
   _id: ObjectId("52769ea0f3dc6ead47c9a1b2"),
   author: "abc123",
   title: "zzz",
   tags: [ "programming", "database", "mongodb" ]
}

The following example performs an aggregate operation on the articles collection to calculate the count of each distinct element in the tags array that appears in the collection.