DOCSP-21058 BACKPORT (#780)

Author: Dave

source/reference/operator/aggregation/first.txt

@@ -47,6 +47,19 @@ Behavior
 
 .. include:: /includes/note-group-and-window-behavior.rst
 
+Missing Values
+~~~~~~~~~~~~~~
+
+The documents in a group may be missing fields or may have fields with
+missing values.
+
+- If there are no documents from the prior pipeline stage, the 
+  :pipeline:`$group` stage returns nothing.
+- If the field that the :group:`$first` accumulator is processing is
+  missing, :group:`$first` returns ``null``.
+  
+See the :ref:`missing data <first-missing-values-example>` example.
+
 Examples
 --------
 
@@ -55,17 +68,19 @@ Examples
 Use in ``$group`` Stage
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Consider a ``sales`` collection with the following documents:
+Create the ``sales`` collection:
 
 .. code-block:: javascript
 
-   { "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") }
-   { "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") }
-   { "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") }
-   { "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") }
-   { "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") }
-   { "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-15T12:05:10Z") }
-   { "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T14:12:12Z") }
+   db.sales.insertMany( [
+      { "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2014-01-01T08:00:00Z") },
+      { "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2014-02-03T09:00:00Z") },
+      { "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-03T09:05:00Z") },
+      { "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2014-02-15T08:00:00Z") },
+      { "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T09:05:00Z") },
+      { "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2014-02-15T12:05:10Z") },
+      { "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T14:12:12Z") }
+   ] )
 
 Grouping the documents by the ``item`` field, the following operation
 uses the :group:`$first` accumulator to compute the first sales date for
@@ -80,7 +95,7 @@ each item:
           $group:
             {
               _id: "$item",
-              firstSalesDate: { $first: "$date" }
+              firstSale: { $first: "$date" }
             }
         }
       ]
@@ -90,9 +105,66 @@ The operation returns the following results:
 
 .. code-block:: javascript
 
-   { "_id" : "xyz", "firstSalesDate" : ISODate("2014-02-03T09:05:00Z") }
-   { "_id" : "jkl", "firstSalesDate" : ISODate("2014-02-03T09:00:00Z") }
-   { "_id" : "abc", "firstSalesDate" : ISODate("2014-01-01T08:00:00Z") }
+   [
+      { _id: 'jkl', firstSale: ISODate("2014-02-03T09:00:00.000Z") },
+      { _id: 'xyz', firstSale: ISODate("2014-02-03T09:05:00.000Z") },
+      { _id: 'abc', firstSale: ISODate("2014-01-01T08:00:00.000Z") }
+   ]
+
+.. _first-missing-values-example:
+
+Missing Data
+~~~~~~~~~~~~
+
+Some documents in the ``badData`` collection are missing fields, other
+documents are missing values. 
+
+Create the ``badData`` collection:
+
+.. code-block:: javascript
+
+   db.badData.insertMany( [
+      { "_id": 1, "price": 6, "quantity": 6 },
+      { "_id": 2, "item": "album", "price": 5 , "quantity": 5  },
+      { "_id": 7, "item": "tape", "price": 6, "quantity": 6 },
+      { "_id": 8, "price": 5, "quantity": 5  },
+      { "_id": 9, "item": "album", "price": 3, "quantity": '' },
+      { "_id": 10, "item": "tape", "price": 3, "quantity":  4 },
+      { "_id": 12, "item": "cd", "price": 7  }
+   ] )
+
+Query the ``badData`` collection, grouping the output on the ``item``
+field:
+
+.. code-block:: javascript
+
+   db.badData.aggregate( [
+      { $sort: { item: 1, price: 1 } },
+      { $group: 
+         { 
+            _id: "$item",
+            inStock: { $first: "$quantity" }
+         }
+      }
+   ] )
+
+The :pipeline:`$sort` stage orders the documents and passes them to the
+:pipeline:`$group` stage.
+
+.. code-block:: javascript
+
+   [
+     { _id: null, inStock: 5 },
+     { _id: 'album', inStock: '' },
+     { _id: 'cd', inStock: null },
+     { _id: 'tape', inStock: 4 }
+   ]
+
+:group:`$first` selects the first document from each output group:
+
+- The ``_id: null`` group is included.
+- When the accumulator field, ``$quantity`` in this example, is 
+  missing, :group:`$first` returns ``null``.
 
 .. _first-accumulator-window-example: