db.aggregate()
On this page
Definition
New in version 3.6.
db.aggregate()
Runs a specified admin/diagnostic pipeline which does not require an underlying collection. For aggregations on collection data, see
db.collection.aggregate()
.The
db.aggregate()
method has the following syntax:db.aggregate( [ <pipeline> ], { <options> } ) The
pipeline
parameter is an array of stages to execute. It must start with a compatible stage that does not require an underlying collection, such as$currentOp
or$listLocalSessions
.The
options
document can contain the following fields and values:FieldTypeDescriptionexplain
booleanOptional. 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
booleanOptional. Enables writing to temporary files. When set to
true
, aggregation operations can write data to the_tmp
subdirectory in thedbPath
directory. See Perform Large Sort Operation with External Sort for an example.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
documentOptional. Specifies the initial batch size for the cursor. The value of thecursor
field is a document with the fieldbatchSize
. See Specify an Initial Batch Size for syntax and example.maxTimeMS
non-negative integerOptional. 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
booleanOptional. 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
documentOptional. Specifies the read concern.
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 the primary and secondaries."available"
. Available for read operations against the primary and secondaries."available"
behaves the same as"local"
against the primary and non-sharded secondaries. 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 theprimary
only.
For more formation on the read concern levels, see Read Concern Levels.
The
$out
stage cannot be used in conjunction with read concern"linearizable"
. 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 read concern"linearizable"
. That is, if you specify"linearizable"
read concern fordb.collection.aggregate()
, you cannot include the$merge
stage in the pipeline.collation
documentOptional.
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 documentOptional. 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
stringOptional. Users can specify an arbitrary string to help trace the operation through the database profiler, currentOp, and logs.
New in version 3.6.
writeConcern
documentOptional. 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.
Compatibility
This method is available in deployments hosted in the following environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
Note
This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Example
Pipeline with $currentOp
The following example runs a pipeline with two stages. The first stage
runs the $currentOp
operation and the second stage filters the
results of that operation.
use admin db.aggregate( [ { $currentOp : { allUsers: true, idleConnections: true } }, { $match : { shard: "shard01" } } ] )