> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# db.collection.aggregate() (mongosh method)

## Definition

Calculates aggregate values for the data in a collection or a [view.](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page)

- A [cursor](https://www.mongodb.com/docs/manual/core/cursors.md#std-label-cursors) 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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) or [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) operators, the query returns an empty cursor.

## Compatibility

You can use `db.collection.aggregate()` for deployments hosted in the following environments:

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

* [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

* [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Syntax

`db.collection.aggregate()` has the following form:

```javascript
db.collection.aggregate( <pipeline>, <options> )
```

### Parameters

`db.collection.aggregate()` takes the following parameters:

| Parameter | Type | Description |
| --- | --- | --- |
| `pipeline` | array | A sequence of data aggregation operations or stages. See the [aggregation pipeline operators](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline) 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`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command. Available only if you specify the `pipeline` as an array. To see available options, see [AggregateOptions.](https://mongodb.github.io/node-mongodb-native/Next/interfaces/AggregateOptions.html) |

## Behavior

### Error Handling

If an error occurs, the [`aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) helper throws an exception.

### Cursor Behavior

In [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh), if the `aggregate()` cursor is not assigned to a variable using the `var` keyword, [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) automatically iterates the cursor up to 20 times. See [Iterate a Cursor in mongosh](https://www.mongodb.com/docs/manual/tutorial/iterate-a-cursor.md) for handling cursors in [`mongosh`.](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.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:

- [`cursor.hasNext()`](https://www.mongodb.com/docs/manual/reference/method/cursor.hasnext.md#mongodb-method-cursor.hasNext)

- [`cursor.next()`](https://www.mongodb.com/docs/manual/reference/method/cursor.next.md#mongodb-method-cursor.next)

- [`cursor.toArray()`](https://www.mongodb.com/docs/manual/reference/method/cursor.toarray.md#mongodb-method-cursor.toArray)

- [`cursor.forEach()`](https://www.mongodb.com/docs/manual/reference/method/cursor.foreach.md#mongodb-method-cursor.forEach)

- [`cursor.map()`](https://www.mongodb.com/docs/manual/reference/method/cursor.map.md#mongodb-method-cursor.map)

- [`cursor.objsLeftInBatch()`](https://www.mongodb.com/docs/manual/reference/method/cursor.objsleftinbatch.md#mongodb-method-cursor.objsLeftInBatch)

- [`cursor.itcount()`](https://www.mongodb.com/docs/manual/reference/method/cursor.itcount.md#mongodb-method-cursor.itcount)

- [`cursor.pretty()`](https://www.mongodb.com/docs/manual/reference/method/cursor.pretty.md#mongodb-method-cursor.pretty)

For more information, see:

- [Aggregation Pipeline](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline)

- [Aggregation Reference](https://www.mongodb.com/docs/manual/reference/aggregation.md)

- [Aggregation Pipeline Limits](https://www.mongodb.com/docs/manual/core/aggregation-pipeline-limits.md)

- [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate)

### Sessions

For cursors created inside a session, you cannot call [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) outside the session.

Similarly, for cursors created outside of a session, you cannot call [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) inside a session.

#### Session Idle Timeout

MongoDB drivers and [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) associate all operations with a [server session](https://www.mongodb.com/docs/manual/reference/server-sessions.md), with the exception of unacknowledged write operations. For operations not explicitly associated with a session (i.e. using [`Mongo.startSession()`](https://www.mongodb.com/docs/manual/reference/method/mongo.startsession.md#mongodb-method-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()`](https://www.mongodb.com/docs/manual/reference/method/cursor.nocursortimeout.md#mongodb-method-cursor.noCursorTimeout) or a [`maxTimeMS()`](https://www.mongodb.com/docs/manual/reference/method/cursor.maxtimems.md#mongodb-method-cursor.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()`](https://www.mongodb.com/docs/manual/reference/method/mongo.startsession.md#mongodb-method-Mongo.startSession) and periodically refresh the session using the [`refreshSessions`](https://www.mongodb.com/docs/manual/reference/command/refreshsessions.md#mongodb-dbcommand-dbcmd.refreshSessions) command. See [Session Idle Timeout](https://www.mongodb.com/docs/manual/reference/limits.md#mongodb-limit-Session-Idle-Timeout) for more information.

### Transactions

`aggregate()` can be used inside [distributed transactions.](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions)

However, the following stages are not allowed within transactions:

- [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#mongodb-pipeline-pipe.-collStats)

- [`$currentOp`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/currentop.md#mongodb-pipeline-pipe.-currentOp)

- [`$indexStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#mongodb-pipeline-pipe.-indexStats)

- [`$listLocalSessions`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listlocalsessions.md#mongodb-pipeline-pipe.-listLocalSessions)

- [`$listSessions`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listsessions.md#mongodb-pipeline-pipe.-listSessions)

- [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out)

- [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge)

- [`$planCacheStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/plancachestats.md#mongodb-pipeline-pipe.-planCacheStats)

You also cannot specify the `explain` option.

- For cursors created outside of a transaction, you cannot call [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) inside the transaction.

- For cursors created in a transaction, you cannot call [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) outside the transaction.

**Important:**

In most cases, a distributed transaction incurs a greater performance cost over single document writes, and the availability of distributed transactions should not be a replacement for effective schema design. For many scenarios, the [denormalized data model (embedded documents and arrays)](https://www.mongodb.com/docs/manual/data-modeling/embedding.md#std-label-data-modeling-embedding) 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 distributed transactions.

For additional transactions usage considerations (such as runtime limit and oplog size limit), see also [Production Considerations.](https://www.mongodb.com/docs/manual/core/transactions-production-consideration.md#std-label-production-considerations)

### Client Disconnection

For `aggregate()` operations that do not include the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) or [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) stages:

If the client that issued `aggregate()` disconnects before the operation completes, MongoDB marks `aggregate()` for termination using [`killOp`.](https://www.mongodb.com/docs/manual/reference/command/killop.md#mongodb-dbcommand-dbcmd.killOp)

### Query Settings

**New in version 8.0**

You can use query settings to set index hints, set [operation rejection filters](https://www.mongodb.com/docs/manual/tutorial/operation-rejection-filters.md#std-label-operation-rejection-filters), and other fields. The settings apply to the [query shape](https://www.mongodb.com/docs/manual/reference/operator/aggregation/querystats.md#std-label-queryStats-queryShape) on the entire cluster. The cluster retains the settings after shutdown.

The [query optimizer](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-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`.](https://www.mongodb.com/docs/manual/reference/command/setquerysettings.md#mongodb-dbcommand-dbcmd.setQuerySettings)

You can add query settings for [`find`](https://www.mongodb.com/docs/manual/reference/command/find.md#mongodb-dbcommand-dbcmd.find), [`distinct`](https://www.mongodb.com/docs/manual/reference/command/distinct.md#mongodb-dbcommand-dbcmd.distinct), and [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) commands.

Query settings have more functionality and are preferred over deprecated [index filters.](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-index-filters)

To remove query settings, use [`removeQuerySettings`](https://www.mongodb.com/docs/manual/reference/command/removequerysettings.md#mongodb-dbcommand-dbcmd.removeQuerySettings). To obtain the query settings, use a [`$querySettings`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/querysettings.md#mongodb-pipeline-pipe.-querySettings) stage in an aggregation pipeline.

## Examples

The examples on this page use data from the [sample\_mflix dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix). For details on how to load this dataset into your self-managed MongoDB deployment, see [Load the Sample Dataset](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local). If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

**Note:**

Documents in the `movies` collection contain additional fields not shown here.

```javascript
{
   title: 'The Shawshank Redemption',
   year: 1994,
   genres: [ 'Crime', 'Drama' ],
   runtime: 142,
   imdb: { rating: 9.3, votes: 1521105, id: 111161 },
   directors: [ 'Frank Darabont' ],
   cast: [ 'Tim Robbins', 'Morgan Freeman', 'Bob Gunton', 'William Sadler' ],
},
{
   title: 'The Godfather',
   year: 1972,
   genres: [ 'Crime', 'Drama' ],
   runtime: 175,
   imdb: { rating: 9.2, votes: 1038358, id: 68646 },
   directors: [ 'Francis Ford Coppola' ],
   cast: [ 'Marlon Brando', 'Al Pacino', 'James Caan', 'Richard S. Castellano' ]
},
{
   title: 'Pulp Fiction',
   year: 1994,
   genres: [ 'Crime', 'Drama' ],
   runtime: 154,
   imdb: { rating: 8.9, votes: 1179033, id: 110912 },
   directors: [ 'Quentin Tarantino' ],
   cast: [ 'Tim Roth', 'Amanda Plummer', 'Laura Lovelace', 'John Travolta' ]
},
{
   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' ],
},
{
   title: 'Inception',
   year: 2010,
   genres: [ 'Action', 'Sci-Fi', 'Thriller' ],
   runtime: 148,
   imdb: { rating: 8.8, votes: 1294646, id: 1375666 },
   directors: [ 'Christopher Nolan' ],
   cast: [ 'Leonardo DiCaprio', 'Joseph Gordon-Levitt', 'Ellen Page', 'Tom Hardy' ],
}
```

### 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

```javascript
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:

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

[`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) iterates the returned cursor automatically to print the results. See [Iterate a Cursor in mongosh](https://www.mongodb.com/docs/manual/tutorial/iterate-a-cursor.md) for handling cursors manually in [`mongosh`.](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)

### Return Information on Aggregation Pipeline Operation

The following example uses [`db.collection.explain()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) to view detailed information regarding the execution plan of the aggregation pipeline.

```javascript
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.  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.

**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()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.explain.md#mongodb-method-db.collection.explain) method.

[Index Filters](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-index-filters) can affect the choice of index used. See [Index Filters](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-index-filters) for details.

### 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`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.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](https://www.mongodb.com/docs/manual/tutorial/manage-the-database-profiler.md#std-label-database-profiler) and [diagnostic log messages](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-messages-ref) includes a `usedDisk` indicator if any aggregation stage wrote data to temporary files due to [memory restrictions.](https://www.mongodb.com/docs/manual/core/aggregation-pipeline-limits.md#std-label-agg-memory-restrictions)

For more information, see [Aggregation Pipeline Limits.](https://www.mongodb.com/docs/manual/core/aggregation-pipeline-limits.md#std-label-agg-pipeline-limits)

### Specify an Initial Batch Size

To specify an initial batch size for the cursor, use the following syntax for the `cursor` option:

```javascript
cursor: { batchSize: <int> }
```

For example, the following aggregation operation specifies the *initial* batch size of `0` for the cursor:

```javascript
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 specifies the size of the *initial* batch size and indicates an empty first batch. This quickly returns a cursor or failure message without doing significant server-side work.

To specify batch size for subsequent [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) operations, use [`batchSize()`](https://www.mongodb.com/docs/manual/reference/method/cursor.batchsize.md#mongodb-method-cursor.batchSize) in mongosh or the `batchSize` field in the [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) command.

[`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) iterates the returned cursor automatically to print the results. See [Iterate a Cursor in mongosh](https://www.mongodb.com/docs/manual/tutorial/iterate-a-cursor.md) for handling cursors manually in [`mongosh`.](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)

### Specify a Collation

[Collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-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:

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

```

**Note:**

If performing an aggregation that involves multiple views, such as with [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup) or [`$graphLookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphlookup.md#mongodb-pipeline-pipe.-graphLookup), the views must have the same [collation.](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation)

For descriptions on the collation fields, see [Collation Document.](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation-document-fields)

### Hint an Index

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

```javascript
{
   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:

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

```

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

```

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

```javascript
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`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) command uses the `readConcern` level specified in the originating [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command.

The following operation on the `movies` collection from the `sample_mflix` database specifies a [read concern](https://www.mongodb.com/docs/manual/reference/read-concern.md#std-label-read-concern) of [`"majority"`](https://www.mongodb.com/docs/manual/reference/read-concern-majority.md#mongodb-readconcern-readconcern.-majority-) to read the most recent copy of the data confirmed as having been written to a majority of the nodes.

**Important:**

- You can specify [read concern](https://www.mongodb.com/docs/manual/reference/read-concern.md#std-label-read-concern) level [`"majority"`](https://www.mongodb.com/docs/manual/reference/read-concern-majority.md#mongodb-readconcern-readconcern.-majority-) for an aggregation that includes an [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) stage.

- Regardless of the [read concern](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-read-concern) level, the most recent data on a node may not reflect the most recent version of the data in the system.

```javascript
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"`](https://www.mongodb.com/docs/manual/reference/read-concern-majority.md#mongodb-readconcern-readconcern.-majority-) read concern and [`"majority"`](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-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:

```javascript
{
   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`.

```javascript
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:

```javascript
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:

```javascript
{
  "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.

**Note:**

To filter results using a variable in a pipeline [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) stage, you must access the variable within the [`$expr`](https://www.mongodb.com/docs/manual/reference/operator/query/expr.md#mongodb-query-op.-expr) operator.

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`

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

```