$merge (aggregation)

On this page本页内容

Definition定义

Note注意

This page describes the $merge stage, which outputs the aggregation pipeline results to a collection. 本页介绍$merge阶段，该阶段将聚合管道结果输出到集合。For the $mergeObjects operator, which merges documents into a single document, see $mergeObjects.有关将文档合并为单个文档的$mergeObjects运算符，请参阅$mergeObjects。

$merge

New in version 4.2.在版本4.2中新增。

Writes the results of the aggregation pipeline to a specified collection. 将聚合管道的结果写入指定集合。The $merge operator must be the last stage in the pipeline.$merge运算符必须是管道中的最后一个阶段。

The $merge stage:$merge阶段：

  • Can output to a collection in the same or different database.可以输出到相同或不同数据库中的集合。

  • Starting in MongoDB 4.4:从MongoDB 4.4开始：

    • $merge can output to the same collection that is being aggregated. 可以输出到正在聚合的同一集合。For more information, see Output to the Same Collection that is Being Aggregated.有关详细信息，请参阅输出到正在聚合的同一集合。

    • Pipelines with the $merge stage can run on replica set secondary nodes if all the nodes in cluster have featureCompatibilityVersion set to 4.4 or higher and the Read Preference allows secondary reads.如果集群中的所有节点都将featureCompatibilityVersion设置为4.4或更高，并且读取首选项允许辅助读取，则带有$merge阶段的管道可以在副本集辅助节点上运行。

      • Read operations of the $merge statement are sent to secondary nodes, while the write operations occur only on the primary node.$merge语句的读操作被发送到辅助节点，而写操作只发生在主节点上。
      • Not all driver versions support targeting of $merge operations to replica set secondary nodes. 并非所有驱动程序版本都支持将$merge操作定向到副本集辅助节点。Check your driver documentation to see when your driver added support for $merge read operations running on secondary nodes.检查驱动程序文档，查看驱动程序何时添加了对在辅助节点上运行的$merge读取操作的支持。
  • Creates a new collection if the output collection does not already exist.如果输出集合不存在，则创建新集合。
  • Can incorporate results (insert new documents, merge documents, replace documents, keep existing documents, fail the operation, process documents with a custom update pipeline) into an existing collection.可以将结果（插入新文档、合并文档、替换文档、保留现有文档、操作失败、使用自定义更新管道处理文档）合并到现有集合中。
  • Can output to a sharded collection. 可以输出到分片集合。Input collection can also be sharded.输入集合也可以分片。

For a comparison with the $out stage which also outputs the aggregation results to a collection, see $merge and $out Comparison.有关与也将聚合结果输出到集合的$out阶段的比较，请参阅$merge和$out比较。

Note注意
On-Demand Materialized Views按需物化视图

$merge can incorporate the pipeline results into an existing output collection rather than perform a full replacement of the collection. 可以将管道结果合并到现有的输出集合中，而不是执行集合的完全替换。This functionality allows users to create on-demand materialized views, where the content of the output collection is incrementally updated when the pipeline is run.此功能允许用户创建按需的物化视图，其中输出集合的内容在管道运行时以增量方式更新。

For more information on this use case, see On-Demand Materialized Views as well as the examples on this page.有关此用例的更多信息，请参阅按需物化视图以及本页上的示例。

Materialized views are separate from read-only views. 物化视图与只读视图是分开的。For information on creating read-only views, see read-only views.有关创建只读视图的信息，请参阅只读视图。

Syntax语法

$merge has the following syntax:具有以下语法：

{ $merge: {
     into: <collection> -or- { db: <db>, coll: <collection> },
     on: <identifier field> -or- [ <identifier field1>, ...],  // Optional
     let: <variables>,
                                         // Optional
     whenMatched: <replace|keepExisting|merge|fail|pipeline>,  // Optional
     whenNotMatched: <insert|discard|fail>
                     // Optional
} }

For example:例如：

{ $merge: { into: "myOutput", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } }

If using all default options for $merge, including writing to a collection in the same database, you can use the simplified form:如果使用$merge的所有默认选项，包括写入同一数据库中的集合，则可以使用简化形式：

{ $merge: <collection> } // Output collection is in the same database

The $merge takes a document with the following fields:$merge获取具有以下字段的文档：

Field字段Description描述
into

The output collection. Specify either:输出集合。指定：

  • The collection name as a string to output to a collection in the same database where the aggregation is run. 将集合名称作为字符串输出到运行聚合的同一数据库中的集合。For example:例如：

    into: "myOutput"

  • The database and collection name in a document to output to a collection in the specified database. 文档中要输出到指定数据库中集合的数据库和集合名称。For example:例如：

    into: { db:"myDB", coll:"myOutput" }
Note注意

  • If the output collection does not exist, $merge creates the collection:如果输出集合不存在，$merge将创建集合：

    • For a replica set or a standalone, if the output database does not exist, $merge also creates the database.对于副本集或独立数据库，如果输出数据库不存在，$merge也会创建数据库。
    • For a sharded cluster, the specified output database must already exist.对于分片集群，指定的输出数据库必须已经存在。
  • The output collection can be a sharded collection.输出集合可以是分片集合。
on

Optional. 可选。Field or fields that act as a unique identifier for a document. 用作文档唯一标识符的一个或多个字段。The identifier determines if a results document matches an existing document in the output collection. 标识符确定结果文档是否与输出集合中的现有文档匹配。Specify either:指定以下两者之一：

  • A single field name as a string. 作为字符串的单个字段名。For example:例如：

    on: "_id"

  • A combination of fields in an array. 数组中字段的组合。For example:例如：

    on: [ "date", "customerId" ]
    The order of the fields in the array does not matter, and you cannot specify the same field multiple times.数组中字段的顺序无关紧要，不能多次指定同一字段。

For the specified field or fields:对于指定的一个或多个字段：

  • The aggregation results documents must contain the field(s) specified in the on, unless the on field is the _id field. 聚合结果文档必须包含on中指定的字段，除非on字段是_id字段。If the _id field is missing from a results document, MongoDB adds it automatically.如果结果文档中缺少_id字段，MongoDB会自动添加它。
  • The specified field or fields cannot contain a null or an array value.指定的字段不能包含null或数组值。

$merge requires a unique, index with keys that correspond to the on identifier fields. 需要唯一的索引，索引中的键对应于on标识符字段。Although the order of the index key specification does not matter, the unique index must only contain the on fields as its keys.虽然索引键规范的顺序无关紧要，但唯一索引只能包含on字段作为其键。

  • The index must also have the same collation as the aggregation's collation.索引的排序规则也必须与聚合的排序规则相同。
  • The unique index can be a sparse index.唯一索引可以是稀疏索引。
  • The unique index cannot be a partial index.唯一索引不能是部分索引。
  • For output collections that already exist, the corresponding index must already exist.对于已经存在的输出集合，相应的索引必须已经存在。

The default value for on depends on the output collection:on的默认值取决于输出集合：

  • If the output collection does not exist, the on identifier must be and defaults to the _id field. 如果输出集合不存在，则on标识符必须为且默认为_id字段。The corresponding unique _id index is automatically created.自动创建相应的唯一_id索引。

    Tip提示

    To use a different on identifier field(s) for a collection that does not exist, you can create the collection first by creating a unique index on the desired field(s). 若要为不存在的集合使用不同的on标识符字段，可以首先通过在所需字段上创建唯一索引来创建集合。See the section on non-existent output collection for an example.有关示例，请参阅不存在输出集合一节。

  • If the existing output collection is unsharded, the on identifier defaults to the _id field.如果现有输出集合未共享，则on标识符默认为_id字段。
  • If the existing output collection is a sharded collection, the on identifier defaults to all the shard key fields and the _id field. 如果现有输出集合是分片集合，则on标识符默认为所有分片键字段和_id字段。If specifying a different on identifier, the on must contain all the shard key fields.如果指定不同的on标识符，则on必须包含所有分片键字段。
whenMatched

Optional. 可选。The behavior of $merge if a result document and an existing document in the collection have the same value for the specified on field(s).如果集合中的结果文档和现有文档对于指定的on字段具有相同的值，$merge的行为。

You can specify either:您可以指定：

  • One of the pre-defined action strings:预定义的动作字符串之一：

    ActionDescription描述
    "replace"

    Replace the existing document in the output collection with the matching results document.用匹配的结果文档替换输出集合中的现有文档。

    When performing a replace, the replacement document cannot result in a modification of the _id value or, if the output collection is sharded, the shard key value. 执行替换时，替换文档不能导致修改_id值，或者如果输出集合被分片，则修改分片键值。Otherwise, the operation generates an error.否则，操作将生成错误。

    Tip提示

    To avoid this error, if the on field does not include the _id field, remove the _id field in the aggregation results to avoid the error, such as with a preceding $unset stage, and so on.为了避免此错误，如果on字段不包括_id字段，请在聚合结果中删除_id字段以避免错误，例如使用前面的$unset阶段，等等。

    "keepExisting"

    Keep the existing document in the output collection.将现有文档保留在输出集合中。

    "merge" (Default)

    Merge the matching documents (similar to the $mergeObjects operator).合并匹配的文档（类似于$mergeObjects运算符）。

    • If the results document contains fields not in the existing document, add these new fields to the existing document.如果结果文档包含不在现有文档中的字段，请将这些新字段添加到现有文档中。
    • If the results document contains fields in the existing document, replace the existing field values with those from the results document.如果结果文档包含现有文档中的字段，请将现有字段值替换为结果文档中的值。

    For example, if the output collection has the document:例如，如果输出集合具有以下文档：

    { _id: 1, a: 1, b: 1 }

    And the aggregation results has the document:并且聚合结果具有文档：

    { _id: 1, b: 5, z: 1 }

    Then, the merged document is:那么，合并的文档是：

    { _id: 1, a: 1, b: 5, z: 1 }

    When performing a merge, the merged document cannot result in a modification of the _id value or, if the output collection is sharded, the shard key value. Otherwise, the operation generates an error.执行合并时，合并的文档不能导致修改_id值，或者如果输出集合被分片，则不能修改分片键值。否则，操作将生成错误。

    Tip提示

    To avoid this error, if the on field does not include the _id field, remove the _id field in the aggregation results to avoid the error, such as with a preceding $unset stage, and so on.为了避免此错误，如果on字段不包括_id字段，请在聚合结果中删除_id字段以避免错误，例如使用前面的$unset阶段，等等。

    "fail"

    Stop and fail the aggregation operation. Any changes to the output collection from previous documents are not reverted.停止聚合操作并失败。以前文档中对输出集合的任何更改都不会恢复。

  • An aggregation pipeline to update the document in the collection.用于更新集合中文档的聚合管道。

    [ <stage1>, <stage2> ... ]

    The pipeline can only consist of the following stages:管道只能由以下阶段组成：

    The pipeline cannot modify the on field's value. 管道无法修改on字段的值。For example, if you are matching on the field month, the pipeline cannot modify the month field.例如，如果在字段month上进行匹配，则管道无法修改month字段。

    The whenMatched pipeline can directly access the fields of the existing documents in the output collection using $<field>.WhenMatch管道可以使用$<field>直接访问输出集合中现有文档的字段。

    To access the fields from the aggregation results documents, use either:要访问聚合结果文档中的字段，请使用：

    • The built-in $$new variable to access the field. 用于访问字段的内置$$new变量。Specifically, $$new.<field>. 具体来说，$$new.<field>。The $$new variable is only available if the let specification is omitted.$$new变量仅在省略let规范时可用。

      Note注意

      Starting in MongoDB 4.2.2, the $$new variable is reserved, and cannot be overridden.从MongoDB 4.2.2开始，$$new变量是保留的，不能被重写。

    • The user-defined variables in the let field.let字段中的用户定义变量。

      Specify the double dollar sign ($$) prefix together with the variable name in the form $$<variable_name>. 以$$<variable_name>的形式指定双美元符号（$$）前缀和变量名。For example, $$year. 例如，$$year。If the variable is set to a document, you can also include a document field in the form $$<variable_name>.<field>. 如果变量设置为文档，则还可以以$$<variable_name>.<field>的形式包含文档字段。For example, $$year.month.例如，$$year.month。

      For more examples, see Use Variables to Customize the Merge.有关更多示例，请参阅使用变量自定义合并。

let

Optional. 可选。Specifies variables for use in the whenMatched pipeline.指定在WhenMatch管道中使用的变量。

Specify a document with the variable names and value expressions:使用变量名和值表达式指定文档：

{ <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n> }

If unspecified, defaults to { new: "$$ROOT" } (see ROOT). 如果未指定，则默认为{ new: "$$ROOT" }（请参见ROOT）。The whenMatched pipeline can access the $$new variable.WhenMatch管道可以访问$$new变量。

Note注意

Starting in MongoDB 4.2.2, the $$new variable is reserved, and cannot be overridden.从MongoDB 4.2.2开始，$$new变量是保留的，不能被重写。

To access the variables in the whenMatched pipeline:要访问whenMatch管道中的变量：

Specify the double dollar sign ($$) prefix together with the variable name in the form $$<variable_name>. 以$$<variable_name>的形式指定双美元符号（$$）前缀和变量名。For example, $$year. 例如，$$year。If the variable is set to a document, you can also include a document field in the form $$<variable_name>.<field>. 如果变量设置为文档，则还可以以$$<variable_name>.<field>的形式包含文档字段。For example, $$year.month.例如，$$year.month。

For examples, see Use Variables to Customize the Merge.有关示例，请参阅使用变量自定义合并。

whenNotMatched

Optional. 可选。The behavior of $merge if a result document does not match an existing document in the out collection.如果结果文档与out集合中的现有文档不匹配，$merge的行为。

You can specify one of the pre-defined action strings:您可以指定一个预定义的操作字符串：

ActionDescription描述
"insert" (Default)

Insert the document into the output collection.将文档插入到输出集合中。

"discard"

Discard the document. 丢弃文档。Specifically, $merge does not insert the document into the output collection.具体来说，$merge不会将文档插入到输出集合中。

"fail"

Stop and fail the aggregation operation. 停止聚合操作并失败。Any changes already written to the output collection are not reverted.已写入输出集合的任何更改都不会恢复。

Considerations注意事项

_id Field Generation_id字段生成

If the _id field is not present in a document from the aggregation pipeline results, the $merge stage generates it automatically.如果聚合管道结果的文档中不存在_id字段，$merge阶段将自动生成该字段。

For example, in the following aggregation pipeline, $project excludes the _id field from the documents passed into $merge. 例如，在以下聚合管道中，$project从传递到$merge的文档中排除_id字段。When $merge writes these documents to the "newCollection", $merge generates a new _id field and value.当$merge将这些文档写入"newCollection"时，$merge将生成一个新的_id字段和值。

db.sales.aggregate( [
   { $project: { _id: 0 } },
   { $merge : { into : "newCollection" } }
] )

Create a New Collection if Output Collection is Non-Existent如果输出集合不存在，则创建新集合

The $merge operation creates a new collection if the specified output collection does not exist.如果指定的输出集合不存在，$merge操作将创建新集合。

  • The output collection is created when $merge writes the first document into the collection and is immediately visible.当$merge将第一个文档写入集合时，将创建输出集合，并立即可见。
  • If the aggregation fails, any writes completed by the $merge before the error will not be rolled back.如果聚合失败，则不会回滚在错误发生之前由$merge完成的任何写入。
Note注意

For a replica set or a standalone, if the output database does not exist, $merge also creates the database.对于副本集或独立数据库，如果输出数据库不存在，$merge也会创建数据库。

For a sharded cluster, the specified output database must already exist.对于分片集群，指定的输出数据库必须已经存在。

If the output collection does not exist, $merge requires the on identifier to be the _id field. 如果输出集合不存在，$merge要求on标识符为_id字段。To use a different on field value for a collection that does not exist, you can create the collection first by creating a unique index on the desired field(s) first. 要为不存在的集合使用不同的on字段值，可以先在所需字段上创建唯一索引，然后创建集合。For example, if the output collection newDailySales201905 does not exist and you want to specify the salesDate field as the on identifier:例如，如果输出集合newDailySales201905不存在，并且您希望将salesDate字段指定为on标识符：

db.newDailySales201905.createIndex( { salesDate: 1 }, { unique: true } )
db.sales.aggregate( [
   { $match: { date: { $gte: new Date("2019-05-01"), $lt: new Date("2019-06-01") } } },
   { $group: { _id: { $dateToString: { format: "%Y-%m-%d", date: "$date" } }, totalqty: { $sum: "$quantity" } } },
   { $project: { _id: 0, salesDate: { $toDate: "$_id" }, totalqty: 1 } },
   { $merge : { into : "newDailySales201905", on: "salesDate" } }
] )

Output to a Sharded Collection输出到分片集合

The $merge stage can output to a sharded collection. $merge阶段可以输出到分片集合。When the output collection is sharded, $merge uses the _id field and all the shard key fields as the default on identifier. 当输出集合被分片时，$merge使用_id字段和所有分片键字段作为默认的on标识符。If you override the default, the on identifier must include all the shard key fields:如果覆盖默认值，则on标识符必须包括所有分片键字段：

{ $merge: {
   into: "<shardedColl>" or { db:"<sharding enabled db>", coll: "<shardedColl>" },
   on: [ "<shardkeyfield1>", "<shardkeyfield2>",... ], // Shard key fields and any additional fields
   let: <variables>,
                                         // Optional
   whenMatched: <replace|keepExisting|merge|fail|pipeline>,  // Optional
   whenNotMatched: <insert|discard|fail>
                     // Optional
} }

For example, in a database that has sharding enabled, use the sh.shardCollection() method to create a new sharded collection newrestaurants with the postcode field as the shard key.例如，在已启用分片的数据库中，使用sh.shardCollection()方法创建一个新的分片集合newrestaurants，其中postcode字段作为分片键。

sh.enableSharding("exampledb");
     // Sharding must be enabled in the database
sh.shardCollection(
   "exampledb.newrestaurants",
      // Namespace of the collection to shard
   { postcode: 1 },
                 // Shard key
);

The newrestaurants collection will contain documents with information on new restaurant openings by month (date field) and postcode (shard key); specifically, the on identifier is ["date", "postcode"] (the ordering of the fields does not matter). newrestaurants集合将包含关于每月新餐厅开业信息的文档（date字段）和邮政编码（分片键）；具体而言，on标识符为["date", "postcode"]（字段的顺序无关紧要）。Because $merge requires a unique index with keys that correspond to the on identifier fields, create the unique index (the ordering of the fields do not matter): 由于$merge需要一个唯一索引，其键对应于on标识符字段，因此创建唯一索引（字段的顺序无关紧要）：[1]

use exampledb
db.newrestaurants.createIndex( { postcode: 1, date: 1 }, { unique: true } )

With the sharded collection restaurants and the unique index created, you can use $merge to output the aggregation results to this collection, matching on [ "date", "postcode" ] as in this example:使用分片的集合restaurants和创建的唯一索引，您可以使用$merge将聚合结果输出到此集合，并在[ "date", "postcode" ]匹配，如下例所示：

use exampledb
db.openings.aggregate([
   { $group: {
      _id: { date: { $dateToString: { format: "%Y-%m", date: "$date" } }, postcode: "$postcode" },
      restaurants: { $push: "$restaurantName" } } },
   { $project: { _id: 0, postcode: "$_id.postcode", date: "$_id.date", restaurants: 1 } },
   { $merge: { into: "newrestaurants", "on": [ "date", "postcode" ], whenMatched: "replace", whenNotMatched: "insert" } }
])
[1] The sh.shardCollection() method can also create a unique index on the shard key when passed the { unique: true } option if: the shard key is range-based, the collection is empty, and a unique index on the shard key doesn't already exist.当传递{ unique: true }选项时，sh.shardCollection()方法还可以在分片键上创建唯一索引，如果：分片键基于范围，集合为空，并且分片键上的唯一索引不存在。In the previous example, because the on identifier is the shard key and another field, a separate operation to create the corresponding index is required.在前面的示例中，因为on标识符是分片键和另一个字段，所以需要单独的操作来创建相应的索引。

Replace Documents ($merge) vs Replace Collection ($out)替换文档（$merge）vs替换集合（$out）

$merge can replace an existing document in the output collection if the aggregation results contain a document or documents that match based on the on specification. 如果聚合结果包含基于on规范匹配的一个或多个文档，则可以替换输出集合中的现有文档。As such, $merge can replace all documents in the existing collection if the aggregation results include matching documents for all existing documents in the collection and you specify "replace" for whenMatched.因此，如果聚合结果包括集合中所有现有文档的匹配文档，并且您为whenMatched指定了"replace"，则$merge可以替换现有集合中的所有文档。

However, to replace an existing collection regardless of the aggregation results, use $out instead.但是，要替换现有集合而不管聚合结果如何，请改用$out。

Existing Documents and _id and Shard Key Values现有文档和_id和Shard键值

The $merge errors if the $merge results in a change to an existing document's _id value.如果$merge导致现有文档的_id值发生更改，则$merge错误。

Tip提示

To avoid this error, if the on field does not include the _id field, remove the _id field in the aggregation results to avoid the error, such as with a preceding $unset stage, and so on.为了避免此错误，如果on字段不包括_id字段，请在聚合结果中删除_id字段以避免错误，例如使用前面的$unset阶段，等等。

Additionally, for a sharded collection, $merge also generates an error if it results in a change to the shard key value of an exising document.此外，对于分片集合，$merge如果导致现有文档的分片键值发生更改，也会生成错误。

Any writes completed by the $merge before the error will not be rolled back.$merge在错误之前完成的任何写入都不会回滚。

Unique Index Constraints唯一索引约束

If the unique index used by $merge for on field(s) is dropped mid-aggregation, there is no guarantee that the aggregation will be killed. 如果在聚合过程中删除了on字段上的$merge使用的唯一索引，则无法保证聚合将被终止。If the aggregation continues, there is no guarantee that documents do not have duplicate on field values.如果聚合继续，则无法保证文档不会有重复的on字段值。

If the $merge attempts to write a document that violates any unique index on the output collection, the operation generates an error. 如果$merge试图写入违反输出集合上任何唯一索引的文档，则该操作将生成错误。For example:例如：

  • Insert a non-matching document插入不匹配的文档 that violates a unique index other than the index on the on field(s).这违反了除on字段上的索引之外的唯一索引。
  • Fail if there is a matching document in the collection. 如果集合中有匹配的文档，则失败。Specifically, the operation attempts to insert the matching document which violates the unique index on the on field(s).具体而言，该操作尝试插入与on字段上的唯一索引相冲突的匹配文档。
  • Replace an existing document with a new document that violates a unique index other than the index on the on field(s).将现有文档替换为新文档，该新文档违反了除on字段上的索引之外的唯一索引。
  • Merge the matching documents that results in a document that violates a unique index other than the index on the on field(s).合并匹配文档，这会导致文档违反唯一索引，而不是字段on上的索引。

whenMatched Pipeline Behavior管道行为

Starting in MongoDB 4.2.2, if all of the following are true for a $merge stage:从MongoDB 4.2.2开始，如果$merge阶段的以下所有条件均为真：

  • The value of whenMatched is an aggregation pipeline,whenMatched的值是聚合管道，
  • The value of whenNotMatched is insert, andwhenNotMatched的值为insert，并且
  • There is no match for a document in the output collection,输出集合中的文档不匹配，

$merge inserts the document directly into the output collection.将文档直接插入到输出集合中。

Prior to MongoDB 4.2.2, when these conditions for a $merge stage are met, the pipeline specified in the whenMatched field is executed with an empty input document. 在MongoDB 4.2.2之前，当满足$merge阶段的这些条件时，将使用空输入文档执行whenMatched字段中指定的管道。The resulting document from the pipeline is inserted into the output collection.来自管道的结果文档被插入到输出集合中。

Tip提示
See also: 参阅：

$merge and $out Comparison$merge和$out比较

With the introduction of $merge, MongoDB provides two stages, $merge and $out, for writing the results of the aggregation pipeline to a collection:随着$merge的引入，MongoDB提供了两个阶段$merge和$out，用于将聚合管道的结果写入集合：

$merge$out
  • Available starting in MongoDB 4.2从MongoDB 4.2开始提供
  • Available starting in MongoDB 2.6从MongoDB 2.6开始提供
  • Can output to a collection in the same or different database.可以输出到相同或不同数据库中的集合。
  • Can output to a collection in the same or, starting in MongoDB 4.4, different database.可以输出到同一数据库中的集合，或者从MongoDB 4.4开始，输出到不同的数据库中。
  • Creates a new collection if the output collection does not already exist.如果输出集合不存在，则创建新集合。
  • Creates a new collection if the output collection does not already exist.如果输出集合不存在，则创建新集合。
  • Replaces the output collection completely if it already exists.如果输出集合已存在，则完全替换它。
  • Can output to a sharded collection. 可以输出到分片集合。Input collection can also be sharded.输入集合也可以被分片。
  • Cannot output to a sharded collection. 无法输出到分片集合。Input collection, however, can be sharded.然而，输入集合可以被分片。

  • Corresponds to SQL statements:对应于SQL语句：

    • MERGE.
    • INSERT INTO T2 SELECT FROM T1.
    • SELECT INTO T2 FROM T1.
    • Create/Refresh Materialized Views.创建/刷新物化视图。

  • Corresponds to SQL statement:对应于SQL语句：

    • INSERT INTO T2 SELECT FROM T1.
    • SELECT INTO T2 FROM T1.

Output to the Same Collection that is Being Aggregated输出到正在聚合的同一集合

Warning警告

When $merge outputs to the same collection that is being aggregated, documents may get updated multiple times or the operation may result in an infinite loop. 当$merge输出到正在聚合的同一集合时，文档可能会被多次更新，或者操作可能导致无限循环。This behavior occurs when the update performed by $merge changes the physical location of documents stored on disk. 当$merge执行的更新更改存储在磁盘上的文档的物理位置时，会发生此行为。When the physical location of a document changes, $merge may view it as an entirely new document, resulting in additional updates. 当文档的物理位置更改时，$merge可能会将其视为一个全新的文档，从而导致其他更新。For more information on this behavior, see Halloween Problem.有关此行为的详细信息，请参阅万圣节问题。

Starting in MongoDB 4.4, $merge can output to the same collection that is being aggregated. 从MongoDB 4.4开始，$merge可以输出到正在聚合的相同集合。You can also output to a collection which appears in other stages of the pipeline, such as $lookup.您还可以输出到出现在管道其他阶段的集合，例如$lookup。

Versions of MongoDB prior to 4.4 did not allow $merge to output to the same collection as the collection being aggregated.MongoDB 4.4之前的版本不允许$merge输出到与聚合的集合相同的集合。

Restrictions限制

Restrictions限制Description描述
Transactions事务An aggregation pipeline cannot use $merge inside a transaction.聚合管道不能在事务中使用$merge。
Time Series Collections时间序列集合An aggregation pipeline cannot use $merge to output to a time series collection.聚合管道不能使用$merge输出到时间序列集合。
View definition视图定义
Separate from materialized view与物化视图分离
View definition cannot include the $merge stage. 视图定义不能包含$merge阶段。If the view definition includes nested pipeline (for example, the view definition includes $facet stage), this $merge stage restriction applies to the nested pipelines as well.如果视图定义包括嵌套管道（例如，视图定义包括$facet阶段），则$merge阶段限制也适用于嵌套管道。
$lookup stage阶段$lookup stage's nested pipeline cannot include the $merge stage.$lookup阶段的嵌套管道不能包含$merge阶段。
$facet stage阶段$facet stage's nested pipeline cannot include the $merge stage.$facet阶段的嵌套管道不能包含$merge阶段。
$unionWith stage阶段$unionWith stage's nested pipeline cannot include the $merge stage.$unionWith阶段的嵌套管道不能包含$merge阶段。
"linearizable" read concern关注阅读

The $merge stage cannot be used in conjunction with read concern "linearizable". $merge阶段不能与读取关注点"linearizable"一起使用。That is, if you specify "linearizable" read concern for db.collection.aggregate(), you cannot include the $merge stage in the pipeline.也就是说，如果为db.collection.aggregate()指定"linearizable"读取关注点，则无法在管道中包含$merge阶段。

Examples示例

On-Demand Materialized View: Initial Creation按需物化视图：初始创建

If the output collection does not exist, the $merge creates the collection.如果输出集合不存在，$merge将创建集合。

For example, a collection named salaries in the zoo database is populated with the employee salary and department history:例如，zoo数据库中名为salaries的集合将填充员工工资和部门历史记录：

db.getSiblingDB("zoo").salaries.insertMany([
   { "_id" : 1, employee: "Ant", dept: "A", salary: 100000, fiscal_year: 2017 },
   { "_id" : 2, employee: "Bee", dept: "A", salary: 120000, fiscal_year: 2017 },
   { "_id" : 3, employee: "Cat", dept: "Z", salary: 115000, fiscal_year: 2017 },
   { "_id" : 4, employee: "Ant", dept: "A", salary: 115000, fiscal_year: 2018 },
   { "_id" : 5, employee: "Bee", dept: "Z", salary: 145000, fiscal_year: 2018 },
   { "_id" : 6, employee: "Cat", dept: "Z", salary: 135000, fiscal_year: 2018 },
   { "_id" : 7, employee: "Gecko", dept: "A", salary: 100000, fiscal_year: 2018 },
   { "_id" : 8, employee: "Ant", dept: "A", salary: 125000, fiscal_year: 2019 },
   { "_id" : 9, employee: "Bee", dept: "Z", salary: 160000, fiscal_year: 2019 },
   { "_id" : 10, employee: "Cat", dept: "Z", salary: 150000, fiscal_year: 2019 }
])

You can use the $group and $merge stages to initially create a collection named budgets (in the reporting database) from the data currently in the salaries collection:您可以使用$group和$merge阶段从当前salaries集合中的数据创建一个名为budgets的集合（在reporting数据库中）：

Note注意

For a replica set or a standalone deployment, if the output database does not exist, $merge also creates the database.对于副本集或独立部署，如果输出数据库不存在，$merge还会创建数据库。

For a sharded cluster deployment, the specified output database must already exist.对于分片集群部署，指定的输出数据库必须已经存在。

db.getSiblingDB("zoo").salaries.aggregate( [
   { $group: { _id: { fiscal_year: "$fiscal_year", dept: "$dept" }, salaries: { $sum: "$salary" } } },
   { $merge : { into: { db: "reporting", coll: "budgets" }, on: "_id",  whenMatched: "replace", whenNotMatched: "insert" } }
] )
  • $group stage to group the salaries by the fiscal_year and dept.按fiscal_year（财政年度）和dept（部门）对工资进行分组的阶段。
  • $merge stage writes the output of the preceding $group stage to the budgets collection in the reporting database.阶段将前一个$group阶段的输出写入报告数据库中的budgets（预算）集合。

To view the documents in the new budgets collection:要查看新budgets集合中的文档：

db.getSiblingDB("reporting").budgets.find().sort( { _id: 1 } )

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

{ "_id" : { "fiscal_year" : 2017, "dept" : "A" }, "salaries" : 220000 }
{ "_id" : { "fiscal_year" : 2017, "dept" : "Z" }, "salaries" : 115000 }
{ "_id" : { "fiscal_year" : 2018, "dept" : "A" }, "salaries" : 215000 }
{ "_id" : { "fiscal_year" : 2018, "dept" : "Z" }, "salaries" : 280000 }
{ "_id" : { "fiscal_year" : 2019, "dept" : "A" }, "salaries" : 125000 }
{ "_id" : { "fiscal_year" : 2019, "dept" : "Z" }, "salaries" : 310000 }
Tip提示

On-Demand Materialized View: Update/Replace Data按需物化视图：更新/替换数据

The following example uses the collections in the previous example.以下示例使用上一示例中的集合。

The example salaries collection contains the employee salary and department history:示例salaries集合包含员工薪资和部门历史记录：

{ "_id" : 1, employee: "Ant", dept: "A", salary: 100000, fiscal_year: 2017 },
{ "_id" : 2, employee: "Bee", dept: "A", salary: 120000, fiscal_year: 2017 },
{ "_id" : 3, employee: "Cat", dept: "Z", salary: 115000, fiscal_year: 2017 },
{ "_id" : 4, employee: "Ant", dept: "A", salary: 115000, fiscal_year: 2018 },
{ "_id" : 5, employee: "Bee", dept: "Z", salary: 145000, fiscal_year: 2018 },
{ "_id" : 6, employee: "Cat", dept: "Z", salary: 135000, fiscal_year: 2018 },
{ "_id" : 7, employee: "Gecko", dept: "A", salary: 100000, fiscal_year: 2018 },
{ "_id" : 8, employee: "Ant", dept: "A", salary: 125000, fiscal_year: 2019 },
{ "_id" : 9, employee: "Bee", dept: "Z", salary: 160000, fiscal_year: 2019 },
{ "_id" : 10, employee: "Cat", dept: "Z", salary: 150000, fiscal_year: 2019 }

The example budgets collection contains the cumulative yearly budgets:示例budgets集合包含累积年度预算：

{ "_id" : { "fiscal_year" : 2017, "dept" : "A" }, "salaries" : 220000 }
{ "_id" : { "fiscal_year" : 2017, "dept" : "Z" }, "salaries" : 115000 }
{ "_id" : { "fiscal_year" : 2018, "dept" : "A" }, "salaries" : 215000 }
{ "_id" : { "fiscal_year" : 2018, "dept" : "Z" }, "salaries" : 280000 }
{ "_id" : { "fiscal_year" : 2019, "dept" : "A" }, "salaries" : 125000 }
{ "_id" : { "fiscal_year" : 2019, "dept" : "Z" }, "salaries" : 310000 }

During the current fiscal year (2019 in this example), new employees are added to the salaries collection and new head counts are pre-allocated for the next year:在当前财政年度（本例中为2019年），新员工被添加到salaries集合中，并为下一年预先分配新的人数：

db.getSiblingDB("zoo").salaries.insertMany([
   { "_id" : 11,  employee: "Wren", dept: "Z", salary: 100000, fiscal_year: 2019 },
   { "_id" : 12,  employee: "Zebra", dept: "A", salary: 150000, fiscal_year: 2019 },
   { "_id" : 13,  employee: "headcount1", dept: "Z", salary: 120000, fiscal_year: 2020 },
   { "_id" : 14,  employee: "headcount2", dept: "Z", salary: 120000, fiscal_year: 2020 }
])

To update the budgets collection to reflect the new salary information, the following aggregation pipeline uses:要更新salaries集合以反映新的薪资信息，以下聚合管道使用：

  • $match stage to find all documents with fiscal_year greater than or equal to 2019.阶段查找fiscal_year大于或等于2019的所有文档。
  • $group stage to group the salaries by the fiscal_year and dept.按fiscal_year（财政年度）和dept（部门）对工资进行分组的阶段。
  • $merge to write the result set to the budgets collection, replacing documents with the same _id value (in this example, a document with the fiscal year and dept). $merge将结果集写入budgets集合，替换具有相同_id值的文档（在本例中，是具有财政年度和部门的文档）。For documents that do not have matches in the collection, $merge inserts the new documents.对于集合中没有匹配项的文档，$merge将插入新文档。
db.getSiblingDB("zoo").salaries.aggregate( [
   { $match : { fiscal_year:  { $gte : 2019 } } },
   { $group: { _id: { fiscal_year: "$fiscal_year", dept: "$dept" }, salaries: { $sum: "$salary" } } },
   { $merge : { into: { db: "reporting", coll: "budgets" }, on: "_id",  whenMatched: "replace", whenNotMatched: "insert" } }
] )

After the aggregation is run, view the documents in the budgets collection:运行聚合后，查看budgets集合中的文档：

db.getSiblingDB("reporting").budgets.find().sort( { _id: 1 } )

The budgets collection incorporates the new salary data for fiscal year 2019 and adds new documents for fiscal year 2020:budgets集合包含了2019财年的新薪资数据，并添加了2020财年的新文档：

{ "_id" : { "fiscal_year" : 2017, "dept" : "A" }, "salaries" : 220000 }
{ "_id" : { "fiscal_year" : 2017, "dept" : "Z" }, "salaries" : 115000 }
{ "_id" : { "fiscal_year" : 2018, "dept" : "A" }, "salaries" : 215000 }
{ "_id" : { "fiscal_year" : 2018, "dept" : "Z" }, "salaries" : 280000 }
{ "_id" : { "fiscal_year" : 2019, "dept" : "A" }, "salaries" : 275000 }
{ "_id" : { "fiscal_year" : 2019, "dept" : "Z" }, "salaries" : 410000 }
{ "_id" : { "fiscal_year" : 2020, "dept" : "Z" }, "salaries" : 240000 }
Tip提示

Only Insert New Data仅插入新数据

To ensure that the $merge does not overwrite existing data in the collection, set whenMatched to keepExisting or fail.要确保$merge不会覆盖集合中的现有数据，请将whenMatched设置为keepExisting或fail。

The example salaries collection in the zoo database contains the employee salary and department history:zoo数据库中的salaries薪资集合包含员工薪资和部门历史记录：

{ "_id" : 1, employee: "Ant", dept: "A", salary: 100000, fiscal_year: 2017 },
{ "_id" : 2, employee: "Bee", dept: "A", salary: 120000, fiscal_year: 2017 },
{ "_id" : 3, employee: "Cat", dept: "Z", salary: 115000, fiscal_year: 2017 },
{ "_id" : 4, employee: "Ant", dept: "A", salary: 115000, fiscal_year: 2018 },
{ "_id" : 5, employee: "Bee", dept: "Z", salary: 145000, fiscal_year: 2018 },
{ "_id" : 6, employee: "Cat", dept: "Z", salary: 135000, fiscal_year: 2018 },
{ "_id" : 7, employee: "Gecko", dept: "A", salary: 100000, fiscal_year: 2018 },
{ "_id" : 8, employee: "Ant", dept: "A", salary: 125000, fiscal_year: 2019 },
{ "_id" : 9, employee: "Bee", dept: "Z", salary: 160000, fiscal_year: 2019 },
{ "_id" : 10, employee: "Cat", dept: "Z", salary: 150000, fiscal_year: 2019 }

A collection orgArchive in the reporting database contains historical departmental organization records for the past fiscal years. reporting数据库中的集合orgArchive包含过去财政年度的历史部门组织记录。Archived records should not be modified.存档记录不应修改。

{ "_id" : ObjectId("5cd8c68261baa09e9f3622be"), "employees" : [ "Ant", "Gecko" ], "dept" : "A", "fiscal_year" : 2018 }
{ "_id" : ObjectId("5cd8c68261baa09e9f3622bf"), "employees" : [ "Ant", "Bee" ], "dept" : "A", "fiscal_year" : 2017 }
{ "_id" : ObjectId("5cd8c68261baa09e9f3622c0"), "employees" : [ "Bee", "Cat" ], "dept" : "Z", "fiscal_year" : 2018 }
{ "_id" : ObjectId("5cd8c68261baa09e9f3622c1"), "employees" : [ "Cat" ], "dept" : "Z", "fiscal_year" : 2017 }

The orgArchive collection has a unique compound index on the fiscal_year and dept fields. orgArchive集合在fiscal_year和dept字段上具有唯一的复合索引。Specifically, there should be at most one record for the same fiscal year and department combination:具体而言，同一财政年度和部门组合最多应有一个记录：

db.getSiblingDB("reporting").orgArchive.createIndex ( { fiscal_year: 1, dept: 1 }, { unique: true } )

At the end of current fiscal year (2019 in this example), the salaries collection contain the following documents:在当前财政年度结束时（本例中为2019年），salaries集合包含以下文件：

{ "_id" : 1, "employee" : "Ant", "dept" : "A", "salary" : 100000, "fiscal_year" : 2017 }
{ "_id" : 2, "employee" : "Bee", "dept" : "A", "salary" : 120000, "fiscal_year" : 2017 }
{ "_id" : 3, "employee" : "Cat", "dept" : "Z", "salary" : 115000, "fiscal_year" : 2017 }
{ "_id" : 4, "employee" : "Ant", "dept" : "A", "salary" : 115000, "fiscal_year" : 2018 }
{ "_id" : 5, "employee" : "Bee", "dept" : "Z", "salary" : 145000, "fiscal_year" : 2018 }
{ "_id" : 6, "employee" : "Cat", "dept" : "Z", "salary" : 135000, "fiscal_year" : 2018 }
{ "_id" : 7, "employee" : "Gecko", "dept" : "A", "salary" : 100000, "fiscal_year" : 2018 }
{ "_id" : 8, "employee" : "Ant", "dept" : "A", "salary" : 125000, "fiscal_year" : 2019 }
{ "_id" : 9, "employee" : "Bee", "dept" : "Z", "salary" : 160000, "fiscal_year" : 2019 }
{ "_id" : 10, "employee" : "Cat", "dept" : "Z", "salary" : 150000, "fiscal_year" : 2019 }
{ "_id" : 11, "employee" : "Wren", "dept" : "Z", "salary" : 100000, "fiscal_year" : 2019 }
{ "_id" : 12, "employee" : "Zebra", "dept" : "A", "salary" : 150000, "fiscal_year" : 2019 }
{ "_id" : 13, "employee" : "headcount1", "dept" : "Z", "salary" : 120000, "fiscal_year" : 2020 }
{ "_id" : 14, "employee" : "headcount2", "dept" : "Z", "salary" : 120000, "fiscal_year" : 2020 }

To update the orgArchive collection to include the fiscal year 2019 that has just ended, the following aggregation pipeline uses:要更新orgArchive集合以包括刚刚结束的2019财年，以下聚合管道使用：

  • $match stage to find all documents with fiscal_year equal to 2019.阶段查找fiscal_year等于2019年的所有文档。
  • $group stage to group the employees by the fiscal_year and dept.按fiscal_year和dept对员工进行分组的阶段。
  • $project stage to suppress the _id field and add separate dept and fiscal_year field. 阶段以抑制_id字段，并添加单独的dept和fiscal_year字段。When the documents are passed to $merge, $merge automatically generates a new _id field for the documents.当文档传递到$merge时，$merge会自动为文档生成一个新的_id字段。

  • $merge to write the result set to orgArchive.将结果集写入orgArchive。

    The $merge stage matches documents on the dept and fiscal_year fields and fails when matched. 阶段匹配dept和fiscal_year字段中的文档，匹配失败。That is, if a document already exists for the same department and fiscal year, the $merge errors.也就是说，如果同一部门和财政年度的文档已经存在，则$merge错误。

db.getSiblingDB("zoo").salaries.aggregate( [
    { $match: { fiscal_year: 2019 }},
    { $group: { _id: { fiscal_year: "$fiscal_year", dept: "$dept" }, employees: { $push: "$employee" } } },
    { $project: { _id: 0, dept: "$_id.dept", fiscal_year: "$_id.fiscal_year", employees: 1 } },
    { $merge : { into : { db: "reporting", coll: "orgArchive" }, on: [ "dept", "fiscal_year" ], whenMatched: "fail" } }
] )

After the operation, the orgArchive collection contains the following documents:操作后，orgArchive集合包含以下文档：

{ "_id" : ObjectId("5caccc6a66b22dd8a8cc419f"), "employees" : [ "Ahn", "Bess" ], "dept" : "A", "fiscal_year" : 2017 }
{ "_id" : ObjectId("5caccc6a66b22dd8a8cc419e"), "employees" : [ "Ahn", "Gee" ], "dept" : "A", "fiscal_year" : 2018 }
{ "_id" : ObjectId("5caccd0b66b22dd8a8cc438e"), "employees" : [ "Ahn", "Zeb" ], "dept" : "A", "fiscal_year" : 2019 }
{ "_id" : ObjectId("5caccc6a66b22dd8a8cc41a0"), "employees" : [ "Carl" ], "dept" : "Z", "fiscal_year" : 2017 }
{ "_id" : ObjectId("5caccc6a66b22dd8a8cc41a1"), "employees" : [ "Bess", "Carl" ], "dept" : "Z", "fiscal_year" : 2018 }
{ "_id" : ObjectId("5caccd0b66b22dd8a8cc438d"), "employees" : [ "Bess", "Carl", "Wen" ], "dept" : "Z", "fiscal_year" : 2019 }

If the orgArchive collection already contained a document for 2019 for department "A" and/or "B", the aggregation fails because of the duplicate key error. 如果orgArchive集合已包含部门"A"和/或"B"的2019年文档，则由于重复密钥错误，聚合失败。However, any document inserted before the error will not be rolled back.但是，错误之前插入的任何文档都不会回滚。

If you specify keepExisting for the matching document, the aggregation does not affect the matching document and does not error with duplicate key error. 如果为匹配文档指定keepExisting，则聚合不会影响匹配文档，并且不会出现重复键错误。Similarly, if you specify replace, the operation would not fail; however, the operation would replace the existing document.类似地，如果指定替换，则操作不会失败；但是，该行动将取代现有文件。

Merge Results from Multiple Collections合并来自多个集合的结果

By default, if a document in the aggregation results matches a document in the collection, the $merge stage merges the documents.默认情况下，如果聚合结果中的文档与集合中的文档匹配，$merge阶段将合并这些文档。

An example collection purchaseorders is populated with the purchase order information by quarter and regions:示例集合purchaseorders按季度和地区填充采购订单信息：

db.purchaseorders.insertMany( [
   { _id: 1, quarter: "2019Q1", region: "A", qty: 200, reportDate: new Date("2019-04-01") },
   { _id: 2, quarter: "2019Q1", region: "B", qty: 300, reportDate: new Date("2019-04-01") },
   { _id: 3, quarter: "2019Q1", region: "C", qty: 700, reportDate: new Date("2019-04-01") },
   { _id: 4, quarter: "2019Q2", region: "B", qty: 300, reportDate: new Date("2019-07-01") },
   { _id: 5, quarter: "2019Q2", region: "C", qty: 1000, reportDate: new Date("2019-07-01") },
   { _id: 6, quarter: "2019Q2", region: "A", qty: 400, reportDate: new Date("2019-07-01") },
] )

Another example collection reportedsales is populated with the reported sales information by quarter and regions:另一个示例集合reportedsales按季度和地区填充报告的销售信息：

db.reportedsales.insertMany( [
   { _id: 1, quarter: "2019Q1", region: "A", qty: 400, reportDate: new Date("2019-04-02") },
   { _id: 2, quarter: "2019Q1", region: "B", qty: 550, reportDate: new Date("2019-04-02") },
   { _id: 3, quarter: "2019Q1", region: "C", qty: 1000, reportDate: new Date("2019-04-05") },
   { _id: 4, quarter: "2019Q2", region: "B", qty: 500, reportDate: new Date("2019-07-02") },
] )

Assume that, for reporting purposes, you want to view the data by quarter in the following format:假设出于报告目的，您希望按季度以以下格式查看数据：

{ "_id" : "2019Q1", "sales" : 1950, "purchased" : 1200 }
{ "_id" : "2019Q2", "sales" : 500, "purchased" : 1700 }

You can use the $merge to merge in results from the purchaseorders collection and the reportedsales collection to create a new collection quarterlyreport.您可以使用$merge合并purchaseorders集合和reportedsales集合的结果，以创建新的集合quarterlyreport。

To create the quarterlyreport collection, you can use the following pipeline:要创建quarterlyreport集合，可以使用以下管道：

db.purchaseorders.aggregate( [
   { $group: { _id: "$quarter", purchased: { $sum: "$qty" } } },  // group purchase orders by quarter
   { $merge : { into: "quarterlyreport", on: "_id",  whenMatched: "merge", whenNotMatched: "insert" } }
])
First stage:第一阶段：

The $group stage groups by the quarter and uses $sum to add the qty fields into a new purchased field. $group阶段按季度分组，并使用$sum将qty字段添加到新的purchased（采购）字段中。For example:例如：

To create the quarterlyreport collection, you can use this pipeline:要创建quarterlyreport集合，可以使用以下管道：

{ "_id" : "2019Q2", "purchased" : 1700 }
{ "_id" : "2019Q1", "purchased" : 1200 }
Second stage:第二阶段：
The $merge stage writes the documents to the quarterlyreport collection in the same database. $merge阶段将文档写入同一数据库中的quarterlyreport集合。If the stage finds an existing document in the collection that matches on the _id field, the stage merges the matching documents. 如果阶段在集合中找到与_id字段匹配的现有文档，则阶段将合并匹配文档。Otherwise, the stage inserts the document. 否则，阶段将插入文档。For the initial creation, no documents should match.对于初始创建，不应匹配任何文档。

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

db.quarterlyreport.find().sort( { _id: 1 } )

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

{ "_id" : "2019Q1", "sales" : 1200, "purchased" : 1200 }
{ "_id" : "2019Q2", "sales" : 1700, "purchased" : 1700 }

Similarly, run the following aggregation pipeline against the reportedsales collection to merge the sales results into the quarterlyreport collection.类似地，对reportedsales集合运行以下聚合管道，以将销售结果合并到quarterlyreport集合中。

db.reportedsales.aggregate( [
   { $group: { _id: "$quarter", sales: { $sum: "$qty" } } },  // group sales by quarter
   { $merge : { into: "quarterlyreport", on: "_id",  whenMatched: "merge", whenNotMatched: "insert" } }
])
First stage:第一阶段：

The $group stage groups by the quarter and uses $sum to add the qty fields into a new sales field. $group阶段按季度分组，并使用$sum将qty字段添加到新的sales字段中。For example:例如：

{ "_id" : "2019Q2", "sales" : 500 }
{ "_id" : "2019Q1", "sales" : 1950 }
Second stage:第二阶段：
The $merge stage writes the documents to the quarterlyreport collection in the same database. $merge阶段将文档写入同一数据库中的quarterlyreport集合。If the stage finds an existing document in the collection that matches on the _id field (the quarter), the stage merges the matching documents. 如果阶段在集合中找到与_id字段（季度）匹配的现有文档，则阶段合并匹配的文档。Otherwise, the stage inserts the document.否则，阶段将插入文档。

To view the documents in the quarterlyreport collection after the data has been merged, run the following operation:要在合并数据后查看quarterlyreport集合中的文档，请运行以下操作：

db.quarterlyreport.find().sort( { _id: 1 } )

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

{ "_id" : "2019Q1", "sales" : 1950, "purchased" : 1200 }
{ "_id" : "2019Q2", "sales" : 500, "purchased" : 1700 }

Use the Pipeline to Customize the Merge使用管道自定义合并

The $merge can use a custom update pipeline when documents match. 当文档匹配时，$merge可以使用自定义更新管道。The whenMatched pipeline can have the following stages:whenMatched管道可以具有以下阶段：

An example collection votes is populated with the daily vote tally. 使用每日投票记录填充示例votes集合。Create the collection with the following documents:使用以下文档创建集合：

db.votes.insertMany( [
   { date: new Date("2019-05-01"), "thumbsup" : 1, "thumbsdown" : 1 },
   { date: new Date("2019-05-02"), "thumbsup" : 3, "thumbsdown" : 1 },
   { date: new Date("2019-05-03"), "thumbsup" : 1, "thumbsdown" : 1 },
   { date: new Date("2019-05-04"), "thumbsup" : 2, "thumbsdown" : 2 },
   { date: new Date("2019-05-05"), "thumbsup" : 6, "thumbsdown" : 10 },
   { date: new Date("2019-05-06"), "thumbsup" : 13, "thumbsdown" : 16 }
] )

Another example collection monthlytotals has the up-to-date monthly vote totals. 另一个示例集合monthlytotals具有最新的每月投票总数。Create the collection with the following document:使用以下文档创建集合：

db.monthlytotals.insertOne(
   { "_id" : "2019-05", "thumbsup" : 26, "thumbsdown" : 31 }
)

At the end of each day, that day's votes is inserted into the votes collection:每天结束时，将当天的投票插入votes集合：

db.votes.insertOne(
   { date: new Date("2019-05-07"), "thumbsup" : 14, "thumbsdown" : 10 }
)

You can use $merge with an custom pipeline to update the existing document in the collection monthlytotals:您可以使用$merge和自定义管道来更新集合monthlytotals中的现有文档：

db.votes.aggregate([
   { $match: { date: { $gte: new Date("2019-05-07"), $lt: new Date("2019-05-08") } } },
   { $project: { _id: { $dateToString: { format: "%Y-%m", date: "$date" } }, thumbsup: 1, thumbsdown: 1 } },
   { $merge: {
         into: "monthlytotals",
         on: "_id",
         whenMatched:  [
            { $addFields: {
                thumbsup: { $add:[ "$thumbsup", "$$new.thumbsup" ] },
                thumbsdown: { $add: [ "$thumbsdown", "$$new.thumbsdown" ] }
            } } ],
         whenNotMatched: "insert"
   } }
])
First stage:第一阶段：

The $match stage finds the specific day's votes. $match阶段查找特定日期的投票。For example:例如：

{ "_id" : ObjectId("5ce6097c436eb7e1203064a6"), "date" : ISODate("2019-05-07T00:00:00Z"), "thumbsup" : 14, "thumbsdown" : 10 }
Second stage:第二阶段：

The $project stage sets the _id field to a year-month string. For example:$project阶段将_id字段设置为年-月字符串。例如：

{ "thumbsup" : 14, "thumbsdown" : 10, "_id" : "2019-05" }
Third stage:第三阶段：

The $merge stage writes the documents to the monthlytotals collection in the same database. $merge阶段将文档写入同一数据库中的monthlytotals集合。If the stage finds an existing document in the collection that matches on the _id field, the stage uses a pipeline to add the thumbsup votes and the thumbsdown votes.如果阶段在集合中找到与_id字段匹配的现有文档，则阶段将使用管道添加thumbsup投票和thumbsdown投票。

  • This pipeline cannot directly accesses the fields from the results document. 此管道无法直接访问结果文档中的字段。To access the thumbsup field and the thumbsdown field in the results document, the pipeline uses the $$new variable; i.e. $$new.thumbsup and $new.thumbsdown.要访问结果文档中的thumbsup字段和thumbsdown字段，管道使用$$new变量；即$$new.thumbsup和$new.thumpsdown。
  • This pipeline can directly accesses the thumbsup field and the thumbsdown field in the existing document in the collection; i.e. $thumbsup and $thumbsdown.该管道可以直接访问集合中现有文档中的thumbsup字段和thumbsdown字段；即$thumbsup和$thumpsdown。

The resulting document replaces the existing document.生成的文档将替换现有文档。

To view documents in the monthlytotals collection after the merge operation, run the following operation:要在合并操作后查看monthlytotals集合中的文档，请运行以下操作：

db.monthlytotals.find()

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

{ "_id" : "2019-05", "thumbsup" : 40, "thumbsdown" : 41 }

Use Variables to Customize the Merge使用变量自定义合并

You can use variables in the $merge stage whenMatched field. 您可以在$merge阶段whenMatched字段中使用变量。Variables must be defined before they can be used.变量必须先定义，然后才能使用。

Define variables in one or both of the following:在以下一项或两项中定义变量：

To use variables in whenMatched:要在whenMatched中使用变量：

Specify the double dollar sign ($$) prefix together with the variable name in the form $$<variable_name>. 以$$<variable_name>的形式指定双美元符号（$$）前缀和变量名。For example, $$year. 例如，$$year。If the variable is set to a document, you can also include a document field in the form $$<variable_name>.<field>. 如果变量设置为文档，则还可以以$$<variable_name>.<field>的形式包含文档字段。For example, $$year.month.例如，$$year.month。

The tabs below demonstrate behavior when variables are defined in the merge stage, the aggregate command, or both.下面的选项卡演示了在合并阶段、聚合命令或两者中定义变量时的行为。

Use Variables Defined in the Merge Stage使用合并阶段中定义的变量

You can define variables in the $merge stage let and use the variables in the whenMatched field.您可以在$merge阶段let中定义变量，并在whenMatched字段中使用变量。

Example:例子：

db.cakeSales.insertOne( [
   { _id: 1, flavor: "chocolate", salesTotal: 1580,
     salesTrend: "up" }
] )


db.runCommand( {
   aggregate: db.cakeSales.getName(),
   pipeline: [ {
      $merge: {
         into: db.cakeSales.getName(),
         let : { year: "2020" },
         whenMatched: [ {
            $addFields: { "salesYear": "$$year" }
         } ]
      }
   } ],
   cursor: {}
} )


db.cakeSales.find()

The example:该示例：

  • creates a collection named cakeSales创建名为cakeSales的集合

  • runs an aggregate command that defines a year variable in the $merge let and adds the year to cakeSales using whenMatched运行aggregate命令，该命令在$merge let中定义year变量，并使用whenMatched将年份添加到cakeSales

  • retrieves the cakeSales document检索cakeSales文档

Output:输出：

{ "_id" : 1, "flavor" : "chocolate", "salesTotal" : 1580,
  "salesTrend" : "up", "salesYear" : "2020" }

Use Variables Defined in the Aggregate Command使用聚合命令中定义的变量

New in version 5.0.

You can define variables in the aggregate command let and use the variables in the $merge stage whenMatched field.您可以在aggregate命令let中定义变量，并在$merge阶段whenMatched字段中使用变量。

Example:示例：

db.cakeSales.insertOne(
   { _id: 1, flavor: "chocolate", salesTotal: 1580,
     salesTrend: "up" }
)


db.runCommand( {
   aggregate: db.cakeSales.getName(),
      pipeline: [ {
         $merge: {
            into: db.cakeSales.getName(),
            whenMatched: [ {
               $addFields: { "salesYear": "$$year" } }
            ] }
         }
   ],
   cursor: {},
   let : { year: "2020" }
} )


db.cakeSales.find()

The example:该示例：

  • creates a collection named cakeSales创建名为cakeSales的集合

  • runs an aggregate command that defines a year variable in the aggregate command let and adds the year to cakeSales using whenMatched运行aggregate命令，该命令在aggregate命令let中定义year变量，并使用whenMatched将年份添加到cakeSales

  • retrieves the cakeSales document检索cakeSales文档

Output:输出：

{ "_id" : 1, "flavor" : "chocolate", "salesTotal" : 1580,
  "salesTrend" : "up", "salesYear" : "2020" }

Use Variables Defined in the Merge Stage and Aggregate Command使用合并阶段和聚合命令中定义的变量

You can define variables in the $merge stage and, starting in MongoDB 5.0, the aggregate command.您可以在$merge阶段定义变量，并从MongoDB 5.0开始定义aggregate命令。

If two variables with the same name are defined in the $merge stage and the aggregate command, the $merge stage variable is used.如果$merge阶段和aggregate命令中定义了两个同名的变量，则使用$merge阶段变量。

In this example, the year: "2020" $merge stage variable is used instead of the year: "2019" aggregate command variable:在此示例中，使用year: "2020" $merge阶段变量，而不是year: "2019"aggregate命令变量：

db.cakeSales.insertOne(
   { _id: 1, flavor: "chocolate", salesTotal: 1580,
     salesTrend: "up" }
)


db.runCommand( {
   aggregate: db.cakeSales.getName(),
      pipeline: [ {
         $merge: {
            into: db.cakeSales.getName(),
            let : { year: "2020" },
            whenMatched: [ {
               $addFields: { "salesYear": "$$year" }
            } ]
         }
      } ],
   cursor: {},
   let : { year: "2019" }
} )


db.cakeSales.find()

Output:

{
  _id: 1,
  flavor: 'chocolate',
  salesTotal: 1580,
  salesTrend: 'up',
  salesYear: '2020'
}
←  $match (aggregation)$out (aggregation) →