[DOCS-12675] Docs for SERVER-40429: Add $merge stage to write output to existing collection Created: 03/May/19  Updated: 13/Nov/23  Resolved: 01/Jun/19

Status: Closed
Project: Documentation
Component/s: manual, Server
Affects Version/s: None
Fix Version/s: 4.1.11, Server_Docs_20231030, Server_Docs_20231106, Server_Docs_20231105, Server_Docs_20231113

Type: Task Priority: Major - P3
Reporter: Kay Kim (Inactive) Assignee: Kay Kim (Inactive)
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Documented
documents SERVER-40429 Add $merge stage to write output to e... Closed
documents SERVER-40430 Add $merge support for whenMatched: '... Closed
documents SERVER-40431 Add $merge support for whenMatched: p... Closed
documents SERVER-40440 Add $merge support for whenMatched: '... Closed
Duplicate
is duplicated by DOCS-12674 Docs for SERVER-40430: Add $merge sup... Closed
is duplicated by DOCS-12687 Docs for SERVER-40440: Add $merge sup... Closed
Related
related to DOCS-12671 Docs for SERVER-40397: Add the abilit... Closed
related to DOCS-12541 4.2: On-Demand Materialized Views Closed
Participants:
Days since reply: 4 years, 36 weeks ago
Epic Link: DOCS: 4.2 Server/Tools

 Description   

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.)



 Comments   
Comment by Githook User [ 05/Jun/19 ]

Author:

{'name': 'Kay Kim', 'email': 'kay.kim@10gen.com', 'username': 'kay-kim'}

Message: DOCS-12675: tweak merge
Branch: master
https://github.com/mongodb/docs/commit/7a804d3b2afbc2ad935a26139a21a7477265db79

Comment by Githook User [ 04/Jun/19 ]

Author:

{'name': 'Kay Kim', 'email': 'kay.kim@10gen.com', 'username': 'kay-kim'}

Message: DOCS-12675: 4.2 $merge cleanup
Branch: master
https://github.com/mongodb/docs/commit/97939112d0e490f60b973d3b434057e35ddf86ea

Comment by Githook User [ 03/Jun/19 ]

Author:

{'name': 'Kay Kim', 'email': 'kay.kim@10gen.com', 'username': 'kay-kim'}

Message: DOCS-12675: mention $merge restriction in capped collections page
Branch: master
https://github.com/mongodb/docs/commit/c695d92e8576a4752c416421dc5bc399d9453c51

Comment by Githook User [ 30/May/19 ]

Author:

{'email': 'kay.kim@10gen.com', 'name': 'Kay Kim', 'username': 'kay-kim'}

Message: DOCS-12675,DOCS-12541: 4.2 $merge stage and materialized views
Branch: master
https://github.com/mongodb/docs/commit/4723f80fb491e8b0c3b043011f37aca6a9af26ad

Generated at Thu Feb 08 08:05:50 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.