DOCS-14841 expose documents as stage

Author: mungitoperrito

source/reference/operator/aggregation-pipeline.txt

@@ -325,6 +325,7 @@ Alphabetical Listing of Stages
    /reference/operator/aggregation/collStats
    /reference/operator/aggregation/count
    /reference/operator/aggregation/currentOp
+   /reference/operator/aggregation/documents
    /reference/operator/aggregation/facet
    /reference/operator/aggregation/geoNear
    /reference/operator/aggregation/graphLookup

source/reference/operator/aggregation/documents.txt

@@ -0,0 +1,147 @@
+========================
+$documents (aggregation)
+========================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. pipeline:: $documents
+
+   .. versionchanged:: 5.1
+
+   Returns literal documents from input values.
+
+Syntax
+------
+
+The :pipeline:`$documents` stage has the following form:
+
+.. code-block::
+
+   { $documents: <expression> }
+
+Behavior
+--------
+
+:pipeline:`$documents` accepts any valid expression that resolves to an
+array of objects. This includes:
+
+- system variables, such as :variable:`$$NOW <NOW>` or
+  ``$$SEARCH_META``
+- :expression:`$let` expressions
+- variables in scope from :pipeline:`$lookup` expressions
+
+Expressions that do not resolve to a current document, like
+``$myField`` or :variable:`$$ROOT <ROOT>`, will result in an error.
+
+Examples
+--------
+
+Test a Pipeline Stage
+~~~~~~~~~~~~~~~~~~~~~
+
+Create testing and debugging data for a pipeline stage without creating
+test collections.
+
+.. code-block:: javascript
+   :emphasize-lines: 3
+
+   db.aggregate( 
+      [
+         { $documents: [ { x: 10 }, { x: 2 }, { x: 5 } ] }, 
+         { $bucketAuto: { groupBy: "$x", buckets: 4 } }
+      ]
+   )
+
+The :ref:`aggregation expression <aggregation-expressions>` does not
+specify a collection. It uses the input data in the highlighted
+:pipeline:`$documents` stage as input to the :pipeline:`$bucketAuto`
+stage.
+
+.. code-block:: javascript
+   :copyable: false
+
+   [
+     { _id: { min: 2, max: 5 }, count: 1 },
+     { _id: { min: 5, max: 10 }, count: 1 },
+     { _id: { min: 10, max: 10 }, count: 1 }
+   ]
+
+Use :pipeline:`$documents` with :pipeline:`$lookup`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Correlate documents in a collection with other data using
+:pipeline:`$documents` to modify :pipeline:`$lookup` output.
+
+Create the ``locations`` collection.
+
+.. code-block:: javascript
+
+   db.locations.insertMany(
+      [
+         { zip: 94301, name: "Palo Alto" },
+         { zip: 10019, name: "New York" }
+      ]
+    )
+
+Use :pipeline:`$documents` as a data source to transform the documents.
+
+.. code-block:: javascript
+
+   db.locations.aggregate(
+      [
+         { $match: {} },
+         { $lookup:
+            {
+               localField: "zip",
+               foreignField: "zip_id", 
+               as: "city_state",
+               pipeline:
+                 [ 
+                    { $documents:
+                       [
+                          { zip_id: 94301, name: "Palo Alto, CA" },
+                          { zip_id: 10019, name: "New York, NY" }
+                       ]
+                    }
+                 ]
+            }
+         }
+      ]
+    )
+
+The output correlates the data in the ``locations`` collection with the
+values in the :pipeline:`$documents` pipeline stage.
+
+.. code-block:: javascript
+   :copyable: false
+
+   [
+      {
+         _id: ObjectId("618949d60f7bfd5f5689490d"),
+         zip: 94301,
+         name: 'Palo Alto',
+         city_state: [ { zip_id: 94301, name: 'Palo Alto, CA' } ]
+      },
+      {
+         _id: ObjectId("618949d60f7bfd5f5689490e"),
+         zip: 10019,
+         name: 'New York',
+         city_state: [ { zip_id: 10019, name: 'New York, NY' } ]
+      }
+   ]
+
+- The ``zip`` field corresponds to the ``zip_id`` field
+- The ``as`` parameter creates a new output field
+
+For details on subqueries using this :pipeline:`$lookup` syntax, see
+:ref:`lookup-syntax-concise-correlated-subquery`.
+

source/release-notes/5.1.txt

@@ -31,6 +31,20 @@ $lookup and $graphLookup with sharded collections
 
 .. include:: /includes/5.1-fact-sharded-lookup-graphlookup.rst
 
+New Aggregation Stages
+~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.1 introduces the following aggregation stages:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Stage
+     - Description
+   * - :pipeline:`$documents`
+     - Returns literal documents from input expressions.
+
 New Aggregation Operators
 ~~~~~~~~~~~~~~~~~~~~~~~~~