(v5.0) DOCSP-27261 Add guidance for $project stage placement (#2322) (#2563)

* first draft

* edits

* review feedback

* wording

* add link to project page

* typo fix

* add clarity

* wording

* wording

* add advice to project page

Author: jeff-allen-mongo

source/core/aggregation-pipeline-optimization.txt

@@ -37,6 +37,13 @@ the fields in the documents to obtain the results. If so, the pipeline
 will only use those required fields, reducing the amount of data
 passing through the pipeline.
 
+``$project`` Stage Placement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. |$project| replace:: :pipeline:`$project`
+
+.. include:: /includes/aggregation/fact-project-stage-placement.rst
+
 .. _aggregation-pipeline-sequence-optimization:
 
 Pipeline Sequence Optimization

source/includes/aggregation/fact-project-stage-placement.rst

@@ -0,0 +1,7 @@
+When you use a |$project| stage it should typically be the last stage in
+your pipeline, used to specify which fields to return to the client.
+
+Using a ``$project`` stage at the beginning or middle of a pipeline to
+reduce the number of fields passed to subsequent pipeline stages is
+unlikely to improve performance, as the database performs this
+optimization automatically.

source/reference/operator/aggregation/project.txt

@@ -205,6 +205,13 @@ fails with the same error:
 
    { $project: { "contact.address.country": 1, contact: 1 } }
 
+``$project`` Stage Placement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. |$project| replace:: ``$project``
+
+.. include:: /includes/aggregation/fact-project-stage-placement.rst
+
 Restrictions
 ~~~~~~~~~~~~