db.collection.aggregate()

Definition

db.collection.aggregate(pipeline, options)

Important

mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the aggregate command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

• mongo shell v4.4

• mongo shell v4.2

Calculates aggregate values for the data in a collection or a view.

Parameter	Type	Description
pipeline	array	A 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 the options parameter.
options	document	Optional. Additional options that aggregate() passes to the aggregate command. Available only if you specify the pipeline as an array.

The options document can contain the following fields and values:

Changed in version 5.0.

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. Not available in multi-document transactions.
allowDiskUse	boolean	Optional. Enables writing to temporary files. When set to true, aggregation operations can write data to the _tmp subdirectory in the dbPath directory. See Interaction with allowDiskUseByDefault 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	document	Optional. Specifies the initial batch size for the cursor. The value of the cursor field is a document with the field batchSize. See Specify an Initial Batch Size for syntax and example.
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. 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	document	Optional. 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 the primary 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 for db.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 for db.collection.aggregate(), you cannot include the $merge stage in the pipeline.
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: 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 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.
comment	string	Optional. Users can specify an arbitrary string to help trace the operation through the database profiler, currentOp, and logs.
writeConcern	document	Optional. 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	document	Optional. 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 To use a variable to filter results in a pipeline $match stage, you must access the variable within the $expr operator. For a complete example using let and variables, see Use Variables in let. New in version 5.0.

Returns:	This method returns: A cursor for the documents produced by the final stage of the aggregation pipeline. If the pipeline includes the explain option, the query returns a document that provides details on the processing of the aggregation operation. If the pipeline includes the $out or $merge operators, the query returns an empty cursor.

Behavior

Examples

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 }

db.orders.aggregate([
                     { $match: { status: "A" } },
                     { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                     { $sort: { total: -1 } }
                   ])

{ "_id" : "xyz1", "total" : 100 }
{ "_id" : "abc1", "total" : 75 }

db.orders.explain().aggregate([
   { $match: { status: "A" } },
   { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
   { $sort: { total: -1 } }
])

cursor: { batchSize: <int> }

db.orders.aggregate(
                     [
                       { $match: { status: "A" } },
                       { $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
                       { $sort: { total: -1 } },
                       { $limit: 2 }
                     ],
                     {
                       cursor: { batchSize: 0 }
                     }
                   )

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

db.myColl.aggregate(
   [ { $match: { status: "A" } }, { $group: { _id: "$category", count: { $sum: 1 } } } ],
   { collation: { locale: "fr", strength: 1 } }
);

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 }
] )

db.foodColl.createIndex( { qty: 1, type: 1 } );
db.foodColl.createIndex( { qty: 1, category: 1 } );

db.foodColl.aggregate(
   [ { $sort: { qty: 1 }}, { $match: { category: "cake", qty: 10  } }, { $sort: { type: -1 } } ],
   { hint: { qty: 1, category: 1 } }
)

db.restaurants.aggregate(
   [ { $match: { rating: { $lt: 5 } } } ],
   { readConcern: { level: "majority" } }
)

{
  "_id" : ObjectId("599b3b54b8ffff5d1cd323d8"),
  "title" : "Jaws",
  "year" : 1975,
  "imdb" : "tt0073195"
}

db.movies.aggregate( [ { $match: { year : 1995 } } ], { comment : "match_all_movies_from_1995" } ).pretty()

db.system.profile.find( { "command.aggregate": "movies", "command.comment" : "match_all_movies_from_1995" } ).sort( { ts : -1 } ).pretty()

{
  "op" : "command",
  "ns" : "video.movies",
  "command" : {
    "aggregate" : "movies",
    "pipeline" : [
      {
        "$match" : {
          "year" : 1995
        }
      }
    ],
    "comment" : "match_all_movies_from_1995",
    "cursor" : {
    },
    "$db" : "video"
  },
  ...
}

db.cakeSales.insertMany( [
   { _id: 1, flavor: "chocolate", salesTotal: 1580 },
   { _id: 2, flavor: "strawberry", salesTotal: 4350 },
   { _id: 3, flavor: "cherry", salesTotal: 2150 }
] )

db.cakeSales.aggregate(
   [
      { $match: {
         $expr: { $gt: [ "$salesTotal", "$$targetTotal" ] }
      } }
   ],
   { let: { targetTotal: 3000 } }
)