DOCS-484

source/includes/note-ref-equality.rst

@@ -0,0 +1,10 @@
+.. 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,48 @@ $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: [ < value1 > , < value2 > ... ] }``
+
+   :operator:`$all` selects the documents where the ``field`` is an
+   array and contains all the ``<values>`` in the array.  
+
+   For example, you would query:
+
    .. code-block:: javascript
+
+      db.inventory.find( { tags: { $all: [ "appliances", "school" ] } } )
+
+   to select all documents in ``inventory`` where ``tags`` contains all
+   the elements in the array ``[ "appliances", "school" ]``.  So, in the case of:
+
+   - a document with ``tags`` equal to ``[ "school", "book", "bag",
+     "headphone", "appliances" ]`` *and* 
+   - a document with ``tags`` equal to ``[ "appliances",
+     "school" ]``, 
+
+   the above query will return both documents.
+
+   Although :operator:`$all` is most meaningful when queried against an array
+   ``field``, you can use :operator:`$all`  to query against a non-array ``field``.
+
+   For example, you could query:
+
+   .. code-block:: javascript
+
+      db.inventory.find( { qty: { $all: [ 50 ] } } )
+
+   to select all documents in ``inventory`` where the integer ``qty``
+   equals ``50``; **however** you should, instead, use:
 
-      db.collection.find( { field: { $all: [ 1, 2 , 3 ] } } );
-
-   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.find( { qty: 50 } )
+
    .. 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.
+
+   .. seealso:: 
+      :method:`find() <db.collection.find()>`, :method:`update()
+      <db.collection.update()>`, :operator:`$set`.

source/reference/operator/and.txt

@@ -8,14 +8,51 @@ $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 an array of
+   *two or more* ``<expressions>`` and selects the
+   documents that satisfy *all* the ``<expressions>`` in the array.
 
+   For example, you would query: 
+
    .. code-block:: javascript
+
+      db.inventory.find({ $and: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] } )
 
-      db.collection.find( { $and [ { key1: value1 }, { key2: value2} ] } );
+   to select all documents in ``inventory`` where:
+
+   - ``price`` equals ``1.99`` **and** 
+   - ``qty`` is less than ``20`` **and**
+   - ``sale`` is ``true``.
 
-   returns all documents in ``collection`` that have *both* a
-   ``key1`` field with ``value1`` *and* a ``key2`` field with
-   ``value2``.
+   MongoDB provides an implicit ``AND`` operation when specifying a
+   comma separated list of expressions. For example, you can write the
+   above query as:
+
+   .. code-block:: javascript
+
+      db.inventory.find( { price: 1.99, qty: { $lt: 20 } , sale: true } )
+
+
+   However, you need to use the :operator:`$and` operator when you need an
+   ``AND`` operation on the value of a single field.
+
+   For example, you would query: 
+
+   .. code-block:: javascript
+
+      db.inventory.update( { $and: [ { price: { $ne: 1.99 } }, { price: { $exists: true } } ] }, { $set: { qty: 15 } } )
+
+   to update a single document in ``inventory`` where:
+
+   - ``price`` does not equal ``1.99`` **and** 
+   - ``price`` exists.
+
+   .. seealso:: 
+
+      :method:`find() <db.collection.find()>`, :method:`update()
+      <db.collection.update()>`, :operator:`$ne`, :operator:`$exists`,
+      :operator:`$set`.
+
+

source/reference/operator/exists.txt

@@ -6,19 +6,27 @@ $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 } }`` 
 
-   .. code-block:: javascript
-
-        db.collection.find( { field: { $exists: true } );
+   :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`
+   operator.
 
-   returns all documents in ``collection`` that have ``field``, while:
+   For example, you would query:
 
    .. code-block:: javascript
 
-      db.collection.find( { field: { $exists: false } );
-
-   returns all documents in ``collection`` that do *not* have ``field``
-   specified.
+      db.inventory.find( { $and: [ { qty: { $exists: true } }, { qty: { $nin: [ 5, 15 ] } } ] } )
+
+   to select all documents in ``inventory`` where ``qty`` exists *and* does
+   not equal either ``5`` nor ``15``.
+
+   The above query used the :operator:`$and` operator because the query
+   performs an ``AND`` operation on the value of a single field and is
+   not specific to the :operator:`$exists` operator.
+
+   .. seealso:: 
+
+      :method:`find() <db.collection.find()>`, :operator:`$and`,
+      :operator:`$nin``, :operator:`$in``.

source/reference/operator/gt.txt

@@ -6,17 +6,31 @@ $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``.
+   For example, you would query:
+
+   .. 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 } } )
 
+   to select all documents in ``inventory`` where ``qty`` is greater than
+   ``20``.
+
+   You may use the :operator:`$lt` operator to select fields from
+   embedded documents. For example, you would query:
+
+   .. code-block:: javascript
+
+      db.inventory.update( { "carrier.fee": { $gt: 2 } }, { $set: { price: 9.99 } } )
+
+   to update a single document in ``inventory`` where the field ``fee``
+   from the embedded document ``carrier`` is greater than ``2``.
+
+   .. seealso:: 
+
+      :method:`find() <db.collection.find()>`, :method:`update()
+      <db.collection.update()>`, :operator:`$set`.

source/reference/operator/gte.txt

@@ -6,14 +6,31 @@ $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} }``
 
+   :operator:`$gte` selects the documents where the ``field`` is
+   greater than or equal to (i.e. ``>=``) the specified ``value``.
+
+   For example, you would query:
+
    .. code-block:: javascript
 
-      db.collection.find( { field: { $gte: value } } );
+      db.inventory.find( { qty: { $gte: 20 } } )
+
+   to select all documents in ``inventory`` where ``qty`` is greater than
+   or equal to ``20``.
+
+   You may use the :operator:`$lt` operator to select fields from
+   embedded documents. For example, you would query:
+
+   .. code-block:: javascript
+
+      db.inventory.update( { "carrier.fee": { $gte: 2 } }, { $set: { price: 9.99 } } )
 
-   This query returns all documents in ``collection`` where the value
-   of ``field`` greater than or equal to the specified ``value``.
+   to update a single document in ``inventory`` where the field ``fee``
+   from the embedded document ``carrier`` is greater than ``2``.
 
+   .. seealso::
+
+      :method:`find() <db.collection.find()>`, :method:`update()
+      <db.collection.update()>`, :operator:`$set`.

source/reference/operator/in.txt

@@ -6,43 +6,37 @@ $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: [<value1>, <value2>, ... <valueN> ] } }``
 
+   :operator:`$in` selects the documents where the ``field`` equals any
+   value in the specified ``array``.
+
+   For example, you would query: 
+
    .. code-block:: javascript
 
-      db.collection.find( { field: { $in: array } } );
+      db.inventory.find( { qty: { $in: [ 5, 15 ] } } )
 
-   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:
+   to select all documents in ``inventory`` where ``qty`` is either ``5`` or ``15``.
+
+   Although you could write the above query using the :operator:`$or`
+   operator, :operator:`$in` is preferred over :operator:`$or` when
+   performing equality checks for the same.
+
+   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``.
 
+   For example, the query:
+
    .. 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:
-
-   .. code-block:: javascript
-
-      { 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:
-
-   .. 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 } } )
+
+   will update a single document in ``inventory`` where at least one
+   element of the ``tags`` array matches an element in ``["appliances",
+   "school"]``.
+
+   .. seealso:: 
+
+      method:`find() <db.collection.find()>`, :method:`update()
+      <db.collection.update()>`, :operator:`$or`, :operator:`$set`.

source/reference/operator/lt.txt

@@ -6,12 +6,31 @@ $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``.
+
+   For example, you would query:
+
    .. code-block:: javascript
 
-       db.collection.find( { field: { $lt: value } } );
+      db.inventory.find( { qty: { $lt: 20 } } )
+
+   to select all documents in ``inventory`` where ``qty`` is less than
+   ``20``.
 
-   This query returns all documents in ``collection`` where a value
-   of ``field`` is less than the specified ``value``.
+   You may use the :operator:`$lt` operator to select fields from
+   embedded documents. For example, you would query:
+
+   .. code-block:: javascript
+
+      db.inventory.update( { "carrier.fee": { $lt: 20 } }, { $set: { price: 9.99 } } )
+
+   to update a single document in ``inventory`` where the field ``fee``
+   from the embedded document ``carrier`` is less than ``20``.
+
+   .. seealso::
+
+      method:`find() <db.collection.find()>`, :method:`update()
+      <db.collection.update()>`, :operator:`$set`.