DOCS-12330: $out and $limit restrictions

Author: Kay Kim

source/reference/operator/aggregation/lookup.txt

@@ -179,6 +179,8 @@ The :pipeline:`$lookup` takes a document with the following fields:
        collection. To return all documents, specify an empty pipeline
        ``[]``.
 
+       The ``pipeline`` cannot include the :pipeline:`$out` stage.
+
        The ``pipeline`` cannot directly access the input document
        fields. Instead, first define the variables for the input
        document fields, and then reference the variables in the stages
@@ -224,6 +226,30 @@ Views and Collation
 
 .. include:: /includes/extracts/views-collation-agg.rst
 
+Restrictions
+~~~~~~~~~~~~~
+
+- .. versionchanged:: 4.2
+
+   You cannot include the :pipeline:`$out` stage in the
+   :pipeline:`$lookup` stage. That is, when specifying a :ref:`pipeline
+   for the joined collection <lookup-syntax-let-pipeline>`,
+   you cannot include the :pipeline:`$out` stage in the ``pipeline``
+   field.
+
+  .. code-block:: javascript
+     :emphasize-lines: 6
+
+     {
+       $lookup:
+         {
+            from: <collection to join>,
+            let: { <var_1>: <expression>, …, <var_n>: <expression> },
+            pipeline: [ <pipeline to execute on the joined collection> ],  // Cannot include $out
+            as: <output array field>
+         }
+     }
+   
 Examples
 --------
 

source/reference/operator/aggregation/out.txt

@@ -311,8 +311,15 @@ The :pipeline:`$out` stage is not allowed as part of a :doc:`view
 definition </core/views>`. If the view definition includes nested
 pipeline (e.g. the view definition includes :pipeline:`$lookup` or
 :pipeline:`$facet` stage), this :pipeline:`$out` stage restriction
-applies to the nested pipelines as well.
+applies to the nested pipelines as well. [#lookup]_
 
+.. [#lookup]
+
+   Starting in 4.2, you cannot include the :pipeline:`$out` stage in
+   the :pipeline:`$lookup` stage's :ref:`nested pipeline
+   <lookup-syntax-let-pipeline>`, regardless of whether the
+   :pipeline:`$lookup` is part of a view definition.
+   
 ``linearizable`` Read Concern
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/release-notes/4.2-compatibility.txt

@@ -253,6 +253,10 @@ Aggregation
   <collMod>` with a new pipeline that does not contain the
   :pipeline:`$out` stage.
 
+- The :pipeline:`$lookup` stage cannot include the :pipeline:`$out`
+  stage in its nested :ref:`pipeline field for the joined collection
+  <lookup-syntax-let-pipeline>`.
+
 - The :pipeline:`$out` stage cannot be used in conjunction with read
   concern :readconcern:`"linearizable"`.