Pipeline Stages Reference

Parent: MongoDB Aggregation Pipeline · Published reference · snapshot 2026-10-15

Depth-first rabbithole dossier for Pipeline Stages Reference; source-anchored research pack.

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

Definitions

[low] The $queryStats aggregation stage is unsupported and is not guaranteed to be stable in a future release. Sources: https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md [source]

Structure and components

[low] The $group stage supports certain expressions allowing users to perform arithmetic, array, boolean, and other operations as part of the aggregation pipeline. Sources: https://studio3t.com/knowledge-base/articles/mongodb-aggregation-framework/ [source]

How it works

[low] When using Stable API V1, only the count field is available in the $collStats stage; all other $collStats fields are not available. (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/manual/reference/command/aggregate.md [source]
[low] The explain field is not available in Stable API V1, and including it causes the server to return an APIStrictError. (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/manual/reference/command/aggregate.md [source]
[low] When the MongoDB server closes a session, it also kills any in-progress operations and open cursors associated with that session. Sources: https://www.mongodb.com/docs/manual/reference/command/aggregate.md [source]

Measurements and reference values

[low] The $changeStreamSplitLargeEvent stage splits large change stream events that exceed 16 MB into smaller fragments returned in a change stream cursor. Sources: https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md [source]

Problems, failure modes and limitations

Fact 1 states MongoDB limits the number of aggregation pipeline stages to 1000, while Fact 44 states there is no limit to the number of stages used in the query. Sources: https://www.mongodb.com/docs/manual/core/aggregation-pipeline-limits.md, https://studio3t.com/knowledge-base/articles/mongodb-aggregation-framework/ [source]
[low] There is no limit to the number of stages used in the query, or how they are combined. Sources: https://studio3t.com/knowledge-base/articles/mongodb-aggregation-framework/ [source]
[low] You cannot use the $graphLookup stage within a transaction while targeting a sharded collection. Sources: https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup.md [source]

Facts and statements

[low] All stages except $out, $merge, $geoNear, $changeStream, and $changeStreamSplitLargeEvent can appear multiple times in a pipeline; $out and $merge must also be the last stage. Sources: https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md [source]
[low] MongoDB limits the number of aggregation pipeline stages allowed in a single pipeline to 1000. Sources: https://www.mongodb.com/docs/manual/core/aggregation-pipeline-limits.md [source]
[low] The $changeStream stage can only occur once in an aggregation pipeline and it must occur as the first stage. Sources: https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md [source]
[low] You can only use $changeStreamSplitLargeEvent in a $changeStream pipeline and it must be the final stage in the pipeline. Sources: https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md [source]
[low] The $count stage provides an easy way to check the number of documents obtained in the output of the previous stages of the pipeline. Sources: https://studio3t.com/knowledge-base/articles/mongodb-aggregation-framework/ [source]
[low] You must use the aggregate command with the cursor option unless the command includes the explain option. Sources: https://www.mongodb.com/docs/manual/reference/command/aggregate.md [source]
[low] To indicate a cursor with the default batch size, specify cursor: {}, while a non-default batch size uses cursor: { batchSize: <num> }. Sources: https://www.mongodb.com/docs/manual/reference/command/aggregate.md [source]
[low] The { cursor: { batchSize: 0 } } document specifies the size of the initial batch size and indicates an empty first batch. Sources: https://www.mongodb.com/docs/manual/reference/command/aggregate.md [source]
[low] 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. Sources: https://www.mongodb.com/docs/manual/reference/command/aggregate.md [source]
[low] The querySettings document accepts the following fields: indexHints, queryFramework, reject, comment, queryKnobs, and maxTimeMS. (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/manual/reference/command/aggregate.md [source]
[low] The $vectorSearch stage is only available for MongoDB Atlas clusters running MongoDB v6.0.11 or higher, and is not available for self-managed deployments. (verified as of 2026-10-15) Sources: https://www.mongodb.com/docs/manual/reference/mql/aggregation-stages.md [source]
[low] The $graphLookup stage performs a recursive search on a collection, with options for restricting the search by recursion depth and query filter. Sources: https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup.md [source]
[low] Setting the maxDepth field to 0 in $graphLookup is equivalent to a non-recursive $graphLookup search stage. Sources: https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup.md [source]
[low] The $graphLookup stage does not return sorted results. Sources: https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup.md [source]
[low] As of Version 3.4, MongoDB supports faceted classification by using the Aggregation Framework. (verified as of 2026-10-15) Sources: https://docs.spring.io/spring-data/mongodb/reference/mongodb/aggregation-framework.html [source]
[low] A sort by count operation is equivalent to the BSON: { $group: { _id: <expression>, count: { $sum: 1 } } }, { $sort: { count: -1 } }. Sources: https://docs.spring.io/spring-data/mongodb/reference/mongodb/aggregation-framework.html [source]
[low] As of MongoDB 3.6, it is possible to exclude fields from the projection by using a conditional expression. (verified as of 2026-10-15) Sources: https://docs.spring.io/spring-data/mongodb/reference/mongodb/aggregation-framework.html [source]
[low] The same behavior occurs with all grouping stages, specifically $bucket, $bucketAuto, $count, and $sortByCount. Sources: https://www.practical-mongodb-aggregations.com/guides/sharding.html [source]
[low] The $out stage must be the last stage in the pipeline. Sources: https://studio3t.com/knowledge-base/articles/mongodb-aggregation-framework/ [source]

Related concepts

Reference — is a part of Pipeline Stages Reference
Pipeline — is a part of Pipeline Stages Reference
Stages — is a part of Pipeline Stages Reference

Children

No children recorded.

← the whole tree · 3D view· how to read this page