DOCS-484

source/includes/note-ref-equality.rst

@@ -0,0 +1,13 @@
+.. note::
+
+   To signify ``equal to`` (``=``), MongoDB defaults to the JSON ``{
+   key:value }`` structure. For example, the query
+
+   .. code-block:: javascript
+
+   	db.collection.find( { field: value } )
+
+   selects all the documents where the ``field`` equals ``value``.
+
+
+

source/reference/operator/all.txt

@@ -6,21 +6,38 @@ $all
 
 .. operator:: $all
 
-   The :operator:`$all` operator matches a minimum set of elements that must
-   be present in a document's ``field``, as in the following example:
+   *Syntax*: ``{ field: { $all: array }``
+
+   :operator:`$all` selects the documents where:
+      - the ``field`` is *not* an array and its value matches the specified ``array``'s single element **or**
+      - the ``field`` is an array that contains all the elements in the specified ``array``.
+
+   **Example**: Select all documents in ``inventory`` where ``qty``
+   matches the element of the specified array ``[5]``.
+
+   .. code-block:: javascript
+
+      db.inventory.find( { qty: { $all: [ 5 ] } } )
 
+   **Example**: Select all documents in ``inventory`` where ``tags``
+   contains all the elements in the array ``["appliances", "school"]``.
+
    .. code-block:: javascript
+
+      db.inventory.find( { tags: { $all: [ "appliances", "school" ] } } )
 
-      db.collection.find( { field: { $all: [ 1, 2 , 3 ] } } );
+   **Example**: Update a single document in ``inventory`` where
+   ``tags`` contain all the elements in the array ``["appliances",
+   "school"]``.
 
-   This returns all documents in ``collection`` where the value of
-   ``field`` is an array that is equivalent to or a superset of ``[
-   1, 2, 3, ]``. The :operator:`$all` operator will not return any arrays
-   that are subsets; for example, the above query matches ``{ field: [
-   1, 2, 3, 4] }`` but not ``{ field: [ 2, 3 ] }``.
+   .. code-block:: javascript
 
+      db.inventory.update( { tags: { $all: [ "appliances", "school" ] } }, { $set: { sale: false } } )
+
    .. note::
 
       In most cases, MongoDB does not treat arrays as sets. This
-      operator provides a notable exception to this general approach
-
+      operator provides a notable exception to this general approach.
+
+   See also :method:`find() <db.collection.find()>`, :method:`update()
+   <db.collection.update()>`, :operator:`$set`.

source/reference/operator/and.txt

@@ -8,14 +8,43 @@ $and
 
    .. versionadded:: 2.0
 
-   The :operator:`$and` operator provides a Boolean ``AND`` expression in
-   queries. Use :operator:`$and` to return the documents that satisfy *all*
-   included expressions. For example:
+   *Syntax*: ``{ $and: [ { <expression1> }, { <expression2> } , ... , { <expressionN> } ] }`` 
+
+   :operator:`$and` performs a logical ``AND`` operation on the
+   specified array of ``<expressions>`` and selects the
+   documents that satisfy *all* the ``<expressions>`` in the array.
 
+   :operator:`$and` requires at least two ``<expressions>``. In the above
+   syntax, ``N`` must be greater than or equal to 2.
+
+   **Example**: Select all documents in ``inventory`` where
+      - ``price`` equals ``1.99`` **and** 
+      - ``qty`` is less than ``20`` **and**
+      - ``sale`` is ``true``.
+
+   .. code-block:: javascript
+
+      db.inventory.find({ $and: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] } )
+
+   **Example**: Update a single document in ``inventory`` where
+      - ``price`` equals ``1.99`` **and** 
+      - ``qty`` is less than ``20``.
+
+   .. code-block:: javascript
+
+      db.inventory.update( { $and: [ { price: 1.99 }, { qty: { $lt: 20 } } ] }, { $set: { qty: 15 } } )
+
+   MongoDB queries provide an implicit ``AND`` operation by specifying
+   a comma-separated list of expressions. The above examples are
+   equivalent to:
+
    .. code-block:: javascript
+
+      db.inventory.find( { price: 1.99, qty: { $lt: 20 } , sale: true } )
+
+      db.inventory.update( { price: 1.99, qty: { $lt: 20 } , sale: true }, { $set: { qty: 15 } } )
 
-      db.collection.find( { $and [ { key1: value1 }, { key2: value2} ] } );
+   See also :method:`find() <db.collection.find()>`, :method:`update()
+   <db.collection.update()>`, :operator:`$set`.
 
-   returns all documents in ``collection`` that have *both* a
-   ``key1`` field with ``value1`` *and* a ``key2`` field with
-   ``value2``.
+

source/reference/operator/exists.txt

@@ -6,19 +6,37 @@ $exists
 
 .. operator:: $exists
 
-   The :operator:`$exists` operator tests documents for the existence
-   of a field. The :operator:`$exists` operator accepts either true and
-   false values. For example:
+   *Syntax*: ``{ field: { $exists: boolean } }`` 
+
+   :operator:`$exists` selects the documents that contain
+   the field. 
+
+   MongoDB `$exists` does **not** correspond to SQL operator
+   ``exists``. For SQL ``exists``, refer to the :operator:`$in`.
+
+   **Example**: Select all documents in ``inventory`` where ``sale``
+   exists.
 
    .. code-block:: javascript
 
-        db.collection.find( { field: { $exists: true } );
+      db.inventory.find( { sale: { $exists: true } } )
 
-   returns all documents in ``collection`` that have ``field``, while:
+   **Example**: Select all documents in ``inventory`` where ``qty``
+   exists *and* is not in the array ``[5, 15]``.
+
+   .. code-block:: javascript
 
+      db.inventory.find( { $and: [ { qty: { $nin: [ 5, 15 ] } } , { qty: { $exists: true } } ] }, { qty:1 } )
+
+   You **must** use the :operator:`$and` construct rather than the
+   implicit ``AND`` operation provided by comma-separated list.
+
+   **Example**: Update a single document in ``inventory`` where
+   ``sale`` does *not* exist.
+
    .. code-block:: javascript
 
-      db.collection.find( { field: { $exists: false } );
+      db.inventory.update( { sale: { $exists: false } }, { $set: { sale: false } } )
 
-   returns all documents in ``collection`` that do *not* have ``field``
-   specified.
+   See also :method:`find() <db.collection.find()>`, :method:`update()
+   <db.collection.update()>`, :operator:`$set`, :operator:`$and`.

source/reference/operator/gt.txt

@@ -6,17 +6,24 @@ $gt
 
 .. operator:: $gt
 
-   The :operator:`$gt` comparison operator provides the ability to select
-   documents where a field is greater than (e.g. ``>``) a value:
+   *Syntax*: ``{field: {$gt: value} }``
 
-   .. code-block:: javascript
-
-      db.collection.find( { field: { $gt: value } } );
+   :operator:`$gt` selects those documents where the ``field`` is greater
+   than (i.e. ``>``) the specified ``value``.
 
-   This query returns all documents in ``collection`` where a value
-   of ``field`` is greater than the specified ``value``.
+   **Example**: Select all documents in ``inventory`` where ``qty`` is
+   greater than ``20``.
+
+   .. code-block:: javascript
 
-   If ``field`` holds an array, only one value in the array needs to
-   be greater than the specified ``value`` to produce a successful
-   match.
+      db.inventory.find( { qty: { $gt: 20 } } )
 
+   **Example**: Update a single document in ``inventory`` where ``qty``
+   is greater than ``20``.
+
+   .. code-block:: javascript
+
+      db.inventory.update( { qty: { $gt: 20 } }, { $set: { qty: 0 } } )
+
+   See also :method:`find() <db.collection.find()>`, :method:`update()
+   <db.collection.update()>`, :operator:`$set`.

source/reference/operator/gte.txt

@@ -6,14 +6,24 @@ $gte
 
 .. operator:: $gte
 
-   The :operator:`$gte` comparison operator provides the ability to select
-   documents where a field is greater than or equal to (e.g. ``>=``) a
-   value:
+   *Syntax*: ``{field: {$gte: value} }``
 
-   .. code-block:: javascript
+   :operator:`$gte` selects the documents where the ``field`` is greater than or
+   equal to (i.e. ``>=``) the specified ``value``.
 
-      db.collection.find( { field: { $gte: value } } );
+   **Example**: Select all documents in ``inventory`` where ``qty`` is
+   greater than or equal to ``20``.
+
+   .. code-block:: javascript
 
-   This query returns all documents in ``collection`` where the value
-   of ``field`` greater than or equal to the specified ``value``.
+      db.inventory.find( { qty: { $gte: 20 } } )
 
+   **Example**: Update a single document in ``inventory`` where ``qty``
+   is greater than or equal to ``20``.
+
+   .. code-block:: javascript
+
+      db.inventory.update( { qty: { $gte: 20 } }, { $set: { qty: 0 } } )
+
+   See also :method:`find() <db.collection.find()>`, :method:`update()
+   <db.collection.update()>`, :operator:`$set`.

source/reference/operator/in.txt

@@ -6,43 +6,34 @@ $in
 
 .. operator:: $in
 
-   The :operator:`$in` operator allows you to specify a set of possible
-   matches for any value. Consider the following form:
+   *Syntax*: ``{ field: { $in: array } }``
 
-   .. code-block:: javascript
-
-      db.collection.find( { field: { $in: array } } );
-
-   Here, :operator:`$in` returns all documents in ``collection`` where
-   ``field`` has a value included in ``array``. This is analogous to
-   the ``IN`` modifier in SQL. For example:
+   :operator:`$in` selects the documents where the ``field`` is in the
+   specified ``array``.
+
+   If the ``field`` is an array, then ``{ field: { $in: array } }``
+   is true *if* at least one element of the ``field`` is found in the ``array``.
 
+   **Example**: Select all documents in ``inventory`` where ``qty`` is
+   in the array ``[5, 15]``.
+
    .. code-block:: javascript
 
-      db.collection.find( { age: { $in: [ 1, 2, 3, 5, 7, 11 } } );
-
-   returns all documents in ``collection`` with an ``age`` field
-   that is *one* of the first six prime numbers, including all of the
-   following documents:
+      db.inventory.find( { qty: { $in: [ 5, 15 ] } } )
 
+   **Example**: Select all documents in ``inventory`` where any element
+   of the ``tags`` is in ``["appliances", "school"]``.
+
    .. code-block:: javascript
+
+      db.inventory.find( { tags: { $in: [ "appliances", "school" ] } } )
 
-      { age: 7 }
-      { age: 11 }
-      { age: 3 }
-
-   When the field that :operator:`$in` inspects (i.e. ``age`` in the
-   above example) is itself an array, only *one* of the values in the
-   array must match *one* of the values in the :operator:`$in`
-   array. Therefore, the following query:
-
-   .. code-block:: javascript
-
-      db.collection.find( { a: { $in: [1, 2] } } )
-
-   will match both of the following documents:
+   **Example**: Update a single document in ``inventory`` where any
+   element of the ``tags`` is in ``["appliances", "school"]``.
 
    .. code-block:: javascript
 
-      { a: [ 1, 3, 5, 7, 9 ] }
-      { a: [ 0, 2, 4, 6, 8 ] }
+      db.inventory.update( { tags: { $in: ["appliances", "school"] } }, { $set: { sale:true } } )
+
+   See also :method:`find() <db.collection.find()>`, :method:`update()
+   <db.collection.update()>`, :operator:`$set`.

source/reference/operator/lt.txt

@@ -6,12 +6,23 @@ $lt
 
 .. operator:: $lt
 
-   The :operator:`$lt` comparison operator provides the ability to select
-   documents where a field is less than (e.g. ``<``) a value:
+   *Syntax*: ``{field: {$lt: value} }``
 
+   :operator:`$lt` selects the documents where the ``field`` is less than
+   (i.e. ``<``) the specified ``value``.
+
+   **Example**: Select all documents in ``inventory`` where ``qty``
+   is less than ``20``.
+
    .. code-block:: javascript
 
-       db.collection.find( { field: { $lt: value } } );
+      db.inventory.find( { qty: { $lt: 20 } } )
 
-   This query returns all documents in ``collection`` where a value
-   of ``field`` is less than the specified ``value``.
+   **Example**: Update a single document in ``inventory`` where ``qty`` is less than ``20``.
+
+   .. code-block:: javascript
+
+      db.inventory.update( { qty: { $lt: 20 } }, { $set: { qty: 0 } } )
+
+   See also :method:`find() <db.collection.find()>`, :method:`update()
+   <db.collection.update()>`, :operator:`$set`.

source/reference/operator/lte.txt

@@ -6,13 +6,23 @@ $lte
 
 .. operator:: $lte
 
-   The :operator:`$lte` comparison operator provides the ability to select
-   documents where a field is less than or equal to (e.g. ``<=``) a
-   value:
+   *Syntax*: ``{ field: { $lte: value} }``
 
+   :operator:`$lte` selects the documents where the ``field`` is less than or
+   equal to (i.e. ``<=``) the specified ``value``.
+
+   **Example**: Select all documents in ``inventory`` where ``qty``
+   is less than or equal to ``20``.
+
    .. code-block:: javascript
 
-      db.collection.find( { field: { $lte: value } } );
+      db.inventory.find( { qty: { $lte: 20 } } )
 
-   This query returns all documents in ``collection`` where the value
-   of ``field`` less than or equal to the specified ``value``.
+   **Example**: Update a single document in ``inventory`` where ``qty`` is less than or equal to ``20``.
+
+   .. code-block:: javascript
+
+      db.inventory.update( { qty: { $lte: 20 } }, { $set: { qty: 0 } } )
+
+   See also :method:`find() <db.collection.find()>`, :method:`update()
+   <db.collection.update()>`, :operator:`$set`.

source/reference/operator/mod.txt

@@ -6,20 +6,23 @@ $mod
 
 .. operator:: $mod
 
-   The :operator:`$mod` operator performs a fast "modulo" query, to
-   reduce the need for expensive :operator:`$where` operator in some
-   cases. :operator:`$mod` performs a modulo operation on the value of
-   a field, and returns all documents that with the specified remainder value. For
-   example:
-
+   *Syntax*: ``{ field: { $mod: [ divisor, remainder ]} }``
+
+   :operator:`$mod` selects the documents where the ``field`` value modulo
+   ``divisor`` equals the ``remainder``. In some cases,
+   :operator:`$mod` can reduce the need for expensive
+   :operator:`$where` operator in some cases.
+
+   **Example**: Select all documents in ``inventory`` where the ``qty`` modulo ``4`` equals 3.
+
    .. code-block:: javascript
-
-      db.collection.find( { field: { $mod: [ d, m ] } } );
-
-   returns all documents in ``collection`` with a remainder of ``m``,
-   with a divisor of ``d``. This replaces the following
-   :operator:`$where` operation:
-
+
+      db.inventory.find( { qty: { $mod: [ 4, 0 ] } } )
+
+   replaces the more expensive
+
    .. code-block:: javascript
-
-      db.collection.find( "field % d == m" );
+
+      db.inventory.find( { $where: "this.qty % 4 == 3" } )
+
+   See also :method:`find() <db.collection.find()>`, :operator:`$where`