DOCS-1237 tutorial for push operation w modifiers

Author: kay-kim

source/applications.txt

@@ -57,3 +57,4 @@ The following documents provide patterns for developing application features:
    tutorial/isolate-sequence-of-operations
    tutorial/create-an-auto-incrementing-field
    tutorial/expire-data
+   tutorial/limit-number-of-elements-in-updated-array

source/reference/aggregation/match.txt

@@ -85,9 +85,9 @@ $match (aggregation)
         <index>` like any other :mongodb:method:`db.collection.find()`
         or :mongodb:method:`db.collection.findOne()`.
 
-   .. versionchanged:: 2.4
-      Prior to 2.4, :pipeline:`$match` queries did **not** support the
-      geospatial :mongodb:operator:`$within` operator.
+   .. versionadded:: 2.4
+      :pipeline:`$match` queries can support the
+      geospatial :mongodb:operator:`$within` operations.
 
    .. warning::
 

source/release-notes/2.4.txt

@@ -940,20 +940,32 @@ performs an insert, use the :operator:`$setOnInsert` operator with the
    update and for :method:`updates <db.collection.update()>` when the
    ``upsert`` option is ``false``.
 
-``$each``, ``$slice``, and ``$sort`` Available for Use with ``$push``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Limit Number of Elements in an Array
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can now use the :operator:`$push` operator with the following
-modifiers:
+Consider a situation where you only want to maintain a fixed number of
+elements in an array.
 
-- :operator:`$each` to append multiple values to the array field,
+In 2.4, by using the :operator:`$push` operator with the
+:operator:`$each`, the :operator:`$sort`, and the :operator:`$slice`
+modifiers, you can add multiple elements to an array, sort and limit
+the number of elements in the modified array to maintain an array with
+a fixed number of elements.
 
-- :operator:`$slice` to restrict the number of array elements and which
-  must be used with :operator:`$each`, and
+See :doc:`/tutorial/limit-number-of-elements-in-updated-array` for an
+example where an update maintains the top three scores for a student.
 
-- :operator:`$sort` to order the elements of the array, which
-  must be used with :operator:`$slice` and can **only** sort
-  arrays that contain documents.
+.. seealso::
+
+   The following pages provide additional information and examples:
+
+   - :operator:`$push` operator
+
+   - :operator:`$each` modifier
+
+   - :operator:`$sort` modifier
+
+   - :operator:`$slice` modifier
 
 .. _rn-2.4-javascript-change:
 

source/tutorial.txt

@@ -62,6 +62,7 @@ Development Patterns
 - :doc:`/tutorial/enforce-unique-keys-for-sharded-collections`
 - :doc:`/tutorial/aggregation-examples`
 - :doc:`/tutorial/model-data-for-keyword-search`
+- :doc:`/tutorial/limit-number-of-elements-in-updated-array`
 
 .. index:: tutorials; application development
 .. index:: application tutorials

source/tutorial/limit-number-of-elements-in-updated-array.txt

@@ -0,0 +1,91 @@
+====================================================
+Limit Number of Elements in an Array after an Update
+====================================================
+
+.. default-domain:: mongodb
+
+.. versionadded:: 2.4
+
+Synopsis
+--------
+
+Consider an application where users may submit many scores (e.g. for a
+test), but the application only needs to track the top three test
+scores.
+
+This pattern uses the :operator:`$push` operator with the
+:operator:`$each`, :operator:`$sort`, and :operator:`$slice`
+modifiers to sort and maintain an array of fixed size.
+
+.. important:: The array elements must be documents in order to use the
+   :operator:`$sort` modifier.
+
+Pattern
+-------
+
+Consider the following document in the collection ``students``:
+
+.. code-block:: javascript
+
+   {
+     _id: 1,
+     scores: [
+               { attempt: 1, score: 10 },
+               { attempt: 2 , score:8 }
+             ]
+   }
+
+The the following update uses the :operator:`$push` operator with:
+
+- the :operator:`$each` modifier to append to the array 2 new elements,
+
+- the :operator:`$sort` modifier to order the elements by ascending
+  (``1``) score, and
+
+- the :operator:`$slice` modifier to keep the last ``3`` elements of
+  the ordered array.
+
+.. code-block:: javascript
+
+   db.students.update(
+                       { _id: 1 }, 
+                       { $push: { scores: { $each : [
+                                                      { attempt: 3, score: 7 },
+                                                      { attempt: 4, score: 4 }
+                                                    ],
+                                            $sort: { score: 1 },
+                                            $slice: -3
+                                          }
+                                 }
+                       }
+                     )
+
+.. note::
+
+   When using the :operator:`$sort` modifier on the array element,
+   access the field in the subdocument element directly instead of
+   using the :term:`dot notation` on the array field.
+
+After the operation, the document contains the only the top 3 scores in
+the ``scores`` array:
+
+.. code-block:: javascript
+
+   {
+      "_id" : 1,
+      "scores" : [
+                   { "attempt" : 3, "score" : 7 },
+                   { "attempt" : 2, "score" : 8 },
+                   { "attempt" : 1, "score" : 10 } 
+                 ]
+   }
+
+.. seealso::
+
+   - :operator:`$push` operator,
+
+   - :operator:`$each` modifier,
+
+   - :operator:`$sort` modifier, and
+
+   - :operator:`$slice` modifier.