DOCS-503 positional operator doc

Author: kay-kim

source/reference/operator/positional.txt

@@ -0,0 +1,82 @@
+=
+$
+=
+
+.. default-domain:: mongodb
+
+.. operator:: $
+
+   *Syntax*: ``{ "array.$" : value }``
+
+   The positional :operator:`$` operator identifies an element in an
+   ``array`` field to update without explicitly specifying the position
+   of the element in the array. The positional :operator:`$` operator
+   is used in conjunction with the :method:`update()
+   <db.collection.update()>` method and acts as a placeholder for the
+   **first match** of the update ``query selector``:
+
+   .. code-block:: javascript
+
+      db.collection.update( { <query selector> }, { <update operator>: { "array.$" : value } } )
+
+   The ``array`` field **must** appear as part of the ``query selector``.
+
+   Consider the following collection ``students`` with the following documents:
+
+   .. code-block:: javascript
+
+      { "_id" : 1, "grades" : [ 80, 85, 90 ] }
+      { "_id" : 2, "grades" : [ 88, 90, 92 ] }
+      { "_id" : 3, "grades" : [ 85, 100, 90 ] }
+
+   To update ``80`` to ``82`` in the ``grades`` array field in the
+   first document, you can use the positional :operator:`$` operator if
+   you did not know the position of the element in the array:
+
+   .. code-block:: javascript
+
+      db.students.update( { _id: 1, grades: 80 }, { $set: { "grades.$" : 82 } } )
+
+   Remember that the positional :operator:`$` operator acts as a
+   placeholder for the **first match** of the update ``query selector``.
+
+   The positional :operator:`$` operator facilitates updates to arrays
+   that contain embedded documents. You can access the fields in the
+   embedded documents by applying the dot-notation on the :operator:`$`
+   operator.
+
+   .. code-block:: javascript
+
+      db.collection.update( { <query selector> }, { <update operator>: { "array.$.field" : value } } )
+
+   Consider the following document in the ``students`` collection whose
+   ``grades`` field value is an array of embedded documents:
+
+   .. code-block:: javascript
+
+      { "_id" : 4, "grades" : [ { grade: 80, mean: 75, std: 8 },
+                                { grade: 85, mean: 90, std: 5 },
+                                { grade: 90, mean: 85, std: 3 } ] }
+
+   To update the ``std`` value of the embedded document with the
+   ``grade`` of ``85``, you can use the positional :operator:`$`
+   operator:
+
+   .. code-block:: javascript
+
+      db.students.update( { _id: 4, "grades.grade": 85 }, { $set: { "grades.$.std" : 6 } } )
+
+   Consider the following behaviors when using the positional
+   :operator:`$` operator:
+   
+   - The positional :operator:`$` operator should not be used with an
+     :term:`upsert` since an insert will use the ``$`` as a field name
+     in the inserted document.
+
+   - When used with the :operator:`$unset` operator, the positional
+     :operator:`$` operator does not remove the matching element from
+     the array but rather set it to ``null``.
+
+   .. seealso::
+   
+      :method:`update() <db.collection.update()>`, :operator:`$set`.

source/reference/operators.txt

@@ -187,6 +187,9 @@ Fields
 Array
 ~~~~~
 
+.. include:: operator/positional.txt
+   :start-after: mongodb
+
 .. include:: operator/push.txt
    :start-after: mongodb