db.collection.aggregate() (mongosh method)

Parameters

The aggregate() method takes the following parameters:

Error Handling

If an error occurs, the aggregate() helper throws an exception.

Cursor Behavior

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:

For more information, see:

• Aggregation Pipeline

• Aggregation Reference

• Aggregation Pipeline Limits

• aggregate

Sessions

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.

Transactions

db.collection.aggregate() can be used inside distributed transactions.

However, the following stages are not allowed within transactions:

• $collStats

• $currentOp

• $indexStats

• $listLocalSessions

• $listSessions

• $out

• $merge

• $planCacheStats

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.

Client Disconnection

For db.collection.aggregate() operation that do not include the $out or $merge stages:

If the client that issued db.collection.aggregate() disconnects before the operation completes, MongoDB marks db.collection.aggregate() for termination using killOp.

Query Settings

You can use query settings to set index hints, set operation rejection filters, and other fields. The settings apply to the query shape on the entire cluster. The cluster retains the settings after shutdown.

The query optimizer uses the query settings as an additional input during query planning, which affects the plan selected to run the query. You can also use query settings to block a query shape.

To add query settings and explore examples, see setQuerySettings.

You can add query settings for find, distinct, and aggregate commands.

Query settings have more functionality and are preferred over deprecated index filters.

To remove query settings, use removeQuerySettings. To obtain the query settings, use a $querySettings stage in an aggregation pipeline.

Group by and Calculate a Sum

The following aggregation operation:

• Selects movies with an IMDB rating greater than 8.5

• Groups the matching movies by the year field

• Calculates the averageRating for each year from the average of the imdb.rating field

• Sorts the results by the averageRating field in descending order

db.movies.aggregate(
    [
       { $match: { "imdb.rating": { $gt: 8.5 } } },
       { $group: { _id: "$year", averageRating: { $avg: "$imdb.rating" } } },
       { $sort: { averageRating: -1 } },
       { $limit: 3 }
    ] 
)

The operation returns a cursor with the following documents:

[
  { _id: 1972, averageRating: 9.2 },
  { _id: 1990, averageRating: 9.166666666666666 },
  { _id: 1974, averageRating: 9.1 }
]

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

The following example uses db.collection.explain() to view detailed information regarding the execution plan of the aggregation pipeline.

db.movies.explain().aggregate( 
    [
       { $match: { "imdb.rating": { $gt: 8.5 } } },
       { $group: { _id: "$year", averageRating: { $avg: "$imdb.rating" } } },
       { $sort: { averageRating: -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 movies collection is a sharded collection, the document also shows the division of labor between the shards and the merge operation, and for targeted queries, the targeted shards.

You can view more verbose explain output by passing the executionStats or allPlansExecution explain modes to the db.collection.explain() method.

Interaction with allowDiskUseByDefault

Pipeline stages that require more than 100 megabytes of memory to execute write temporary files to disk by default. These temporary files last for the duration of the pipeline execution and can influence storage space on your instance.

Individual find and aggregate commands can override the allowDiskUseByDefault parameter by either:

• Using { allowDiskUse: true } to allow writing temporary files out to disk when allowDiskUseByDefault is set to false

• Using { allowDiskUse: false } to prohibit writing temporary files out to disk when allowDiskUseByDefault is set to true

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.

For more information, see Aggregation Pipeline Limits.

Specify an Initial Batch Size

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.theaters.aggregate( 
    [
       { $match: { "location.address.state": "NY" } },
       { $group: { _id: "$location.address.city", theaterCount: { $sum: 1 } } },
       { $sort: { theaterCount: -1 } },
       { $limit: 2 }
    ],
    { cursor: { batchSize: 0 } }
)

The { cursor: { batchSize: 0 } } document, which specifies the size of the initial batch size, indicates an empty first batch. This batch size is useful for quickly returning a cursor or failure message without doing significant server-side work.

To specify batch size for subsequent getMore operations (after the initial batch), use the batchSize field when running the getMore command.

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

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

The following aggregation operation returns titles of all French movies in the movies collection of the sample_mflix database and specifies the fr collation:

db.movies.aggregate(
    [ 
       { $match: {"countries": "France", "languages": "French"} }, 
       { $project: { "title": 1, "_id": 0 } }
    ],
    { collation: { locale: "fr", strength: 1 } }
)

For descriptions on the collation fields, see Collation Document.

Hint an Index

The movies collection in the sample_mflix database contains documents similar to these:

{
   title: "The Shawshank Redemption",
   year: 1994, rated: "R",
   imdb: { rating: 9.3, votes: 1513145, id: 111161 }
},
{
   title: "The Godfather",
   year: 1972,
   rated: "R",
   imdb: { rating: 9.2, votes: 1038358, id: 68646 }
},
{
   title: "The Dark Knight",
   year: 2008, rated: "PG-13",
   imdb: { rating: 9, votes: 1495351, id: 468569 }
},
{
   title: "Forrest Gump",
   year: 1994,
   rated: "PG-13",
   imdb: { rating: 8.8, votes: 1087227, id: 109830 }
}

Assume the following indexes exist on the movies collection:

db.movies.createIndex( { "imdb.rating": 1, year: 1 } )

db.movies.createIndex( { "imdb.rating": 1, rated: 1 } )

The following aggregation operation includes the hint option to force the usage of the specified index:

db.movies.aggregate(
    [
        { $sort: { "imdb.rating": 1 } },
        { $match: { rated: "R", "imdb.rating": { $gte: 9.0 } } },
        { $sort: { year: -1 } } 
    ],
    { hint: { "imdb.rating": 1, rated: 1 } }
)

Override readConcern

To override the default read concern level, use the readConcern option. The getMore command uses the readConcern level specified in the originating aggregate command.

The following operation on the movies collection from the sample_mflix database 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.

db.movies.aggregate(
    [ 
       { $match: { "imdb.rating": { $gte: 8.0 } } },
       { $group: { _id: "$rated", avgRating: { $avg: "$imdb.rating" }, count: { $sum: 1 } } },
       { $sort: { avgRating: -1 } }
    ],
    { readConcern: { level: "majority" } }
)

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.

Specify a Comment

The movies collection in the sample_mflix sample dataset contains documents similar to this one:

{
   title: 'Forrest Gump',
   year: 1994,
   genres: [ 'Drama', 'Romance' ],
   runtime: 142,
   imdb: { rating: 8.8, votes: 1087227, id: 109830 },
   directors: [ 'Robert Zemeckis' ],
   cast: [ 'Tom Hanks', 'Rebecca Williams', 'Sally Field', 'Michael Conner Humphreys' ],
}

The following aggregation operation finds movies created in 1994 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 : 1994 } },
        { $limit: 3 }
    ], 
    { comment: "match_three_movies_from_1994" } 
)

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_three_movies_from_1994" } ).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" : 1994
        }
      },
      { "$limit": 3 }
    ],
    "comment" : "match_three_movies_from_1994",
    "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

To define variables that you can access elsewhere in the command, use the let option.

The following example:

• Matches documents from the sample_mflix.movies collection where the imdb.rating field is greater than 8.5, limited to three results

• Defines a minRating variable in let, which is referenced in $gt as $$minRating

db.movies.aggregate(
    [
       { $match: {
          $expr: { $gt: [ "$imdb.rating", "$$minRating" ] }
       } },
       { $limit: 3 }
    ],
    { let: { minRating: 8.5 } }
)