$out (aggregation)

Comparison with $merge与$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. 随着$merge在4.2版本中的引入，MongoDB提供了两个阶段，$merge和$out，用于将聚合管道的结果写入集合。The following summarizes the capabilities of the two stages:以下总结了两个阶段的功能：

$out Read Operations Run on Secondary Replica Set Members在辅助副本集成员上运行$out读取操作

Starting in MongoDB 5.0, $out can run on replica set secondary nodes if all the nodes in cluster have featureCompatibilityVersion set to 5.0 or higher and the Read Preference is set to secondary.从MongoDB 5.0开始，如果集群中的所有节点都将featureCompatibilityVersion设置为5.0或更高版本，并且读取首选项设置为次要，$out可以在副本集次要节点上运行。

Read operations of the $out statement occur on the secondary nodes, while the write operations occur only on the primary nodes.$out语句的读取操作发生在辅助节点上，而写入操作仅发生在主节点上。

Not all driver versions support targeting of $out operations to replica set secondary nodes. 并非所有驱动程序版本都支持将$out操作定向到副本集辅助节点。Check your driver documentation to see when your driver added support for $out running on a secondary.查看驱动程序文档，了解驱动程序何时添加了对在辅助设备上运行$out的支持。

Create New Collection创建新集合

The $out operation creates a new collection if one does not already exist.$out操作会创建一个新集合（如果该集合还不存在）。

The collection is not visible until the aggregation completes. If the aggregation fails, MongoDB does not create the collection.在聚合完成之前，集合不可见。如果聚合失败，MongoDB不会创建集合。

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. 如果$out操作指定的集合已经存在，那么在聚合完成后，$out阶段会用新的结果集合原子地替换现有集合。Specifically, the $out operation:具体而言，$out操作：

1. Creates a temp collection.创建临时集合。
2. Copies the indexes from the existing collection to the temp collection.将索引从现有集合复制到临时集合。
3. Inserts the documents into the temp collection.将文档插入临时集合中。
4. Calls the renameCollection command with dropTarget: true to rename the temp collection to the destination collection.使用dropTarget:true调用renameCollection命令，将临时集合重命名为目标集合。

The $out operation does not change any indexes that existed on the previous collection. $out操作不会更改上一个集合上存在的任何索引。If the aggregation fails, the $out operation makes no changes to the pre-existing collection.如果聚合失败，$out操作不会对预先存在的集合进行任何更改。

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.如果管道生成的文档违反任何唯一索引，包括原始输出集合的_id字段上的索引，则管道将无法完成。

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.如果$out操作使用Atlas Search索引修改集合，则必须删除并重新创建搜索索引。请考虑改用$merge。

majority Read Concern读取关注

Starting in MongoDB 4.2, you can specify read concern level "majority" for an aggregation that includes an $out stage.从MongoDB 4.2开始，您可以为包含$out阶段的聚合指定读取关注级别"majority"。

Interaction with mongodump与mongodump的交互

A mongodump started with --oplog fails if a client issues an aggregation pipeline that includes $out during the dump process. 如果客户端在转储过程中发出包含$out的聚合管道，则以--oplog启动的mongodump将失败。See mongodump --oplog for more information.有关详细信息，请参阅mongodump --oplog。

Restrictions限制

Output to Same Database输出到同一数据库

The following aggregation operation pivots the data in the books collection in the test database to have titles grouped by authors and then writes the results to the authors collection, also in the test database.以下聚合操作将test数据库中books集合中的数据调整为按作者分组的标题，然后将结果写入test数据库中的authors集合。

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

First Stage ($group):第一阶段 ($group)：

The $group stage groups by the authors and uses $push to add the titles to a books array field:$group阶段按authors（作者）分组，并使用$push将标题添加到books数组字段：

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

Second Stage ($out):第二阶段 ($out)：

The $out stage outputs the documents to the authors collection in the test database.$out阶段将文档输出到test数据库中的authors集合。

To view the documents in the output collection, run the following operation:若要查看输出集合中的文档，请运行以下操作：

db.getSiblingDB("test").authors.find()

The collection contains the following documents:该集合包含以下文档：

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

Output to a Different Database输出到其他数据库

Starting in MongoDB 4.4, $out can output to a collection in a database different from where the aggregation is run.从MongoDB 4.4开始，$out可以输出到与运行聚合的数据库不同的数据库中的集合。

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 in the reporting database:以下聚合操作将books集合中的数据调整为按作者分组的标题，然后将结果写入reporting数据库中的authors集合：

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

First Stage ($group):第一阶段 ($group)：

The $group stage groups by the authors and uses $push to add the titles to a books array field:$group阶段按authors分组，并使用$push将标题添加到books数组字段：

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

Second Stage ($out):第二阶段 ($out)：

The $out stage outputs the documents to the authors collection in the reporting database.$out阶段将文档输出到reporting数据库中的authors集合。

To view the documents in the output collection, run the following operation:若要查看输出集合中的文档，请运行以下操作：

db.getSiblingDB("reporting").authors.find()

The collection contains the following documents:该集合包含以下文档：

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