$out (aggregation)

New in version 2.6.

Definition

• $out
• Takes the documents returned by the aggregation pipeline and writesthem to a specified collection. The $out operator mustbe the last stage in the pipeline. The $out operatorlets the aggregation framework return result sets of any size.

Changed in version 3.2.0.

The $out stage has the following prototype form:

{ $out: "<output-collection>" }

$out takes a string that specifies the output collectionname.

Important

• You cannot specify a sharded collection as the outputcollection. 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 acapped collection.

Comparison with $merge

Behaviors

Create New Collection

The $out operation creates a new collection in the currentdatabase if one does not already exist. The collection is not visibleuntil the aggregation completes. If the aggregation fails, MongoDB doesnot create the collection.

Replace Existing Collection

If the collection specified by the $out operation alreadyexists, then upon completion of the aggregation, the $outstage atomically replaces the existing collection with the new resultscollection. 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 with dropTarget: trueto rename the temp collection to the destination collection.The $out operation does not change any indexes that existed on theprevious collection. If the aggregation fails, the $out operationmakes no changes to the pre-existing collection.

Index Constraints

The pipeline will fail to complete if the documents produced by thepipeline would violate any unique indexes, including the index on the_id field of the original output collection.

Transactions

$out is not allowed in transactions.

Views

New in version 4.2.

The $out stage is not allowed as part of a viewdefinition. If the view definition includes nestedpipeline (e.g. the view definition includes $lookup or$facet stage), this $out stage restrictionapplies to the nested pipelines as well. [1]

linearizable Read Concern

Starting in MongoDB 4.2, the $out stage cannot be usedin conjunction with read concern "linearizable". Thatis, if you specify "linearizable" read concern fordb.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 anaggregation that includes an $out stage.

In MongoDB 4.0 and earlier, you cannot include the $outstage to use "majority" read concern for the aggregation.

Example

A collection books contains the following documents:

{ "_id" : 8751, "title" : "The Banquet", "author" : "Dante", "copies" : 2 }
{ "_id" : 8752, "title" : "Divine Comedy", "author" : "Dante", "copies" : 1 }
{ "_id" : 8645, "title" : "Eclogues", "author" : "Dante", "copies" : 2 }
{ "_id" : 7000, "title" : "The Odyssey", "author" : "Homer", "copies" : 10 }
{ "_id" : 7020, "title" : "Iliad", "author" : "Homer", "copies" : 10 }

The following aggregation operation pivots the data in the bookscollection to have titles grouped by authors and then writesthe results to the authors collection.

db.books.aggregate( [
                      { $group : { _id : "$author", books: { $push: "$title" } } },
                      { $out : "authors" }
                  ] )

After the operation, the authors collection contains the followingdocuments:

{ "_id" : "Homer", "books" : [ "The Odyssey", "Iliad" ] }
{ "_id" : "Dante", "books" : [ "The Banquet", "Divine Comedy", "Eclogues" ] }