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

# aggregate (database command)

## Definition

Performs an aggregation operation using the [aggregation pipeline](https://www.mongodb.com/docs/manual/core/aggregation-pipeline.md#std-label-aggregation-pipeline). The pipeline lets you process data from a collection or other source through a sequence of stages.

**Tip:**

In [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh), this command can also be run through the [`db.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.aggregate.md#mongodb-method-db.aggregate) and
[`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) helper methods or with the
[`watch()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.watch.md#mongodb-method-db.collection.watch) helper method.

Helper methods are convenient for [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh) users, but they may not return the same level of information as database commands.  In cases where the convenience is not needed or the additional return fields are required, use the database command.

## Compatibility

This command is available in deployments hosted in the following environments:

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

**Important:**

This command has limited support in M0 and Flex clusters. For more information, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

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

**Changed in version 5.0**

The command has the following syntax:

```javascript
db.runCommand(
   {
     aggregate: "<collection>" || 1,
     pipeline: [ <stage>, <...> ],
     explain: <boolean>,
     allowDiskUse: <boolean>,
     allowPartialResults: <boolean>,
     cursor: <document>,
     maxTimeMS: <int>,
     bypassDocumentValidation: <boolean>,
     readConcern: <document>,
     collation: <document>,
     hint: <string or document>,
     comment: <any>,
     writeConcern: <document>,
     let: <document>, // Added in MongoDB 5.0
     querySettings: <document> // Added in MongoDB 9.0
   }
)
```

### Command Fields

The [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command takes the following fields as arguments:

| Field | Type | Description |
| --- | --- | --- |
| `aggregate` | string | The name of the collection or view that acts as the input for the aggregation pipeline. Use `1` for collection agnostic commands. |
| `pipeline` | array | An array of aggregation pipeline stages that process and transform the document stream as part of the aggregation pipeline. |
| `explain` | boolean | Optional. Specifies to return the information on the processing of the pipeline. Not available in [multi-document transactions.](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions) |
| `allowDiskUse` | boolean | Optional. Use this option to override [`allowDiskUseByDefault`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.allowDiskUseByDefault) for a specific query. You can use this option to either: Prohibit disk use on a system where disk use is allowed by default.; Allow disk use on a system where disk use is prohibited by default. Starting in MongoDB 6.0, if [`allowDiskUseByDefault`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.allowDiskUseByDefault) is set to `true` and the server requires more than 100 megabytes of memory for a pipeline execution stage, MongoDB automatically writes temporary files to disk unless the query specifies `{ allowDiskUse: false }`. For details, see [`allowDiskUseByDefault`.](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.allowDiskUseByDefault) 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) |
| `allowPartialResults` | boolean | Optional. For aggregations that run through a [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) against a sharded collection, the command can return partial results instead of an error when one or more queried shards are unavailable. Subsequent [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) commands can also return partial results. Defaults to `false`, which returns an error if a queried shard is unavailable. Set `allowPartialResults` on the initial [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command only. You cannot set it on [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore), but each [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) inherits the setting from the cursor. Since a shard can become unavailable at any point, partial results can appear in the initial [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) response, in a later [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) response, or both. When a batch omits results from unavailable shards, that batch's response includes a `partialResultsReturned: true` field. When all queried shards are available for a batch, the response omits `partialResultsReturned`. `partialResultsReturned` can contain only documents from available shards. Do not assume the result set is complete when `partialResultsReturned` is true. The command returns an `InvalidOptions` error if the pipeline: Ends in a write stage, such as [`$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); Is a [change stream](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) aggregation.; Contains an Atlas Search stage, such as `$search`, `$vectorSearch`, `$rankFusion`, or `$scoreFusion`. |
| `cursor` | document | Specify a document that contains options that control the creation of the cursor object. You must use the [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command with the `cursor` option unless the command includes the `explain` option. To indicate a cursor with the default batch size, specify `cursor: {}`.; To indicate a cursor with a non-default batch size, use `cursor: {
batchSize: <num> }`. |
| `maxTimeMS` | non-negative integer | Optional. Specifies a time limit in milliseconds. 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()`](https://www.mongodb.com/docs/manual/reference/method/db.killop.md#mongodb-method-db.killOp). MongoDB only terminates an operation at one of its designated [interrupt points.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-interrupt-point) |
| `bypassDocumentValidation` | boolean | Optional. Applicable only if you specify 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) aggregation stages. Enables [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) to bypass schema validation during the operation. This lets you insert documents that do not meet the validation requirements. |
| `readConcern` | document | Optional. Specifies the [read concern.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-read-concern) The `readConcern` option has the following syntax: `readConcern: { level: <value> }` Possible read concern levels are: [`"local"`](https://www.mongodb.com/docs/manual/reference/read-concern-local.md#mongodb-readconcern-readconcern.-local-). This is the default read concern level for read operations against the primary and secondaries.; [`"available"`](https://www.mongodb.com/docs/manual/reference/read-concern-available.md#mongodb-readconcern-readconcern.-available-). Available for read operations against the primary and secondaries. [`"available"`](https://www.mongodb.com/docs/manual/reference/read-concern-available.md#mongodb-readconcern-readconcern.-available-) behaves the same as [`"local"`](https://www.mongodb.com/docs/manual/reference/read-concern-local.md#mongodb-readconcern-readconcern.-local-) against the primary and non-sharded secondaries. The query returns the instance's most recent data.; [`"majority"`](https://www.mongodb.com/docs/manual/reference/read-concern-majority.md#mongodb-readconcern-readconcern.-majority-). Available for replica sets that use [WiredTiger storage engine.](https://www.mongodb.com/docs/manual/core/wiredtiger.md#std-label-storage-wiredtiger); [`"linearizable"`](https://www.mongodb.com/docs/manual/reference/read-concern-linearizable.md#mongodb-readconcern-readconcern.-linearizable-). Available for read operations on the [`primary`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.PRIMARY) only.; [`"snapshot"`](https://www.mongodb.com/docs/manual/reference/read-concern-snapshot.md#mongodb-readconcern-readconcern.-snapshot-). Available for [multi-document transactions](https://www.mongodb.com/docs/manual/core/transactions.md#std-label-transactions) and certain read operations outside of multi-document transactions. For more formation on the read concern levels, see [Read Concern Levels.](https://www.mongodb.com/docs/manual/reference/read-concern.md#std-label-read-concern-levels) The [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) stage cannot be used in conjunction with read concern [`"linearizable"`](https://www.mongodb.com/docs/manual/reference/read-concern-linearizable.md#mongodb-readconcern-readconcern.-linearizable-). If you specify [`"linearizable"`](https://www.mongodb.com/docs/manual/reference/read-concern-linearizable.md#mongodb-readconcern-readconcern.-linearizable-) read concern for [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate), you cannot include the [`$out`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/out.md#mongodb-pipeline-pipe.-out) stage in the pipeline. The [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) stage cannot be used in conjunction with read concern [`"linearizable"`](https://www.mongodb.com/docs/manual/reference/read-concern-linearizable.md#mongodb-readconcern-readconcern.-linearizable-). That is, if you specify [`"linearizable"`](https://www.mongodb.com/docs/manual/reference/read-concern-linearizable.md#mongodb-readconcern-readconcern.-linearizable-) read concern for [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate), you cannot include the [`$merge`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge.md#mongodb-pipeline-pipe.-merge) stage in the pipeline. |
| `collation` | document | Optional. Optional. Specifies the [collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation)  to use for the operation. [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 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.](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation-document-fields) If the collation is unspecified but the collection has a default collation (see [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createcollection.md#mongodb-method-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 or view against which the aggregation is run. Specify the index either by the index name or by the index specification document. The `hint` does not apply to [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup) and [`$graphLookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphlookup.md#mongodb-pipeline-pipe.-graphLookup) stages. |
| `comment` | any | Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: [mongod log messages](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-messages-ref), in the `attr.command.cursor.comment` field.; [Database profiler](https://www.mongodb.com/docs/manual/reference/database-profiler.md#std-label-profiler) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/database-profiler.md#mongodb-data-system.profile.command) field.; [`currentOp`](https://www.mongodb.com/docs/manual/reference/command/currentop.md#mongodb-dbcommand-dbcmd.currentOp) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/command/currentop.md#mongodb-data-currentOp.command) field. A comment can be any valid [BSON type](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types) (string, integer, object, array, etc). Any comment set on a `aggregate` command is inherited by any subsequent [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getmore.md#mongodb-dbcommand-dbcmd.getMore) commands run on the `aggregate` cursor. |
| `writeConcern` | document | Optional. A document that expresses the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-write-concern) to use with 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) stage. Omit to use the default write concern with 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) 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`. To use a variable to filter results 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. For a complete example using `let` and variables, see [Use Variables in `let`.](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#std-label-aggregate-let-example) **New in version 5.0** |
| `querySettings` | document | Optional. Query settings that apply only to this execution of the command. The `querySettings` document accepts the following fields: `indexHints`; `queryFramework`; `reject`; `comment`; `queryKnobs`; `maxTimeMS` For descriptions of these fields, see [Command Fields.](https://www.mongodb.com/docs/manual/reference/command/setquerysettings.md#std-label-setQuerySettings-fields) MongoDB doesn't store these settings on the cluster, and they don't apply to other queries with the same [query shape](https://www.mongodb.com/docs/manual/core/query-shapes.md#std-label-query-shapes). To set query settings that persist for a query shape, use [`setQuerySettings`.](https://www.mongodb.com/docs/manual/reference/command/setquerysettings.md#mongodb-dbcommand-dbcmd.setQuerySettings) MongoDB combines the settings that you pass in the command with any query settings stored on the cluster for the same query shape. If both settings specify the same field, the stored cluster setting takes precedence. **New in version 9.0** |

You must use the [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command with the `cursor` option unless the command includes the `explain` option.

- To indicate a cursor with the default batch size, specify `cursor: {}`.

- To indicate a cursor with a non-default batch size, use `cursor: {
  batchSize: <num> }`.

For more information about the aggregation pipeline, 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)

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

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). 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`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.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)

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

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

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

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

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`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.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`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) disconnects before the operation completes, MongoDB marks [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.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.

## Stable API

When using [Stable API](https://www.mongodb.com/docs/manual/reference/stable-api.md#std-label-stable-api) V1, the [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command is supported with the following exceptions:

- The following aggregation stages are not available in Stable API V1:

  - [`$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)

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

  - [`$search`](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search)

- The `explain` field is not available in Stable API V1. If you include it, the server returns an [APIStrictError](https://www.mongodb.com/docs/manual/reference/stable-api.md#std-label-api-strict-resp) error.

- When using the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#mongodb-pipeline-pipe.-collStats) stage, only the `count` field is available. All other [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#mongodb-pipeline-pipe.-collStats) fields are not available in Stable API V1.

## Example

You must use the [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command with the `cursor` option unless the command includes the `explain` option.

- To indicate a cursor with the default batch size, specify `cursor: {}`.

- To indicate a cursor with a non-default batch size, use `cursor: {
  batchSize: <num> }`.

Instead of running the [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command directly, use the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) helper in [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) or the equal helper in your driver.

Except for the first two examples that demonstrate the command syntax, the examples on this page use the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) helper.

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.

### Aggregate Data with Multi-Stage Pipeline

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

**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' ],
}
```

The following example aggregates the `movies` collection to calculate the count of each distinct genre:

```javascript
db.runCommand( {
    aggregate: "movies", 
    pipeline: [
       { $project: { genres: 1 } },
       { $unwind: "$genres" },
       { $group: { _id: "$genres", count: { $sum : 1 } } }
    ],
    cursor: { }
} )

```

In [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh), run the same aggregation using the [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate) helper:

```javascript
db.movies.aggregate( 
    [
       { $project: { genres: 1 } },
       { $unwind: "$genres" },
       { $group: { _id: "$genres", count: { $sum: 1 } } }
    ]
)

```

### Use $currentOp on an Admin Database

The following example runs a two-stage pipeline on the admin database. The first stage executes the [`$currentOp`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/currentop.md#mongodb-pipeline-pipe.-currentOp) operation, and the second stage filters the results.

```javascript
db.adminCommand( { 
    aggregate : 1, 
    pipeline : [ { 
       $currentOp : { allUsers : true, idleConnections : true } }, { 
       $match : { shard : "shard01" } 
       } 
    ], 
    cursor : { } 
})

```

**Note:**

The [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) command does not specify a collection and instead takes the form `{aggregate: 1}`. The initial [`$currentOp`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/currentop.md#mongodb-pipeline-pipe.-currentOp) stage does not draw input from a collection. The stage produces its own data for the rest of the pipeline to use.

The [`db.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.aggregate.md#mongodb-method-db.aggregate) helper supports collectionless aggregations such as this. Run the above aggregation like [this](https://www.mongodb.com/docs/manual/reference/method/db.aggregate.md#std-label-admin-pipeline-currentOp) example.

### Return Information on the Aggregation Operation

The following example sets `explain` to `true` to return information about the aggregation.

```javascript
db.comments.aggregate(
     [
        { $match: { date: { $gte: ISODate("2015-01-01") } } },
        { $group: { _id: "$movie_id", commentCount: { $sum: 1 } } },
        { $sort: { commentCount: -1 } }
     ],
     { explain: true }
)

```

**Note: The explain output is subject to change between releases.**

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

### Aggregate Data Specifying Batch Size

To set an *initial* batch size, include the `batchSize` in the `cursor` field:

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

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

```

For descriptions of 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 Default Read Concern

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.

### 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 `movies` collection in the `sample_mflix` database contains documents like this one:

```javascript
{
   title: "The Shawshank Redemption",
   year: 1994,
   rated: "R",
   imdb: { rating: 9.3, votes: 1513145, id: 111161 },
   runtime: 142
}
```

The following example uses the `let` option to define variables for the pipeline. The example finds movies with high ratings and long runtimes:

```javascript
db.runCommand( {
    aggregate: "movies",
    pipeline: [
       { $match: {
            $expr: { 
               $and: [
                  { $gte: [ "$imdb.rating", "$$minRating" ] },
                  { $gte: [ "$runtime", "$$minRuntime" ] }
               ]
            }
       } },
       { $project: { 
            title: 1, 
            year: 1, 
            "imdb.rating": 1, 
            runtime: 1 
       } },
       { $sort: { "imdb.rating": -1 } },
       { $limit: 3 }
     ],
     cursor: {},
     let: { minRating: 8.5, minRuntime: 120 }
} )

```

## Learn More

- [`db.collection.aggregate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.aggregate.md#mongodb-method-db.collection.aggregate)

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