- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.aggregate()
db.collection.aggregate()¶
On this page
New in version 2.2.
Definition¶
-
db.collection.
aggregate
(pipeline, options)¶ Calculates aggregate values for the data in a collection.
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 theoptions
parameter.options
document Optional. Additional options that
aggregate()
passes to theaggregate
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
, aggregation operations can write data to the_tmp
subdirectory in thedbPath
directory. See Perform Large Sort Operation with External Sort for an example.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 fieldbatchSize
. See Specify an Initial Batch Size for syntax and example.New in version 2.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.
Changed in version 2.4: If an error occurs, the aggregate()
helper
throws an exception. In previous versions, the helper returned a
document with the error message and code, and ok
status field
not equal to 1
, same as the aggregate
command.
See also
For more information, see
Aggregation Pipeline, Aggregation Reference,
Aggregation Pipeline Limits, and aggregate
.
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 Cursors for cursor
behavior in the mongo
shell and
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:
|
Examples¶
The examples in this section use the
db.collection.aggregate()
helper provided in the 2.6 version
of the mongo
shell.
The following examples use the collection orders
that contains the
following documents:
Group by and Calculate a Sum¶
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:
The operation returns a cursor with the following documents:
The mongo
shell iterates the returned cursor automatically
to print the results. See Iterate a Cursor in the mongo Shell for
handling cursors manually in the mongo
shell.
Return Information on Aggregation Pipeline Operation¶
The following aggregation operation sets the option explain
to
true
to return information about the aggregation operation.
The operation returns a cursor with the document that contains detailed
information regarding 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.
The mongo
shell iterates the returned cursor automatically
to print the results. See Iterate a Cursor in the mongo Shell for
handling cursors manually in the mongo
shell.
Perform Large Sort Operation with External Sort¶
Aggregation pipeline stages have maximum memory use limit. To handle large datasets, set
allowDiskUse
option to true
to enable writing data to
temporary files, as in the following example:
Specify an Initial Batch Size¶
To specify an initial batch size for the cursor, use the following
syntax for the cursor
option:
For example, the following aggregation operation specifies the
initial batch size of 0
for the cursor:
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.
The mongo
shell iterates the returned cursor automatically
to print the results. See Iterate a Cursor in the mongo Shell for
handling cursors manually in the mongo
shell.
[1] | Index Filters can affect the choice of index used. See Index Filters for details. |