- Reference >
- Operators >
- Aggregation Pipeline Stages >
- $out (aggregation)
$out (aggregation)¶
On this page
Definition¶
-
$out
¶ Takes the documents returned by the aggregation pipeline and writes them to a specified collection. The
$out
operator must be the last stage in the pipeline. The$out
operator lets the aggregation pipeline return result sets of any size.Changed in version 3.2.0.
The
$out
stage has the following prototype form:$out
takes a string that specifies the output collection name.Important
- You cannot specify a sharded collection as the output
collection. The input collection for a pipeline can be sharded.
To output to a sharded collection, see
$merge
(Available starting in MongoDB 4.2). - The
$out
operator cannot write results to a capped collection.
- You cannot specify a sharded collection as the output
collection. The input collection for a pipeline can be sharded.
To output to a sharded collection, see
Comparison with $merge
¶
With the introduction of $merge
in version 4.2, MongoDB
provides two stages, $merge
and $out
, for
writing the results of the aggregation pipeline to a collection. The
following summarizes the capabilities of the two stages:
$out |
$merge |
---|---|
|
|
|
|
|
|
|
|
|
|
Behaviors¶
Create New Collection¶
The $out
operation creates a new collection in the current
database if one does not already exist. The collection is not visible
until the aggregation completes. If the aggregation fails, MongoDB does
not create the collection.
Replace Existing Collection¶
If the collection specified by the $out
operation already
exists, then upon completion of the aggregation, the $out
stage atomically replaces the existing collection with the new results
collection. Specifically, the $out
operation:
- Creates a temp collection.
- Copies the indexes from the existing collection to the temp collection.
- Inserts the documents into the temp collection.
- Calls
db.collection.renameCollection
withdropTarget: true
to rename the temp collection to the destination collection.
The $out
operation does not change any indexes that existed on the
previous collection. If the aggregation fails, the $out
operation
makes no changes to the pre-existing collection.
Index Constraints¶
The pipeline will fail to complete if the documents produced by the
pipeline would violate any unique indexes, including the index on the
_id
field of the original output collection.
If the $out
operation modifies a collection with an
Atlas Search index, you must delete and
re-create the search index. Consider using $merge
instead.
Transactions¶
$out
is not allowed in transactions.
Views¶
New in version 4.2.
The $out
stage is not allowed as part of a view
definition. If the view definition includes nested
pipeline (e.g. the view definition includes $lookup
or
$facet
stage), this $out
stage restriction
applies to the nested pipelines as well. [1]
[1] | Starting in 4.2, you cannot include the $out stage in
the $lookup stage’s nested pipeline, regardless of whether the
$lookup is part of a view definition. |
linearizable
Read Concern¶
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.
majority
Read Concern¶
Starting in MongoDB 4.2, you can specify read concern level "majority"
for an
aggregation that includes an $out
stage.
Interaction with mongodump
¶
A mongodump
started with
--oplog
fails if a client issues an
aggregation pipeline that includes $out
during the
dump process. See mongodump --oplog
for more information.
Example¶
A collection books
contains the following documents:
The following aggregation operation pivots the data in the books
collection to have titles grouped by authors and then writes
the results to the authors
collection.
After the operation, the authors
collection contains the following
documents: