mongodb
diff --git a/‎source/aggregation.txt‎
Lines changed: 42 additions & 48 deletions b/‎source/aggregation.txt‎
Lines changed: 42 additions & 48 deletions
diff --git a/‎source/core/aggregation-pipeline-optimization.txt‎
Lines changed: 77 additions & 6 deletions b/‎source/core/aggregation-pipeline-optimization.txt‎
Lines changed: 77 additions & 6 deletions
@@ -21,12 +21,16 @@ results. You can use aggregation operations to:
 
 To perform aggregation operations, you can use:
 
-- :ref:`Aggregation pipelines <aggregation-framework>`
+- :ref:`Aggregation pipelines <aggregation-framework>`, which are the
+  preferred method for performing aggregations.
 
 - :ref:`Single purpose aggregation methods
-  <single-purpose-agg-operations>`
+  <single-purpose-agg-methods>`, which are simple but lack the
+  capabilities of an aggregation pipeline.
 
-- :ref:`Map-reduce functions <aggregation-map-reduce>`
+- :ref:`Map-reduce operations <aggregation-map-reduce>`, which are
+  deprecated starting in MongoDB 5.0. Instead, use an aggregation
+  pipeline.
 
 .. _aggregation-framework:
 
@@ -40,50 +44,39 @@ Aggregation Pipeline Example
 
 .. include:: /includes/aggregation-pipeline-example.rst
 
-For a runnable example, see :ref:`Complete Aggregation Pipeline
-Example <aggregation-pipeline-example>`.
+For runnable examples containing sample input documents, see
+:ref:`Complete Aggregation Pipeline Examples
+<aggregation-pipeline-examples>`.
 
-Aggregation Pipeline Stages and Operations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _single-purpose-agg-methods:
 
-The most basic pipeline stages provide *filters* that operate like
-queries and *document transformations* that modify the form
-of the output document.
+Single Purpose Aggregation Methods
+----------------------------------
 
-Other pipeline operations provide tools for grouping and sorting
-documents by specific field or fields as well as tools for aggregating
-the contents of arrays, including arrays of documents. In addition,
-pipeline stages can use :ref:`operators
-<aggregation-expression-operators>` for tasks such as calculating the
-average or concatenating a string.
+You can use the following single purpose aggregation methods to
+aggregate documents from a single collection:
 
-The pipeline provides efficient data aggregation using native
-operations within MongoDB, and is the preferred method for data
-aggregation in MongoDB.
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+   
+   * - Method
+     - Description
 
-The aggregation pipeline can operate on a
-:doc:`sharded collection </sharding>`.
+   * - :method:`db.collection.estimatedDocumentCount()`
+     - Returns an approximate count of the documents in a collection or
+       a view.
 
-The aggregation pipeline can use indexes to improve its performance
-during some of its stages. In addition, the aggregation pipeline has an
-internal optimization phase. See
-:ref:`aggregation-pipeline-operators-and-performance` and
-:doc:`/core/aggregation-pipeline-optimization` for details.
+   * - :method:`db.collection.count()`
+     - Returns a count of the number of documents in a collection or a
+       view.
 
-.. _single-purpose-agg-operations:
+   * - :method:`db.collection.distinct()`
+     - Returns an array of documents that have distinct values for the
+       specified field.
 
-Single Purpose Aggregation Operations
--------------------------------------
-
-MongoDB also provides :method:`db.collection.estimatedDocumentCount()`,
-:method:`db.collection.count()` and :method:`db.collection.distinct()`.
-
-All of these operations aggregate documents from a single collection.
-While these operations provide simple access to common aggregation
-processes, they lack the flexibility and capabilities of an aggregation
-pipeline.
-
-.. include:: /images/distinct.rst
+The single purpose aggregation methods are simple but lack the
+capabilities of an :ref:`aggregation pipeline <aggregation-framework>`.
 
 .. _aggregation-map-reduce:
 
@@ -92,21 +85,22 @@ Map-Reduce
 
 .. include:: /includes/fact-use-aggregation-not-map-reduce.rst
 
-Additional Features and Behaviors
----------------------------------
-
-For a feature comparison of the aggregation pipeline,
-map-reduce, and the special group functionality, see
+For a feature comparison of aggregation pipelines and map-reduce, see
 :doc:`/reference/aggregation-commands-comparison`.
 
 Learn More
 ----------
 
-Practical MongoDB Aggregations E-Book
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To learn more about aggregations, see:
+
+- :ref:`aggregation-pipeline`
+
+- :ref:`aggregation-expression-operators`
+
+- :ref:`aggregation-pipeline-operator-reference`
 
-For more information on aggregations, read the `Practical MongoDB
-Aggregations <https://www.practical-mongodb-aggregations.com>`__ e-book.
+- `Practical MongoDB Aggregations
+  <https://www.practical-mongodb-aggregations.com>`_
 
 
 .. toctree::
 
@@ -19,6 +19,12 @@ include the :method:`explain <db.collection.aggregate()>` option in the
 
 .. include:: /includes/fact-optimizations-subject-to-change.rst
 
+In addition to learning about the aggregation pipeline optimizations
+performed during the optimization phase, you will also see how to
+improve aggregation pipeline performance using indexes and document
+filters. See
+:ref:`aggregation-pipeline-optimization-indexes-and-filters`.
+
 .. _aggregation-pipeline-projection-optimization:
 
 Projection Optimization
@@ -113,11 +119,11 @@ use any values computed in either the :pipeline:`$project` or
 
 .. note::
 
-   After optimization, the filter ``{ name: "Joe Schmoe" }`` is in
-   a :pipeline:`$match` stage at the beginning of the pipeline. This has
+   After optimization, the filter ``{ name: "Joe Schmoe" }`` is in a
+   :pipeline:`$match` stage at the beginning of the pipeline. This has
    the added benefit of allowing the aggregation to use an index on the
-   ``name`` field when initially querying the collection.
-   See :ref:`aggregation-pipeline-operators-and-performance` for more
+   ``name`` field when initially querying the collection. See
+   :ref:`aggregation-pipeline-optimization-indexes-and-filters` for more
    information.
 
 .. _agg-sort-match-optimization:
@@ -152,8 +158,9 @@ can sometimes add a portion of the :pipeline:`$match` stage before the
 :pipeline:`$redact` stage. If the added :pipeline:`$match` stage is at
 the start of a pipeline, the aggregation can use an index as well as
 query the collection to limit the number of documents that enter the
-pipeline. See :ref:`aggregation-pipeline-operators-and-performance` for
-more information.
+pipeline. See
+:ref:`aggregation-pipeline-optimization-indexes-and-filters` for more
+information.
 
 For example, if the pipeline consists of the following stages:
 
@@ -403,6 +410,70 @@ When the |sbe| is used for :pipeline:`$group`, the :ref:`explain results
 - ``explain.explainVersion: '2'``
 - ``explain.queryPlanner.winningPlan.queryPlan.stage: "GROUP"``
 
+.. _aggregation-pipeline-optimization-indexes-and-filters:
+
+Improve Performance with Indexes and Document Filters
+-----------------------------------------------------
+
+The following sections show how you can improve aggregation performance
+using indexes and document filters.
+
+Indexes
+~~~~~~~
+
+The :ref:`query planner <query-plans-query-optimization>` analyzes
+an aggregation pipeline to determine if :ref:`indexes <indexes>`
+can be used to improve pipeline performance.
+
+The following list shows some pipeline stages that can use indexes:
+
+``$match`` stage
+  :pipeline:`$match` can use an index to filter documents if
+  :pipeline:`$match` is the first stage in a pipeline.
+
+``$sort`` stage
+  :pipeline:`$sort` can use an index if :pipeline:`$sort` is not
+  preceded by a :pipeline:`$project`, :pipeline:`$unwind`, or
+  :pipeline:`$group` stage.
+
+``$group`` stage
+  :pipeline:`$group` can potentially use an index to find the first
+  document in each group if:
+  
+  - :pipeline:`$group` is preceded by :pipeline:`$sort` that sorts the
+    field to group by, and
+
+  - there is an index on the grouped field that matches the sort order,
+    and
+
+  - :group:`$first` is the only accumulator in :pipeline:`$group`.
+
+  See :ref:`group-pipeline-optimization` for an example.
+
+``$geoNear`` stage
+  :pipeline:`$geoNear` can use a geospatial index. :pipeline:`$geoNear`
+  must be the first stage in an aggregation pipeline.
+
+Indexes can :ref:`cover <read-operations-covered-query>` queries in an
+aggregation pipeline. A covered query uses an index to return all of the
+documents and has high performance.
+
+Document Filters
+~~~~~~~~~~~~~~~~
+
+If your aggregation operation requires only a subset of the documents in
+a collection, filter the documents first:
+
+- Use the :pipeline:`$match`, :pipeline:`$limit`, and :pipeline:`$skip`
+  stages to restrict the documents that enter the pipeline.
+  
+- When possible, put :pipeline:`$match` at the beginning of the pipeline
+  to use indexes that scan the matching documents in a collection.
+
+- :pipeline:`$match` followed by :pipeline:`$sort` at the start of the
+  pipeline is equivalent to a single query with a sort, and can use an
+  index.
+
 Example
 -------
 .. _agg-sort-skip-limit-sequence: