Docs Home → Develop Applications → MongoDB Manual
db.collection.aggregate()![](/zh-cn/docs/v5.3/assets/link.svg)
On this page
Definition![](/zh-cn/docs/v5.3/assets/link.svg)
db.collection.aggregate(pipeline, options)
Important
mongosh Method
This is a
mongosh
method. This is not the documentation forNode.js
or other programming language specific driver methods.In most cases,
mongosh
methods work the same way as the legacymongo
shell methods. However, some legacy methods are unavailable inmongosh
.For the legacy
mongo
shell documentation, refer to the documentation for the corresponding MongoDB Server release:For MongoDB API drivers, refer to the language specific MongoDB driver documentation.
Calculates aggregate values for the data in a collection or a view.
ParameterTypeDescriptionpipeline
arrayA 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 theoptions
parameter.options
documentOptional. Additional options thataggregate()
passes to theaggregate
command. Available only if you specify thepipeline
as an array.The
options
document can contain the following fields and values:Changed in version 5.0.
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.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
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.readConcern
documentOptional. 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 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.
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 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.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.
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.comment
stringOptional. Users can specify an arbitrary string to help trace the operation through the database profiler, currentOp, and logs.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.let
documentOptional.
Specifies a document with a list of variables. This allows you to improve command readability by separating the variables from the query text.
The document syntax is:
{ <variable_name_1>: <expression_1>, ..., <variable_name_n>: <expression_n> } The variable is set to the value returned by the expression, and cannot be changed afterwards.
To access the value of a variable in the command, use the double dollar sign prefix (
$$
) together with your variable name in the form$$<variable_name>
. For example:$$targetTotal
.Note
For a complete example using
let
and variables, see Use Variables inlet
.New in version 5.0.
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![](/zh-cn/docs/v5.3/assets/link.svg)
Error Handling![](/zh-cn/docs/v5.3/assets/link.svg)
If an error occurs, the aggregate()
helper
throws an exception.
Cursor Behavior![](/zh-cn/docs/v5.3/assets/link.svg)
In mongosh
, if the cursor returned from the
db.collection.aggregate()
is not assigned to a variable using
the var
keyword, then mongosh
automatically
iterates the cursor up to 20 times. See
Iterate a Cursor in mongosh
for handling cursors in
mongosh
.
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:
Tip
See also:
For more information, see
Aggregation Pipeline, Aggregation Reference,
Aggregation Pipeline Limits, and aggregate
.
Sessions![](/zh-cn/docs/v5.3/assets/link.svg)
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![](/zh-cn/docs/v5.3/assets/link.svg)
Starting in MongoDB 3.6, MongoDB drivers and mongosh
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 mongosh
create an implicit session and associate 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 Mongo.startSession()
and periodically refresh the
session using the refreshSessions
command. See
Session Idle Timeout for more information.
Transactions![](/zh-cn/docs/v5.3/assets/link.svg)
db.collection.aggregate()
can be used inside multi-document transactions.
However, the following stages are not allowed within transactions:
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![](/zh-cn/docs/v5.3/assets/link.svg)
For db.collection.aggregate()
operation that do not include
the $out
or $merge
stages:
Starting in MongoDB 4.2, if the client that issued db.collection.aggregate()
disconnects before the operation completes, MongoDB marks db.collection.aggregate()
for termination using killOp
.
Examples![](/zh-cn/docs/v5.3/assets/link.svg)
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("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![](/zh-cn/docs/v5.3/assets/link.svg)
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:
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:
{ "_id" : "xyz1", "total" : 100 } { "_id" : "abc1", "total" : 75 }
mongosh
iterates the returned cursor automatically
to print the results. See Iterate a Cursor in mongosh
for
handling cursors manually in mongosh
.
Return Information on Aggregation Pipeline Operation![](/zh-cn/docs/v5.3/assets/link.svg)
The following example uses db.collection.explain()
to view
detailed information regarding the execution plan of the aggregation
pipeline.
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![](/zh-cn/docs/v5.3/assets/link.svg)
Each individual pipeline stage has a limit of 100 megabytes of RAM. By default, if a stage exceeds this limit,
MongoDB produces an error. To allow pipeline processing to take up
more space, set the allowDiskUse
option to true
to enable writing data to temporary files, as in the
following example:
var results = db.stocks.aggregate( [ { $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.
Tip
See also:
Specify an Initial Batch Size![](/zh-cn/docs/v5.3/assets/link.svg)
To specify an initial batch size for the cursor, use the following
syntax for the cursor
option:
cursor: { batchSize: <int> }
For example, the following aggregation operation specifies the
initial batch size of 0
for the cursor:
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.
mongosh
iterates the returned cursor automatically
to print the results. See Iterate a Cursor in mongosh
for
handling cursors manually in mongosh
.
Specify a Collation![](/zh-cn/docs/v5.3/assets/link.svg)
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:
{ _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:
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![](/zh-cn/docs/v5.3/assets/link.svg)
Create a collection foodColl
with the following documents:
db.foodColl.insertMany( [ { _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:
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:
db.foodColl.aggregate( [ { $sort: { qty: 1 }}, { $match: { category: "cake", qty: 10 } }, { $sort: { type: -1 } } ], { hint: { qty: 1, category: 1 } } )
Override readConcern
![](/zh-cn/docs/v5.3/assets/link.svg)
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 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.
db.restaurants.aggregate( [ { $match: { rating: { $lt: 5 } } } ], { readConcern: { level: "majority" } } )
Specify a Comment![](/zh-cn/docs/v5.3/assets/link.svg)
A collection named movies
contains documents formatted as such:
{ "_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
.
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:
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:
{ "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.
Use Variables in let
![](/zh-cn/docs/v5.3/assets/link.svg)
New in version 5.0.
To define variables that you can access elsewhere in the command, use the let option.
Note
Create a collection cakeSales
containing sales for cake flavors:
db.cakeSales.insertMany( [ { _id: 1, flavor: "chocolate", salesTotal: 1580 }, { _id: 2, flavor: "strawberry", salesTotal: 4350 }, { _id: 3, flavor: "cherry", salesTotal: 2150 } ] )
The following example:
retrieves the cake that has a
salesTotal
greater than 3000, which is the cake with an_id
of 2defines a
targetTotal
variable inlet
, which is referenced in$gt
as$$targetTotal
db.cakeSales.aggregate( [ { $match: { $expr: { $gt: [ "$salesTotal", "$$targetTotal" ] } } } ], { let: { targetTotal: 3000 } } )