[DOCS-12028] New syntax for $out aggregation stage Created: 05/Sep/18  Updated: 13/Nov/23  Resolved: 28/Sep/18

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

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

Issue Links:
Related
is related to DOCS-11892 Docs for SERVER-35893: Update $out to... Closed
is related to DOCS-11943 Docs for SERVER-36286: Rename options... Closed
is related to DOCS-11948 Docs for SERVER-35896: Support "repla... Closed
is related to DOCS-11961 SERVER-36123: Reject $out with mode: ... Closed
is related to DOCS-12015 Docs for SERVER-36424: Make sure $out... Closed
is related to DOCS-12017 Docs for SERVER-36100: Allow missing ... Closed
is related to DOCS-12018 Docs for SERVER-35954: Build uniqueKe... Closed
is related to DOCS-12024 Docs for SERVER-18027: Support aggreg... Closed
is related to DOCS-12025 Docs for SERVER-13201: Allow new Aggr... Closed
is related to DOCS-12052 Docs for SERVER-36367: Add validation... Closed
Participants:
Days since reply: 4 years, 36 weeks, 6 days ago
Epic Link: DOCS: 4.2 Server/Tools
Story Points: 2

 Description   

Description

Document the updated syntax for the $out aggregation stage. The specific syntax has changed between 4.1.1 and 4.1.2, with additional functionality added in 4.1.3. Some functionality may have been backported to 4.0.x. Check the corresponding server ticket for each $out related change to look for any backport work done.

The current syntax for $out is: 

{ $out : <collection name> }

 

Based on the technical design in WRITING-1983 and the updates in SERVER-36286 (4.1.2) ( based on this code chunk ), the updated syntax for $out should be:

{
  $out: {
    to : <string collection name>,
    mode : "insertDocuments" | "replaceDocuments" | "replaceCollection",
    db : "<destination database, if different from current db>",
    uniqueKey: { optional document of fields that identifies a document for replacement or merge }
  }
}

 

WRITING-1983 contains significant amounts of behavioral descriptions that should be taken into account when updating the current $out page. Take special care when documenting the behavior of uniqueKey.

As of SERVER-36123, $out does not support outputting to a sharded collection if  mode : "replaceCollection

As of SERVER-18027, $out does support outputting to a sharded collection if mode : "insertDocuments|replaceDocuments"

SERVER-35954, SERVER-36100, SERVER-36424: describes the behavior of the optional uniqueKey field for sharded collections

Other tickets may come through related to additional behavior of $out. There's some confusion over exactly what versions behavior has been ported to. Focus on what is going into 4.2, but make note of any features (e.g. SERVER-36123) that have been marked with a 4.0.x fix version. Confirm with the engineers what features specifically will/have been backported, if any.

See https://jira.mongodb.org/browse/PM-828 for a complete list of all tickets related to $out
 

Scope of changes

    • You can find the source file in source/reference/operator/aggregation/out.txt
  • Use https://docs.mongodb.com/manual/reference/operator/aggregation/lookup/ as a model to work off of
    • You can find the source file in source/reference/operator/aggregation/lookup.txt. Take note of how we use .. include:: directive and the files it points to, how they are structured, etc. 


 Comments   
Comment by Githook User [ 30/May/19 ]

Author:

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

Message: Revert "DOCS-12028 document new syntax for $out aggregation stage"

This reverts commit 0a8ca61e1bc449615d667f6f5b13b3dba5f48801.
Branch: master
https://github.com/mongodb/docs/commit/31e59696e03e123df8909554308bdc237cefb596

Comment by Githook User [ 09/Oct/18 ]

Author:

{'name': 'Isabella Siu', 'email': 'isabellasiu@Isabellas-MacBook.local'}

Message: DOCS-12028 document new syntax for $out aggregation stage
Branch: master
https://github.com/mongodb/docs/commit/0a8ca61e1bc449615d667f6f5b13b3dba5f48801

Comment by Githook User [ 28/Sep/18 ]

Author:

{'name': 'Isabella Siu', 'email': 'isabellasiu@Isabellas-MacBook.local'}

Message: DOCS-12028 document new syntax for $out aggregation stage
Branch: upcoming-4.2
https://github.com/mongodb/docs/commit/d94af40db08e7514f1753c7f5471daa60a0b37e8

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