New syntax for $out aggregation stage

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

• Update https://docs.mongodb.com/manual/reference/operator/aggregation/out/index.html

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