Description

A new section is required to describe the new $merge stage. With the new $merge stage the user can describe what to do in the various scenarios that can occur when trying to correlate documents with those in a collection. The syntax of the $merge stage is as follows:

{$merge: {
  into: "collection name" OR {db: "db name", coll: "collection name"},
  on: <optional, fields used to uniquely identify a document>,
  let: <optional, variables to be in scope for pipeline below>,
  whenMatched: "optional: merge|replace|keepExisting|fail|pipeline",
  whenNotMatched: "optional: insert|discard|fail"
}}

Two short cut syntaxes are also available:

{$merge: {into: "collection name"}} 
{$merge: "collection name"}

The semantics and the arguments of the $merge stage can be found in the Scope document.

Additionally, the existing $out section in 4.2 documentation will need to reverted to its 4.0 version to keep what we did in 4.0.

Engineering Ticket Description:

This stage will eventually replace the new modes of $out, but for now will be separate.

The syntax will be:

{$merge: {
  into: "collection name" OR {db: "db name", coll: "collection name"},
  on: <fields used to uniquely identify a document>,
  let: <optional, variables to be in scope for pipeline below>,
  whenMatched: "replace|keepExisting|fail|merge|pipeline",
  whenNotMatched: "insert|discard|fail"
}}

For this ticket, we will only support the combination of modes already supported by $out:
mode "insertDocuments":

{$merge: {
  into: "x",
  on: "x_id"
  whenMatched: "fail",
  whenNotMatched: "insert"
}}

mode "replaceDocuments":

{$merge: {
  into: "x",
  on: "x_id"
  whenMatched: "replaceWithNew",
  whenNotMatched: "insert"
}}

In future tickets we'll add support for other modes.

Scope of changes

• $merge – Waiting on remaining whenMatched SERVER tickets before preceding with examples.
• add redirect
• 4.2 release notes

Restrictions

• source/reference/operator/aggregation/facet.txt
• source/reference/operator/aggregation/lookup.txt
• linearizable rc
• transaction

Disambiguation

• createView
• views
• create/collMod

Impact to Other Docs

MVP (Work and Date)

Resources (Scope or Design Docs, Invision, etc.)