db.aggregate()

Definition

New in version 3.6.

• db.aggregate()
• Runs a specified admin/diagnostic pipeline which does not require anunderlying collection. For aggregations on collection data, seedb.collection.aggregate().

The db.aggregate() method has the following syntax:

db.aggregate( [ <pipeline> ], { <options> } )

• The pipeline parameter is an array of stages to execute. Itmust start with a compatible stage that does not require anunderlying collection, such as $currentOp or$listLocalSessions.

• The options document can contain the following fields and values:

FieldTypeDescriptionexplainbooleanOptional. Specifies to return the information on the processing of the pipeline. SeeReturn Information on Aggregation Pipeline Operation for an example.

Not available in multi-document transactions.allowDiskUsebooleanOptional. Enables writing to temporary files. When set to true, aggregationoperations can write data to the _tmp subdirectory in thedbPath directory. SeePerform Large Sort Operation with External Sort for an example.

Starting in MongoDB 4.2, the profiler log messages and diagnostic logmessages includes a usedDiskindicator if any aggregation stage wrote data to temporary files dueto memory restrictions.cursordocumentOptional. Specifies the initial batch size for the cursor. The value of the cursorfield is a document with the field batchSize. SeeSpecify an Initial Batch Size for syntax and example.

New in version 2.6.

maxTimeMSnon-negative integerOptional. Specifies a time limit in milliseconds for processingoperations on a cursor. If you do not specify a value for maxTimeMS,operations will not time out. A value of 0 explicitlyspecifies the default unbounded behavior.

MongoDB terminates operations that exceed their allotted time limitusing the same mechanism as db.killOp(). MongoDB onlyterminates an operation at one of its designated interruptpoints.bypassDocumentValidationbooleanOptional. Applicable only if you specify the $out or $merge aggregationstages.

Enables db.collection.aggregate to bypass document validationduring the operation. This lets you insert documents that do notmeet the validation requirements.

New in version 3.2.

readConcerndocumentOptional. Specifies the read concern.

Starting in MongoDB 3.6, the readConcern option has the followingsyntax: readConcern: { level: <value> }

Possible read concern levels are:

- [<code>&#34;local&#34;</code>]($683517743a7b4361.md#readconcern.&#34;local&#34;). This is the default read concern level forread operations against primary and read operations againstsecondaries when associated with [causally consistent sessions]($fb08affb461c286f.md#causal-consistency).
- [<code>&#34;available&#34;</code>]($282d780c787b0ee8.md#readconcern.&#34;available&#34;). This is the default for reads againstsecondaries when when not associated with [causally consistentsessions]($fb08affb461c286f.md#causal-consistency). The query returns the instance’s mostrecent data.
- [<code>&#34;majority&#34;</code>]($d41917d7e1046d70.md#readconcern.&#34;majority&#34;). Available for replica sets that use[WiredTiger storage engine]($88176f2bf52d95dc.md#storage-wiredtiger).
- [<code>&#34;linearizable&#34;</code>]($59d5f5aa55a16cce.md#readconcern.&#34;linearizable&#34;). Available for read operations on the[<code>primary</code>]($e211822e3d52c6b9.md#replstate.PRIMARY) only.

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

Starting in MongoDB 4.2, the $out stage cannot be usedin conjunction with read concern "linearizable". Thatis, if you specify "linearizable" read concern fordb.collection.aggregate(), you cannot include the$out stage in the pipeline.

The $merge stage cannot be used in conjunction with readconcern "linearizable". That is, if you specify"linearizable" read concern fordb.collection.aggregate(), you cannot include the$merge stage in the pipeline.collationdocumentOptional.

Specifies the collation to use for the operation.

Collation allows users to specifylanguage-specific rules for string comparison, such as rules forlettercase 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; allother collation fields are optional. For descriptions of the fields,see Collation Document.

If the collation is unspecified but the collection has adefault collation (see db.createCollection()), theoperation uses the collation specified for the collection.

If no collation is specified for the collection or for theoperations, MongoDB uses the simple binary comparison used in priorversions for string comparisons.

You cannot specify multiple collations for an operation. Forexample, you cannot specify different collations per field, or ifperforming a find with a sort, you cannot use one collation for thefind and another for the sort.

New in version 3.4.

hintstring or documentOptional. The index to use for the aggregation. The index is on the initialcollection/view against which the aggregation is run.

Specify the index either by the index name or by the indexspecification document.

Note

The hint does not apply to $lookup and$graphLookup stages.

New in version 3.6.

commentstringOptional. Users can specify an arbitrary string to help trace the operationthrough the database profiler, currentOp, and logs.

New in version 3.6.

writeConcerndocumentOptional. A document that expresses the write concernto use with the $out or $merge stage.

Omit to use the default write concern with the $out or$merge stage.

Example

Pipeline with $currentOp

The following example runs a pipeline with two stages. The first stageruns the $currentOp operation and the second stage filters theresults of that operation.

use admin
db.aggregate( [ {
   $currentOp : { allUsers: true, idleConnections: true } }, {
   $match : { shard: "shard01" }
   }
] )