(DOCSP-19941): Support pushdown of to SBE (#229)

* (DOCSP-19941): Support pushdown of group to SBE

* Updates per copy review

* updates per external review

* reformat

* add clarification for allowDiskUse

* technical tweaks

* word tweak

Author: jeff-allen-mongo

snooty.toml

@@ -190,13 +190,16 @@ toc_landing_pages = [
 ]
 
 [substitutions]
+bi = "MongoDB Connector for BI"
 compass = "MongoDB Compass"
-mdb-shell = "MongoDB Shell"
 copy = "©"
 ent-build = "MongoDB Enterprise"
-year = "2021"
-bi = "MongoDB Connector for BI"
+mdb-shell = "MongoDB Shell"
+sbe = "slot-based query execution engine"
+sbe-short = "slot-based engine"
+sbe-title = "Slot-Based Query Execution Engine"
 version = "{+version+}"
+year = "2022"
 
 
 [constants]

source/core/aggregation-pipeline-optimization.txt

@@ -112,6 +112,7 @@ use any values computed in either the :pipeline:`$project` or
 :pipeline:`$match` stage before both of the projection stages.
 
 .. note::
+
    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
@@ -383,6 +384,25 @@ option, the ``explain`` output shows the coalesced stage:
      }
    }
 
+.. _agg-group-optimization-sbe:
+
+``$group`` Optimization 
+-----------------------
+
+.. versionadded:: 5.2
+
+.. include:: /includes/fact-sbe-group-overview.rst
+
+To verify that the |sbe-short| is used, run the aggregation with the
+``.explain()`` option. This option outputs information on the
+aggregation's query plan.
+
+When the |sbe| is used for :pipeline:`$group`, the :ref:`explain results
+<explain-results>` include:
+
+- ``explain.explainVersion: '2'``
+- ``explain.queryPlanner.winningPlan.queryPlan.stage: "GROUP"``
+
 Example
 -------
 .. _agg-sort-skip-limit-sequence:

source/includes/fact-sbe-group-overview.rst

@@ -0,0 +1,14 @@
+Starting in MongoDB 5.2, MongoDB uses the
+:ref:`slot-based execution query engine <5.1-rel-notes-sbe>` to execute
+:pipeline:`$group` stages when :pipeline:`$group` is either:
+
+- The first stage in the pipeline.
+
+- Part of a series of stages executed by the |sbe-short| that
+  occurs at the beginning of the pipeline. For example, if a pipeline
+  begins with :pipeline:`$match` followed by :pipeline:`$group`, the
+  :pipeline:`$match` and :pipeline:`$group` stages are executed by the
+  |sbe-short|.
+  
+In most cases, the |sbe-short| provides improved performance and lower
+CPU and memory costs compared to the classic query engine.

source/reference/command/aggregate.txt

@@ -103,9 +103,11 @@ arguments:
 
      - boolean
 
-     - Optional. Enables writing to temporary files. When set to ``true``, aggregation
-       stages can write data to the :file:`_tmp` subdirectory in the
-       :setting:`~storage.dbPath` directory.
+     - Optional. Enables writing to temporary files. When set to
+       ``true``, aggregation stages can write data to the :file:`_tmp`
+       subdirectory in the :setting:`~storage.dbPath` directory.
+
+       By default, ``allowDiskUse`` is ``false``.
 
        .. include:: /includes/extracts/4.2-changes-usedDisk.rst
 

source/reference/explain-results.txt

@@ -51,20 +51,22 @@ The ``explain`` results present the query plans as a tree of stages.
       }
    },
 
-Each stage passes its results (i.e. documents or index keys) to the
+Each stage passes its resulting documents or index keys to the
 parent node. The leaf nodes access the collection or the indices. The
 internal nodes manipulate the documents or the index keys that result
 from the child nodes. The root node is the final stage from which
 MongoDB derives the result set.
 
-Stages are descriptive of the operation; e.g.
+Stages are descriptive of the operation. For example:
 
 - ``COLLSCAN`` for a collection scan
 
 - ``IXSCAN`` for scanning index keys
 
 - ``FETCH`` for retrieving documents
 
+- ``GROUP`` for grouping douments with :pipeline:`$group`
+
 - ``SHARD_MERGE`` for merging results from shards
 
 - ``SHARDING_FILTER`` for filtering out orphan documents from shards
@@ -207,6 +209,11 @@ This section shows the ``explain`` output for MongoDB 5.1 and later.
       instance, an ``IXSCAN`` stage will include the index bounds
       along with other data specific to the index scan.
 
+      Starting in MongoDB 5.2, MongoDB can execute :pipeline:`$group`
+      stages using the :ref:`slot-based execution query engine
+      <5.1-rel-notes-sbe>`. When the |sbe-short| is used for
+      :pipeline:`$group`, this field value is ``GROUP``.
+
    .. data:: explain.queryPlanner.winningPlan.queryPlan.planNodeId
 
       Unique integer field that identifies each stage in the execution
@@ -217,7 +224,7 @@ This section shows the ``explain`` output for MongoDB 5.1 and later.
 
 .. data:: explain.queryPlanner.winningPlan.slotBasedPlan
 
-   Document with information about the slot based query execution  plan
+   Document with information about the slot based query execution plan
    tree and stages.
 
    .. versionadded:: 5.1

source/reference/operator/aggregation/group.txt

@@ -89,8 +89,15 @@ aggregation pipeline stages to write data to temporary files.
 
 .. _group-pipeline-optimization:
 
+``$group`` Performance Optimizations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes optimizations to improve the performance of
+:pipeline:`$group`. There are optimizations that you can make manually
+and optimizations MongoDB makes internally.
+
 Optimization to Return the First Document of Each Group
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+```````````````````````````````````````````````````````
 
 If a pipeline :pipeline:`sorts <$sort>` and :pipeline:`groups <$group>`
 by the same field and the :pipeline:`$group` stage only uses the
@@ -119,6 +126,14 @@ the first document of each group.
         }
       ])
 
+|sbe-title|
+```````````
+
+.. include:: /includes/fact-sbe-group-overview.rst
+
+See :ref:`agg-group-optimization-sbe`.
+
+
 Examples
 --------
 

source/release-notes/5.2.txt

@@ -100,6 +100,13 @@ Starting in MongoDB 5.2, you can convert timestamps to dates using the
 :expression:`$convert` operator. The :expression:`$toDate` operator can 
 also convert timestamps.
 
+|sbe-title| Can Execute :pipeline:`$group` Stages
+`````````````````````````````````````````````````
+
+.. include:: /includes/fact-sbe-group-overview.rst
+
+See :ref:`agg-group-optimization-sbe`.
+
 .. _5.2-rel-notes-sharding:
 
 Sharding