DOCSP 32572 - adding performance and considerations to $lookup (#4771) (#5005)

* DOCSP-32572 adding performance and considerations to lookup

* DOCSP-32572 adding performance and considerations to lookup

* DOCSP-32572 formatting errors

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 performance and considerations for lookup

* DOCSP-32572 fixing bullet spacing

* DOCSP-32572 adding general strategies

* DOCSP-32572 fixing spacing

* DOCSP-32572 adding embedded data modeling reference

* DOCSP-32572 adding embedded data modeling reference

* DOCSP-32572 copy edits from Jeff

* DOCSP-32572 copy edits from Jeff

* DOCSP-32572 copy edits from Jeff

* DOCSP-32572 copy edits from Jeff

* DOCSP-32572 copy edits round 2

* DOCSP-32572 copy edits round 2

* DOCSP-32572 copy edits round 2

* DOCSP-32572 copy edits round 2

* DOCSP-32572 copy edits round 2

* DOCSP-32572 copy edits round 2

* DOCSP-32572 tech edit

* DOCSP-32572 fixing line

* DOCSP-32572 fixing line

* DOCSP-32572 tech edit

Author: ltran-mdb2

source/core/data-modeling-introduction.txt

@@ -60,6 +60,8 @@ revolves around the structure of documents and how the application
 represents relationships between data. MongoDB allows related data to
 be embedded within a single document.
 
+.. _embedded-data-modeling:
+
 Embedded Data
 ~~~~~~~~~~~~~
 

source/reference/operator/aggregation/lookup.txt

@@ -42,6 +42,8 @@ Syntax
 
 The :pipeline:`$lookup` stage has the following syntaxes:
 
+.. _lookup-single-equality:
+
 Equality Match with a Single Join Condition
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -129,7 +131,7 @@ The operation would correspond to the following pseudo-SQL statement:
 
 See these examples:
 
-- :ref:`lookup-single-equality`
+- :ref:`lookup-single-equality-example`
 - :ref:`unwind-example`
 - :ref:`lookup-mergeObjects`
 
@@ -506,10 +508,93 @@ in the ``from`` parameter of :pipeline:`$lookup` stages.
 
 For more information, see :ref:`agg-lookup-optimization-sbe`.
 
+.. _lookup-performance-considerations:
+
+Performance Considerations 
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``$lookup`` performance depends on the type of operation performed.
+Refer to the following table for performance considerations for
+different ``$lookup`` operations. 
+
+.. list-table::
+   :header-rows: 1 
+   :widths: 20 80
+
+   * - ``$lookup`` Operation
+     - Performance Considerations
+
+   * - :ref:`Equality Match with a Single Join
+       <lookup-single-equality-example>`
+
+     - .. _equality-match-performance:
+
+       - ``$lookup`` operations that perform equality matches with a
+         single join typically perform better when the source collection
+         contains an index on the ``foreignField``.
+
+   * - :ref:`Uncorrelated Subqueries<lookup-uncorrelated-subquery>`
+
+     - .. _uncorrelated-subqueries-performance: 
+
+       - ``$lookup`` operations that contain uncorrelated subqueries
+         typically perform better when the inner pipeline can reference
+         an index on the ``foreignField``. 
+
+       - MongoDB only needs to run the ``$lookup`` subquery once before
+         caching the query because there is no relationship between the
+         source and foreign collections. The ``$lookup`` subquery is not
+         based on any value in the source collection. This behavior
+         improves performance for subsequent executions of this query.
+
+
+   * - :ref:`Correlated Subqueries <lookup-concise-correlated-subquery>`
+
+     - .. _correlated-subqueries-performance: 
+
+       - ``$lookup`` operations that contain correlated subqueries
+         typically perform better when the following conditions apply:
+
+         - The source collection contains an index on the
+           ``localField``.
+         
+         - The foreign collection contains an index on the
+           ``foreignField``.
+
+         - The foreign collection contains an index that references the
+           inner pipline. 
+ 
+       - If your pipeline passes a large number of documents to the
+         ``$lookup`` query, the following strategies may improve
+         performance:
+
+         - Reduce the number of documents that MongoDB passes to the 
+           ``$lookup`` query. For example, set a stricter filter
+           during the ``$match`` stage. 
+
+         - Run the inner pipeline of the ``$lookup`` subquery as a
+           separate query and use ``$out`` to create a temporary
+           collection. Then, run an :ref:`equality match with a single
+           join <lookup-single-equality>`. 
+
+         - Reconsider the data's schema to ensure it is optimal for the
+           use case. 
+
+For general performance strategies, see :ref:`Indexing Strategies
+<manual-indexing-strategies>` and :ref:`Query Optimization
+<read-operations-indexing>`. 
+
+.. important::
+
+   Excessive use of ``$lookup`` within a query may slow down
+   performance. To avoid multiple ``$lookup`` stages, consider an
+   :ref:`embedded data model <embedded-data-modeling>` to optimize query
+   performance. 
+
 Examples
 --------
 
-.. _lookup-single-equality:
+.. _lookup-single-equality-example:
 
 Perform a Single Equality Join with ``$lookup``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -599,6 +684,9 @@ The operation corresponds to this pseudo-SQL statement:
       WHERE sku = orders.item
    );
 
+For more information, see
+:ref:`Equality Match Performance Considerations<equality-match-performance>`. 
+
 .. _unwind-example:
 
 Use ``$lookup`` with an Array
@@ -972,6 +1060,9 @@ The operation corresponds to this pseudo-SQL statement:
       WHERE year = 2018
    );
 
+For more information, see
+:ref:`Uncorrelated Subquery Performance Considerations <uncorrelated-subqueries-performance>`.
+
 .. _lookup-concise-correlated-subquery:
 
 Perform a Concise Correlated Subquery with ``$lookup``
@@ -1136,3 +1227,6 @@ The previous examples correspond to this pseudo-SQL statement:
       WHERE restaurants.name = orders.restaurant_name
       AND restaurants.beverages = orders.drink
    );
+
+For more information, see
+:ref:`Correlated Subquery Performance Considerations <correlated-subqueries-performance>`.