DOCS-14249 documents new count accumulator

Author: jmd-mongo

source/includes/extracts-agg-operators.yaml

@@ -950,6 +950,11 @@ content: |
 
         - Returns an average of numerical values. Ignores non-numeric values.
 
+      * - :group:`$count`
+
+        - Returns the count of the documents in the stage. May be used in
+          place of ``{ $sum : 1 }``.
+
       * - :group:`$first`
 
         - Returns a value from the first document for each group. Order

source/reference/operator/aggregation.txt

@@ -1018,6 +1018,7 @@ Alphabetical Listing of Expression Operators
    /reference/operator/aggregation/convert
    /reference/operator/aggregation/cos
    /reference/operator/aggregation/cosh
+   /reference/operator/aggregation/count-accum
    /reference/operator/aggregation/dateAdd
    /reference/operator/aggregation/dateDiff
    /reference/operator/aggregation/dateFromParts

source/reference/operator/aggregation/count-accum.txt

@@ -0,0 +1,89 @@
+================================
+$count (aggregation accumulator)
+================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. group:: $count
+   
+   .. versionadded:: 5.0
+
+   Returns the count of the documents in the stage.
+   
+   .. note:: Disambiguation
+
+      The following page describes the accumulator :group:`$count`,
+      available only within the :pipeline:`$group` stage. For the 
+      aggregation pipeline stage, see 
+      :pipeline:`$count (aggregation stage) <$count>`.
+
+Syntax
+------
+
+:group:`$count` takes no arguments. :group:`$count` has the following 
+syntax:
+
+.. code-block:: javascript
+
+   { $count: { } }
+
+Behavior
+--------
+
+:group:`$count` is functionally equivalent to using ``{ $sum : 1 }`` 
+within the :pipeline:`$group` stage.
+
+.. seealso::
+
+   :group:`$sum`
+
+
+Example
+-------
+
+Consider a ``sales`` collection with the following documents:
+
+.. code-block:: javascript
+
+   db.sales.insertMany([
+       { "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2021-01-01T08:00:00Z") },
+       { "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2021-02-03T09:00:00Z") },
+       { "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-03T09:05:00Z") },
+       { "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2021-02-15T08:00:00Z") },
+       { "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T09:05:00Z") },
+       { "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-15T12:05:10Z") },
+       { "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T14:12:12Z") },
+       { "_id" : 8, "item" : "abc", "price" : 10, "quantity" : 5, "date" : ISODate("2021-03-16T20:20:13Z") }
+    ])
+
+This operation returns a count of the documents in the stage.
+
+.. code-block:: javascript
+   
+   db.sales.aggregate( 
+      [
+        { 
+          $group: 
+            {
+              _id: null,
+              count: { $count: { } }
+            }
+         }
+      ] 
+   ) 
+
+
+The operation returns the following results:
+
+.. code-block:: javascript
+
+   { "_id" : null, "count" : 8 }

source/reference/operator/aggregation/group.txt

@@ -137,7 +137,7 @@ to count the number of documents in the ``sales`` collection:
      {
        $group: {
           _id: null,
-          count: { $sum: 1 }
+          count: { $count: { } }
        }
      }
    ] )
@@ -158,6 +158,7 @@ This aggregation operation is equivalent to the following SQL statement:
 .. seealso::
 
    - :pipeline:`$count`
+   - :group:`$count (aggregation accumulator) <$count>`
 
 .. _aggregation-group-distinct-values:
 

source/reference/operator/aggregation/sum.txt

@@ -162,6 +162,13 @@ The operation returns:
    { "_id" : { "day" : 34, "year" : 2014 }, "totalAmount" : 0, "count" : 2 }
    { "_id" : { "day" : 1, "year" : 2014 }, "totalAmount" : 0, "count" : 1 }
 
+The :group:`$count` aggregation accumulator can be used in place of
+``{ $sum : 1 }`` in the :pipeline:`$group` stage. 
+
+.. seealso:: 
+   
+   :group:`$count (aggregation accumulator) <$count>`
+
 Use in ``$project`` Stage
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

source/release-notes/5.0.txt

@@ -47,6 +47,18 @@ MongoDB 5.0 introduces the following aggregation operators:
        between 0 and 1 each time it is called. The new
        :expression:`$sampleRate` operator is based on ``$rand``. (Also
        added to MongoDB 4.4.2)
+   
+   * - :group:`$count`
+     - MongoDB 5.0 adds the 
+       :group:`$count (aggregation accumulator) <$count>` which 
+       provides a count of all documents when used in a 
+       :pipeline:`$group (aggregation) <$group>` pipeline stage.
+
+       .. note:: Disambiguation
+
+          The :group:`$count (aggregation accumulator) <$count>` is
+          distinct from the :pipeline:`$count (aggregation) <$count>` 
+          pipeline stage. 
 
 General Aggregation Improvements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~