From 542afe4cf8441aa30dec7b74346129444f4eef52 Mon Sep 17 00:00:00 2001 From: kay Date: Fri, 7 Sep 2012 09:53:15 -0400 Subject: [PATCH 1/3] DOCS-484 --- source/includes/note-ref-equality.rst | 13 +++ source/reference/operator/all.txt | 37 ++++++--- source/reference/operator/and.txt | 43 ++++++++-- source/reference/operator/exists.txt | 34 ++++++-- source/reference/operator/gt.txt | 27 +++--- source/reference/operator/gte.txt | 24 ++++-- source/reference/operator/in.txt | 51 +++++------- source/reference/operator/lt.txt | 21 +++-- source/reference/operator/lte.txt | 22 +++-- source/reference/operator/mod.txt | 33 ++++---- source/reference/operator/ne.txt | 21 +++-- source/reference/operator/nin.txt | 42 ++++++++-- source/reference/operator/nor.txt | 60 ++++++++++++-- source/reference/operator/not.txt | 82 +++++++++++------- source/reference/operator/or.txt | 45 ++++++---- source/reference/operator/type.txt | 60 +++++++++----- source/reference/operators.txt | 115 +++++++++++++------------- 17 files changed, 483 insertions(+), 247 deletions(-) create mode 100644 source/includes/note-ref-equality.rst diff --git a/source/includes/note-ref-equality.rst b/source/includes/note-ref-equality.rst new file mode 100644 index 00000000000..d419a84a95d --- /dev/null +++ b/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``. + + + diff --git a/source/reference/operator/all.txt b/source/reference/operator/all.txt index 56770253827..d2514f7618b 100644 --- a/source/reference/operator/all.txt +++ b/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() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/and.txt b/source/reference/operator/and.txt index a39c02b0817..003bc2f12ec 100644 --- a/source/reference/operator/and.txt +++ b/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: [ { }, { } , ... , { } ] }`` + + :operator:`$and` performs a logical ``AND`` operation on the + specified array of ```` and selects the + documents that satisfy *all* the ```` in the array. + :operator:`$and` requires at least two ````. 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() `, :method:`update() + `, :operator:`$set`. - returns all documents in ``collection`` that have *both* a - ``key1`` field with ``value1`` *and* a ``key2`` field with - ``value2``. + \ No newline at end of file diff --git a/source/reference/operator/exists.txt b/source/reference/operator/exists.txt index 260c2007994..e55e92d5850 100644 --- a/source/reference/operator/exists.txt +++ b/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() `, :method:`update() + `, :operator:`$set`, :operator:`$and`. diff --git a/source/reference/operator/gt.txt b/source/reference/operator/gt.txt index 9d9b32c9191..acb2bf2150d 100644 --- a/source/reference/operator/gt.txt +++ b/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() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/gte.txt b/source/reference/operator/gte.txt index ee189c55df6..51e2779e585 100644 --- a/source/reference/operator/gte.txt +++ b/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() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/in.txt b/source/reference/operator/in.txt index 5f3f38af4db..aa25293a2f0 100644 --- a/source/reference/operator/in.txt +++ b/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() `, :method:`update() + `, :operator:`$set`. \ No newline at end of file diff --git a/source/reference/operator/lt.txt b/source/reference/operator/lt.txt index f049a64d40a..3346275e960 100644 --- a/source/reference/operator/lt.txt +++ b/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() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/lte.txt b/source/reference/operator/lte.txt index abb20d02b8d..eb293b3b972 100644 --- a/source/reference/operator/lte.txt +++ b/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() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/mod.txt b/source/reference/operator/mod.txt index 47bb492527d..3f818050c95 100644 --- a/source/reference/operator/mod.txt +++ b/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() `, :operator:`$where` diff --git a/source/reference/operator/ne.txt b/source/reference/operator/ne.txt index 242b33bfd0f..2e935e725e0 100644 --- a/source/reference/operator/ne.txt +++ b/source/reference/operator/ne.txt @@ -6,13 +6,24 @@ $ne .. operator:: $ne - The :operator:`$ne` operator returns documents where a field is not - equal to the specified value. The following command: + *Syntax*: ``{field: {$ne: value} }`` + :operator:`$ne` selects the documents where a ``field`` is not equal + (i.e. ``!=``) to the specified ``value``. + + **Example**: Select all documents in ``inventory`` where ``qty`` does + not equal ``20``. + .. code-block:: javascript - db.collection.find( { field: { $ne: 100 } } ); + db.inventory.find( { qty: { $ne: 20 } } ) - returns all documents in ``collection`` with ``field`` that does not - equal 100. + **Example**: Update a single document in ``inventory`` where ``qty`` + does not equal ``20``. + + .. code-block:: javascript + db.inventory.update( { qty: { $ne: 20 } }, { $set: { qty: 20 } } ) + + See also :method:`find() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/nin.txt b/source/reference/operator/nin.txt index f1d68a1226a..0be4625d2e7 100644 --- a/source/reference/operator/nin.txt +++ b/source/reference/operator/nin.txt @@ -1,18 +1,44 @@ -=== -$in -=== +==== +$nin +==== .. default-domain:: mongodb .. operator:: $nin - The :operator:`$nin` operator provides a "not in," as the inverse of - :operator:`$in`. For example: + *Syntax*: ``{ field: { $nin: array} }`` + :operator:`$nin` selects the documents where: + - the ``field`` is not in the specified ``array`` **or** + - the ``field`` does not exist. + + If the ``field`` is an array, then ``{ field: { $in: array } }`` is true + **if** no element of the ``field`` is in the ``array``. + + **Example**: Select all documents in ``inventory`` where ``qty`` is + not in the array ``[5, 15]`` including the documents that do *not* + contain the ``qty`` field. + .. code-block:: javascript - db.collection.find( { age: { $nin: [ 3, 5, 7 } } ); + db.inventory.find( { qty: { $nin: [ 5, 15 ] } } ) + + **Example**: Select all documents in ``inventory`` where the + elements of the ``tags`` array are *not* in ``["appliances", + "school"]`` including the documents that do not contain the ``tags`` + field. + + .. code-block:: javascript + + db.inventory.find( { tags: { $nin: [ "appliances", "school" ] } } ) - returns all documents in ``collection`` where the value of ``age`` - is *not* 3, 5, or 7. + **Example**: Update a single document in ``inventory`` where the + elements of the ``tags`` array is not in ``["appliances", + "school"]`` or a document that does not contain the field ``tags``. + + .. code-block:: javascript + db.inventory.update( { tags: { $nin: [ "appliances", "school" ] } }, { $set: { sale: false } } ) + + See also :method:`find() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/nor.txt b/source/reference/operator/nor.txt index b8220a3fa90..48e0e19d744 100644 --- a/source/reference/operator/nor.txt +++ b/source/reference/operator/nor.txt @@ -6,15 +6,59 @@ $nor .. operator:: $nor - The :operator:`$nor` operators provides a Boolean ``NOR`` expression in - queries. :operator:`$nor` is the functional inverse of :operator:`$or`. Use - :operator:`$nor` to exclude documents that have fields with specific - values. For example: + *Syntax*: ``{ $nor: [ { }, { }, ... { } ] }`` + :operator:`$nor` performs a logical ``NOR`` operation on the specified + array of ```` and selects the documents that + fail all the ```` in the array. + + :operator:`$nor` requires at least two ````. In the above + syntax, ``N`` must be greater than or equal to 2. + + **Example**: Select all documents in ``inventory`` where: + - ``price`` does *not* equal ``1.99`` **and** + - ``qty`` is *not* less than ``20`` **and** + - ``sale`` is *not* ``true`` + + including those documents that do not contain these field(s). + .. code-block:: javascript - db.collection.find( { $nor [ { key1: value1 }, { key2: value2} ] } ); + db.inventory.find( { $nor: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] } ) - returns all documents in ``collection`` that have *neither* a - ``key1`` field with ``value1`` *nor* a ``key2`` field with - ``value2``. + **Example**: Update a single document in ``inventory`` where: + - ``price`` does *not* equal ``1.99`` **and** + - ``qty`` is *not* less than ``20``. + + This may be a document that does not contain these field(s). + + .. code-block:: javascript + + db.inventory.update( { $nor: [ { price: 1.99 }, { qty: 20 } ] }, { $set: {qty: 15} } ) + + A document fails *most* Boolean expressions if the document is + missing the field in the expression. The exception is the expression + ``{ missingField: { $exists: false } }``. The following query + + .. code-block:: javascript + + db.inventory.find( { $nor: [ { price: 1.99 }, { sale: true } ] } ) + + will return all documents that: + - have ``price`` *not* equal to ``1.99`` *and* ``sale`` *is not* ``true`` **or** + - have ``price`` *not* equal to ``1.99`` *and* does *not* contain the ``sale`` field **or** + - does *not* contain the ``price`` field *and* ``sale`` *is not* ``true`` **or** + - does *not* contain the ``price`` field *and* does *not* contain the ``sale`` field + + whereas + + .. code-block:: javascript + + db.inventory.find( { $nor: [ { price: 1.99 }, { price: { $exists: false } }, + { sale: true }, { sale: { $exists: false } } ] } ) + + will return all documents that: + - have ``price`` *not* equal to ``1.99`` *and* ``sale`` *is not* ``true``. + + See also :method:`find() `, :method:`update() + `, :operator:`$set`, :operator:`$exists`. diff --git a/source/reference/operator/not.txt b/source/reference/operator/not.txt index dcc6ddb26f8..4066325c2a2 100644 --- a/source/reference/operator/not.txt +++ b/source/reference/operator/not.txt @@ -6,38 +6,60 @@ $not .. operator:: $not - :operator:`$not` is a meta operator used to reverse the operation - of a standard operator. If a document does not match a query statement, - passing that query statement to the :operator:`$not` will return - that document. The operation of :operator:`$not` is consistent with - the behavior of other operators, but may yield unexpected results - with some data types, like arrays. + *Syntax*: ``{ field: { $not: { } } }`` - :operator:`$not` only affects *other operators*, and is unable to - check fields and documents independently. Use :operator:`$ne` to - test the contents of fields directly and :operator:`$nor` for - logical disjunctions. + :operator:`$not` performs a logical ``NOT`` operation on the + specified ```` and selects the documents that + do *not* match the ````. This includes documents that + do not contain the ``field``. - Consider the following example of :operator:`$not`: + :operator:`$not` only affects *other operators* and cannot + check fields and documents independently. + + Use :operator:`$ne` to test the contents of fields directly and + :operator:`$nor` for logical disjunctions instead. + **Example**: Select all documents in ``inventory`` where the + ``price`` is *not* greater than ``1.99``. + .. code-block:: javascript - db.collection.find( { field: { $not: { $type: 2 } } } ); - - This query returns all documents in ``collection`` where ``field`` - is *not* a string, using the :operator:`$type` operator. - - .. note:: - - The :operator:`$not` operator does not support operations with - :operator:`$regex`. - - When using :operator:`$not`, pass all regular expressions using - the native BSON type. For example, consider the following - expression fragment in Python, using the PyMongo driver: - - .. code-block:: python - - { "$not": re.compile("acme.*corp")} - - .. see:: The :operator:`$type` operator, used in the above example. + db.inventory.find( { price: { $not: { $gt: 1.99 } } } ) + + The query selects all documents where: + - ``price`` is less than or equal to ``1.99`` **or** + - ``price`` does not exist + + ``{ $not: { $gt: 1.99 } }`` is different from the :operator:`$lte` operator. + ``{ $lt: 1.99 }`` returns *only* the documents where ``price`` is less than or equal to ``1.99``. + + The operation of :operator:`$not` is consistent with the behavior of + other operators but may yield unexpected results with some data + types like arrays. + + The :operator:`$not` operator does **not** support operations with + :operator:`$regex`. Instead use ``//`` or in your driver interfaces, + use your langauge's regular expression capability to create regular + expression objects. + + **Example**: Select all documents in ``inventory`` where the + ``item`` does *not* start with the letter ``p`` using the pattern + match operator ``/^p.*/``. + + .. code-block:: javascript + + db.inventory.find( { item: { $not: /^p.*/ } } ) + + **Example**: Select all documents in ``inventory`` where the + ``item`` does *not* start with the letter ``p`` in PyMongo using + ``re.compile()``. + + .. code-block:: python + + import re + for noMatch in db.inventory.find( { "item": { "$not": re.compile("^p.*") } } ): + print noMatch + + See also :method:`find() `, :method:`update() + `, :operator:`$set`, :operator:`$gt`, :operator:`$regex`, + :api:`PyMongo `, :term:`driver`. diff --git a/source/reference/operator/or.txt b/source/reference/operator/or.txt index db561884890..49734769802 100644 --- a/source/reference/operator/or.txt +++ b/source/reference/operator/or.txt @@ -8,29 +8,38 @@ $or .. versionadded:: 1.6 - The :operator:`$or` operator provides a Boolean ``OR`` expression in - queries. Use :operator:`$or` to match documents against two or more - expressions. For example: - - .. code-block:: javascript + .. versionchanged:: 2.0 + You may nest :operator:`$or` operations; however, these + expressions are not as efficiently optimized as top-level. - db.collection.find( { $or [ { key1: value1 }, { key2: value2} ] } ); + *Syntax*: ``{ $or: [ { }, { }, ... , { } ] }`` - returns all documents in ``collection`` that *either* have a - ``key1`` field with ``value1`` *or* a ``key2`` field with ``value2``. + :operator:`$or` performs a logical ``OR`` operation on the specified + array of ```` and selects the documents that satisfy + *at least* one of the ````. + + The :operator:`$or` requires at least two ````. In the above + syntax, ``N`` must be greater than or equal to 2. - You may specify a field and then use the :operator:`$or` operator to - further narrow results. Consider the following: + **Examples**: Select all documents in ``inventory`` where: + - ``price`` equals ``1.99`` **and** + - **(** ``qty`` is less than ``20`` **or** ``sale`` is `true` **)**. .. code-block:: javascript + + db.inventory.find( { price:1.99, $or: [ { qty: { $lt: 20 } }, { sale: true } ] } ) + + // or using the $and command + + db.inventory.find( { $and: [ {price:1.99}, { $or: [ { qty: { $lt: 20 } }, { sale: true } ] } ] } ) - db.collection.find( { age: "19", $or [ { key1: value1 }, { key2: value2} ] } ); + **Example**: Update a single document in ``inventory`` where + - ``price`` equals ``1.99`` **or** + - ``qty`` is less than ``20``. - This query returns all documents in ``collection`` with an ``age`` - field that has the value ``19``, and *either* a ``key1`` field with - ``value1`` *or* a ``key2`` field with ``value2``. + .. code-block:: javascript + + db.inventory.update( { $or: [ { price: 1.99 }, { qty: { $lt: 20 } } ] }, { $set: { qty: 15 } } ) - .. versionadded:: 2.0 - You may nest :operator:`$or` operations; however, these - expressions are not as efficiently optimized as top-level - :operator:`$or` operations. + See also :method:`find() `, :method:`update() + `, :operator:`$set`, :operator:`$and`. diff --git a/source/reference/operator/type.txt b/source/reference/operator/type.txt index dbfbb254232..f399cf6f99c 100644 --- a/source/reference/operator/type.txt +++ b/source/reference/operator/type.txt @@ -6,22 +6,49 @@ $type .. operator:: $type - The :operator:`$type` operator matches field values with a specific data - type. :operator:`$type` operator allows you to narrow results based on any - :term:`BSON` type. For example: + *Syntax*: ``{ field: { $type: } }`` + + :operator:`$type` selects the documents where the *value* of the + ``field`` is the specified :term:`BSON` type. + + **Example**: Select all documents in ``inventory`` where the value + of ``price`` is a Double. .. code-block:: javascript - db.collection.find( { field: { $type: 2 } } ); + db.inventory.find( { price: { $type : 1 } } ) + + If the field is an array, :operator:`$type` operates + on the array elements and **not** the field value as a whole. + + **Example**: Select all documents in ``inventory`` where the + ``tags`` array contains an element that is of type array. + + .. code-block:: javascript + + db.inventory.find( { tags: { $type : 4 } } ) + + To determine whether the field is an array, use the + :operator:`$where` operator. + + **Example**: Select all documents in ``inventory`` where ``tags`` is + of type array. + + .. code-block:: javascript + + db.inventory.find( { $where : "Array.isArray(this.tags)" } ) - returns all documents in ``collection`` where the value of - ``field`` is a string. Consider the following chart for the - available types and their corresponding numbers. + See the :issue:`SERVER-1475` for more information about the + array type. + + + Refer to the following table for the + available :term:`BSON` types and their corresponding numbers. ======================= ========== **Type** **Number** ----------------------- ---------- - Double 1 + Double 1 String 2 Object 3 Array 4 @@ -47,25 +74,13 @@ $type .. note:: - Queries for ``MaxKey`` using the :operator:`$type` work as - expected; however, to query for ``MinKey`` you must specify + To query if a field value is a ``MinKey``, you must use the :operator:`$type` with ``-1`` as in the following example: .. code-block:: javascript db.collection.find( { field: { $type: -1 } } ) - Query statements cannot use :operator:`$type` to test arrays - (i.e. ``4``.) Instead, use the :operator:`$where` operator that - resembles the following: - - .. code-block:: javascript - - db.collection.find( { field: { $where : "Array.isArray(this.field)" } } ) - - See the :issue:`SERVER-1475` for more information about the - array type. - .. example:: Consider the following example operation sequence that @@ -99,3 +114,6 @@ $type db.chunks.find( { "min.shardKey": { $type: -1 } } ) .. include:: /includes/warning-mixing-types.rst + + See also :method:`find() `, :method:`insert() + `, :operator:`$where`, :term:`BSON`, :term:`shard key`, :term:`shard cluster` . \ No newline at end of file diff --git a/source/reference/operators.txt b/source/reference/operators.txt index 925a6fa00f3..0591a719b2f 100644 --- a/source/reference/operators.txt +++ b/source/reference/operators.txt @@ -21,85 +21,58 @@ Query Selectors Comparison ~~~~~~~~~~ -.. include:: operator/lt.txt +.. include:: /includes/note-ref-equality.rst + +.. include:: operator/ne.txt :start-after: mongodb -.. include:: operator/gt.txt +.. include:: operator/lt.txt :start-after: mongodb .. include:: operator/lte.txt :start-after: mongodb + +.. include:: operator/gt.txt + :start-after: mongodb .. include:: operator/gte.txt :start-after: mongodb +.. include:: operator/in.txt + :start-after: mongodb + +.. include:: operator/nin.txt + :start-after: mongodb + +.. include:: operator/all.txt + :start-after: mongodb + .. TODO move the following note into a querying page, and link in every above included query operator page. -You may combine comparison operators to specify ranges: + You may combine comparison operators to specify ranges: -.. code-block:: javascript + .. code-block:: javascript - db.collection.find( { field: { $gt: value1, $lt: value2 } } ); + db.collection.find( { field: { $gt: value1, $lt: value2 } } ); -This statement returns all documents with ``field`` between -``value1`` and ``value2``. + This statement returns all documents with ``field`` between + ``value1`` and ``value2``. -.. note:: + .. note:: Fields containing arrays match conditional operators, if only one item matches. Therefore, the following query: - .. code-block:: javascript - - db.collection.find( { field: { $gt:0, $lt:2 } } ); - - Will match a document that contains the following field: - - .. code-block:: javascript - - { field: [-1,3] } - -.. index:: query selectors; document -.. _query-selectors-document: - -Document -~~~~~~~~ + .. code-block:: javascript -.. include:: operator/all.txt - :start-after: mongodb - -.. include:: operator/exists.txt - :start-after: mongodb - -.. include:: operator/ne.txt - :start-after: mongodb - -.. include:: operator/in.txt - :start-after: mongodb + db.collection.find( { field: { $gt:0, $lt:2 } } ); -.. include:: operator/nin.txt - :start-after: mongodb + Will match a document that contains the following field: -.. index:: query selectors; geospatial -.. _query-selectors-geospatial: -.. _geospatial-query-operators: -.. _geolocation-operators: + .. code-block:: javascript -Geospatial -~~~~~~~~~~ - -.. include:: operator/near.txt - :start-after: mongodb - -.. include:: operator/maxDistance.txt - :start-after: mongodb - -.. include:: operator/within.txt - :start-after: mongodb - -.. include:: operator/uniqueDocs.txt - :start-after: mongodb + { field: [-1,3] } .. index:: query selectors; logical .. _query-selectors-logical: @@ -107,13 +80,13 @@ Geospatial Logical ~~~~~~~ -.. include:: operator/or.txt +.. include:: operator/and.txt :start-after: mongodb -.. include:: operator/nor.txt +.. include:: operator/or.txt :start-after: mongodb -.. include:: operator/and.txt +.. include:: operator/nor.txt :start-after: mongodb .. include:: operator/not.txt @@ -125,12 +98,13 @@ Logical Element ~~~~~~~ -.. include:: operator/type.txt +.. include:: operator/exists.txt :start-after: mongodb -.. include:: operator/regex.txt +.. include:: operator/type.txt :start-after: mongodb + .. include:: operator/mod.txt :start-after: mongodb @@ -143,6 +117,29 @@ JavaScript .. include:: operator/where.txt :start-after: mongodb +.. include:: operator/regex.txt + :start-after: mongodb + +.. index:: query selectors; geospatial +.. _query-selectors-geospatial: +.. _geospatial-query-operators: +.. _geolocation-operators: + +Geospatial +~~~~~~~~~~ + +.. include:: operator/near.txt + :start-after: mongodb + +.. include:: operator/maxDistance.txt + :start-after: mongodb + +.. include:: operator/within.txt + :start-after: mongodb + +.. include:: operator/uniqueDocs.txt + :start-after: mongodb + .. index:: query selectors; array .. _query-selectors-array: From b25eecc19c81249e5bb190173ce7696f1dda238e Mon Sep 17 00:00:00 2001 From: kay Date: Mon, 10 Sep 2012 17:09:56 -0400 Subject: [PATCH 2/3] DOCS-484, DOCS-382 Update of the reference operators --- source/includes/note-ref-equality.rst | 9 +-- source/reference/operator/all.txt | 56 ++++++++++------- source/reference/operator/and.txt | 52 ++++++++-------- source/reference/operator/exists.txt | 42 +++++-------- source/reference/operator/gt.txt | 23 ++++--- source/reference/operator/gte.txt | 27 +++++---- source/reference/operator/in.txt | 39 ++++++------ source/reference/operator/lt.txt | 26 +++++--- source/reference/operator/lte.txt | 27 ++++++--- source/reference/operator/mod.txt | 28 ++++++--- source/reference/operator/ne.txt | 26 +++++--- source/reference/operator/nin.txt | 42 +++++++------ source/reference/operator/nor.txt | 56 ++++++++--------- source/reference/operator/not.txt | 86 ++++++++++++++------------- source/reference/operator/or.txt | 76 ++++++++++++++++++----- source/reference/operator/type.txt | 37 ++++++------ 16 files changed, 381 insertions(+), 271 deletions(-) diff --git a/source/includes/note-ref-equality.rst b/source/includes/note-ref-equality.rst index d419a84a95d..b44d77f2dc0 100644 --- a/source/includes/note-ref-equality.rst +++ b/source/includes/note-ref-equality.rst @@ -1,13 +1,10 @@ .. note:: To signify ``equal to`` (``=``), MongoDB defaults to the JSON ``{ - key:value }`` structure. For example, the query + key:value }`` structure. For example, the query: .. code-block:: javascript - db.collection.find( { field: value } ) + db.collection.find( { field: value } ) - selects all the documents where the ``field`` equals ``value``. - - - + selects all the documents where the ``field`` equals ``value``. \ No newline at end of file diff --git a/source/reference/operator/all.txt b/source/reference/operator/all.txt index d2514f7618b..6f4d52aed0d 100644 --- a/source/reference/operator/all.txt +++ b/source/reference/operator/all.txt @@ -6,38 +6,54 @@ $all .. operator:: $all - *Syntax*: ``{ field: { $all: array }`` + *Syntax*: ``{ field: { $all: [ < value1 > , < value2 > ... ] }`` - :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``. + :operator:`$all` selects the documents where the ``field`` is an + array and contains all the ```` in the 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"]``. + For example, you would query: .. code-block:: javascript db.inventory.find( { tags: { $all: [ "appliances", "school" ] } } ) - **Example**: Update a single document in ``inventory`` where - ``tags`` contain all the elements in the array ``["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 first document with ``tags`` equal to ``[ "school", "book", "bag", + "headphone", "appliances" ]`` *and* + - a second document with ``tags`` equal to ``[ "appliances", + "school" ]``, + + the above query will return both documents. + + When used with indexed ``fields``, :operator:`$all` does lookups on + the first element of the index. In the example, ``tags`` is + indexed. Then, :operator:`$all` looks up the documents + + MongoDB :operator:`$all` on a ``field`` that is indexed, + 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.inventory.update( { tags: { $all: [ "appliances", "school" ] } }, { $set: { sale: false } } ) - + .. 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. - See also :method:`find() `, :method:`update() - `, :operator:`$set`. + .. seealso:: + :method:`find() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/and.txt b/source/reference/operator/and.txt index 003bc2f12ec..adb138b98aa 100644 --- a/source/reference/operator/and.txt +++ b/source/reference/operator/and.txt @@ -10,41 +10,45 @@ $and *Syntax*: ``{ $and: [ { }, { } , ... , { } ] }`` - :operator:`$and` performs a logical ``AND`` operation on the - specified array of ```` and selects the + :operator:`$and` performs a logical ``AND`` operation on an array of + *two or more* ```` and selects the documents that satisfy *all* the ```` in the array. - :operator:`$and` requires at least two ````. 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``. + For example, the following query selects 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: + 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 } ) - db.inventory.update( { price: 1.99, qty: { $lt: 20 } , sale: true }, { $set: { qty: 15 } } ) + + 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 can update a single document in ``inventory`` where: + + - ``price`` does not equal ``1.99`` **and** + - ``price`` exists. + + .. code-block:: javascript + + db.inventory.update( { $and: [ { price: { $ne: 1.99 } }, { price: { $exists: true } } ] }, { $set: { qty: 15 } } ) - See also :method:`find() `, :method:`update() - `, :operator:`$set`. + .. seealso:: + + :method:`find() `, :method:`update() + `, :operator:`$ne`, :operator:`$exists`, + :operator:`$set`. \ No newline at end of file diff --git a/source/reference/operator/exists.txt b/source/reference/operator/exists.txt index e55e92d5850..208f7033088 100644 --- a/source/reference/operator/exists.txt +++ b/source/reference/operator/exists.txt @@ -8,35 +8,25 @@ $exists *Syntax*: ``{ field: { $exists: boolean } }`` - :operator:`$exists` selects the documents that contain - the field. - + :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.inventory.find( { sale: { $exists: true } } ) + For example, the following query: - **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.inventory.update( { sale: { $exists: false } }, { $set: { sale: false } } ) - - See also :method:`find() `, :method:`update() - `, :operator:`$set`, :operator:`$and`. + db.inventory.find( { $and: [ { qty: { $exists: true } }, { qty: { $nin: [ 5, 15 ] } } ] } ) + + selects 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. This + is true for all operations and not specific to the :operator:`$exists` + operator. + + .. seealso:: + + :method:`find() `, :operator:`$and`, + :operator:`$nin``. diff --git a/source/reference/operator/gt.txt b/source/reference/operator/gt.txt index acb2bf2150d..e8d6337e158 100644 --- a/source/reference/operator/gt.txt +++ b/source/reference/operator/gt.txt @@ -11,19 +11,26 @@ $gt :operator:`$gt` selects those documents where the ``field`` is greater than (i.e. ``>``) the specified ``value``. - **Example**: Select all documents in ``inventory`` where ``qty`` is - greater than ``20``. + For example, the following query: .. code-block:: javascript db.inventory.find( { qty: { $gt: 20 } } ) - **Example**: Update a single document in ``inventory`` where ``qty`` - is greater than ``20``. + 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, the query: .. code-block:: javascript - db.inventory.update( { qty: { $gt: 20 } }, { $set: { qty: 0 } } ) - - See also :method:`find() `, :method:`update() - `, :operator:`$set`. + db.inventory.update( { "carrier.fee": { $gt: 2 } }, { $set: { price: 9.99 } } ) + + updates a single document in ``inventory`` where the field ``fee`` + from the embedded document ``carrier`` is greater than ``2``. + + .. seealso:: + + :method:`find() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/gte.txt b/source/reference/operator/gte.txt index 51e2779e585..585ef6c87a0 100644 --- a/source/reference/operator/gte.txt +++ b/source/reference/operator/gte.txt @@ -8,22 +8,29 @@ $gte *Syntax*: ``{field: {$gte: value} }`` - :operator:`$gte` selects the documents where the ``field`` is greater than or - equal to (i.e. ``>=``) the specified ``value``. + :operator:`$gte` selects the documents where the ``field`` is + greater than or equal to (i.e. ``>=``) the specified ``value``. - **Example**: Select all documents in ``inventory`` where ``qty`` is - greater than or equal to ``20``. + For example, the following query: .. code-block:: javascript db.inventory.find( { qty: { $gte: 20 } } ) - **Example**: Update a single document in ``inventory`` where ``qty`` - is greater than or equal to ``20``. + 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, the query: .. code-block:: javascript - db.inventory.update( { qty: { $gte: 20 } }, { $set: { qty: 0 } } ) - - See also :method:`find() `, :method:`update() - `, :operator:`$set`. + db.inventory.update( { "carrier.fee": { $gte: 2 } }, { $set: { price: 9.99 } } ) + + updates a single document in ``inventory`` where the field ``fee`` + from the embedded document ``carrier`` is greater than ``2``. + + .. seealso:: + + :method:`find() `, :method:`update() + `, :operator:`$set`. \ No newline at end of file diff --git a/source/reference/operator/in.txt b/source/reference/operator/in.txt index aa25293a2f0..230d0931034 100644 --- a/source/reference/operator/in.txt +++ b/source/reference/operator/in.txt @@ -6,34 +6,35 @@ $in .. operator:: $in - *Syntax*: ``{ field: { $in: array } }`` + *Syntax*: ``{ field: { $in: [, , ... ] } }`` - :operator:`$in` selects the documents where the ``field`` is in the - specified ``array``. + :operator:`$in` selects the documents where the ``field`` equals any + value 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]``. + For example, the query: .. code-block:: javascript 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" ] } } ) - - **Example**: Update a single document in ``inventory`` where any - element of the ``tags`` is in ``["appliances", "school"]``. + selects all documents in ``inventory`` where ``qty`` is either ``5`` or ``15``. + + Although you can write the above query using the :operator:`$or` + operator, :operator:`$in` is preferred over :operator:`$or`. + + 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.inventory.update( { tags: { $in: ["appliances", "school"] } }, { $set: { sale:true } } ) - See also :method:`find() `, :method:`update() - `, :operator:`$set`. \ No newline at end of file + 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() `, :method:`update() + `, :operator:`$or`, :operator:`$set`. diff --git a/source/reference/operator/lt.txt b/source/reference/operator/lt.txt index 3346275e960..f535da35de2 100644 --- a/source/reference/operator/lt.txt +++ b/source/reference/operator/lt.txt @@ -8,21 +8,29 @@ $lt *Syntax*: ``{field: {$lt: value} }`` - :operator:`$lt` selects the documents where the ``field`` is less than - (i.e. ``<``) the specified ``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``. + For example, the following query: .. code-block:: javascript db.inventory.find( { qty: { $lt: 20 } } ) + + select all documents in ``inventory`` where ``qty`` is less than + ``20``. - **Example**: Update a single document in ``inventory`` where ``qty`` is less than ``20``. + You may use the :operator:`$lt` operator to select + fields from embedded documents. For example, the query: .. code-block:: javascript - db.inventory.update( { qty: { $lt: 20 } }, { $set: { qty: 0 } } ) - - See also :method:`find() `, :method:`update() - `, :operator:`$set`. + db.inventory.update( { "carrier.fee": { $lt: 20 } }, { $set: { price: 9.99 } } ) + + updates a single document in ``inventory`` where the field ``fee`` + from the embedded document ``carrier`` is less than ``20``. + + .. seealso:: + + method:`find() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/lte.txt b/source/reference/operator/lte.txt index eb293b3b972..2d39e3d29fb 100644 --- a/source/reference/operator/lte.txt +++ b/source/reference/operator/lte.txt @@ -8,21 +8,30 @@ $lte *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``. + :operator:`$lte` selects the documents where the ``field`` is less + than or equal to (i.e. ``<=``) the specified ``value``. + + For example, the following query: .. code-block:: javascript db.inventory.find( { qty: { $lte: 20 } } ) + + select all documents in ``inventory`` where ``qty`` is less than or + equal to ``20``. - **Example**: Update a single document in ``inventory`` where ``qty`` is less than or equal to ``20``. + You may use the :operator:`$lt` operator to select + fields from embedded documents. For example, the query: .. code-block:: javascript - db.inventory.update( { qty: { $lte: 20 } }, { $set: { qty: 0 } } ) + db.inventory.update( { "carrier.fee": { $lte: 5 } }, { $set: { price: 9.99 } } ) + + updates a single document in ``inventory`` where the field ``fee`` + from the embedded document ``carrier`` is less than or equal to + ``2``. - See also :method:`find() `, :method:`update() - `, :operator:`$set`. + .. seealso:: + + method:`find() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/mod.txt b/source/reference/operator/mod.txt index 3f818050c95..7a78aeacfc0 100644 --- a/source/reference/operator/mod.txt +++ b/source/reference/operator/mod.txt @@ -8,21 +8,33 @@ $mod *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. + :operator:`$mod` selects the documents where the ``field`` divided + by the ``divisor`` has the specified ``remainder``. + + For example, the query: .. code-block:: javascript db.inventory.find( { qty: { $mod: [ 4, 0 ] } } ) - replaces the more expensive + selects all documents in ``inventory`` where the ``qty`` modulo + ``4`` equals 3, such as documents with ``qty`` equal to ``0`` or + ``12``. + + In some cases, you can query using :operator:`$mod` rather than the + more expensive :operator:`$where` operator. So, you can query: + + .. code-block:: javascript + + db.inventory.find( { qty: { $mod: [ 4, 3 ] } } ) + + rather than using the more expensive `$where`: .. code-block:: javascript db.inventory.find( { $where: "this.qty % 4 == 3" } ) - See also :method:`find() `, :operator:`$where` + .. seealso:: + + method:`find() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/ne.txt b/source/reference/operator/ne.txt index 2e935e725e0..e686a38c3cc 100644 --- a/source/reference/operator/ne.txt +++ b/source/reference/operator/ne.txt @@ -9,21 +9,31 @@ $ne *Syntax*: ``{field: {$ne: value} }`` :operator:`$ne` selects the documents where a ``field`` is not equal - (i.e. ``!=``) to the specified ``value``. + (i.e. ``!=``) to the specified ``value``. This includes documents + that do not contain the ``field``. - **Example**: Select all documents in ``inventory`` where ``qty`` does - not equal ``20``. + For example, the following query: .. code-block:: javascript db.inventory.find( { qty: { $ne: 20 } } ) - **Example**: Update a single document in ``inventory`` where ``qty`` - does not equal ``20``. + selects all documents in ``inventory`` where ``qty`` does not equal + ``20``, including those documents that do not contain ``qty``. + + You may use the :operator:`$or` operator to select + fields from embedded documents. + + For example, the query: .. code-block:: javascript - db.inventory.update( { qty: { $ne: 20 } }, { $set: { qty: 20 } } ) + db.inventory.update( { "carrier.state": { $ne: "NY" } }, { $set: { qty: 20 } } ) - See also :method:`find() `, :method:`update() - `, :operator:`$set`. + updates a single document in inventory where the ``"carrier.state"`` does + not equal "NY" or where the "``carrier.state``" does not exist. + + .. seealso:: + + method:`find() `, :method:`update() + `, :operator:`$set`. diff --git a/source/reference/operator/nin.txt b/source/reference/operator/nin.txt index 0be4625d2e7..89da6d0f62d 100644 --- a/source/reference/operator/nin.txt +++ b/source/reference/operator/nin.txt @@ -6,39 +6,37 @@ $nin .. operator:: $nin - *Syntax*: ``{ field: { $nin: array} }`` + *Syntax*: ``{ field: { $nin: [ , ... ]} }`` :operator:`$nin` selects the documents where: - - the ``field`` is not in the specified ``array`` **or** - - the ``field`` does not exist. - If the ``field`` is an array, then ``{ field: { $in: array } }`` is true - **if** no element of the ``field`` is in the ``array``. + - the ``field`` value is not in the specified ``array`` **or** + - the ``field`` does not exist. - **Example**: Select all documents in ``inventory`` where ``qty`` is - not in the array ``[5, 15]`` including the documents that do *not* - contain the ``qty`` field. + For example, the query: .. code-block:: javascript db.inventory.find( { qty: { $nin: [ 5, 15 ] } } ) - **Example**: Select all documents in ``inventory`` where the - elements of the ``tags`` array are *not* in ``["appliances", - "school"]`` including the documents that do not contain the ``tags`` - field. - - .. code-block:: javascript - - db.inventory.find( { tags: { $nin: [ "appliances", "school" ] } } ) + selects all documents in ``inventory`` where ``qty`` does **not** + equal ``5`` nor ``15``. The selected documents will include those + documents that do *not* contain the ``qty`` field. - **Example**: Update a single document in ``inventory`` where the - elements of the ``tags`` array is not in ``["appliances", - "school"]`` or a document that does not contain the field ``tags``. + If the ``field`` is an array, then ``{ field: { $nin: array } }`` is + true **if** no element of the ``field`` is in the ``array``. + For example, the query: + .. code-block:: javascript db.inventory.update( { tags: { $nin: [ "appliances", "school" ] } }, { $set: { sale: false } } ) - - See also :method:`find() `, :method:`update() - `, :operator:`$set`. + + updates a single document in ``inventory`` where **none** of the + elements of the ``tags`` array equals ``appliances`` nor ``school`` + or where a document does not contain the field ``tags``. + + .. seealso:: + + :method:`find() `, :method:`update() + `, :operator:`$set`. \ No newline at end of file diff --git a/source/reference/operator/nor.txt b/source/reference/operator/nor.txt index 48e0e19d744..d1a7a89c921 100644 --- a/source/reference/operator/nor.txt +++ b/source/reference/operator/nor.txt @@ -8,47 +8,38 @@ $nor *Syntax*: ``{ $nor: [ { }, { }, ... { } ] }`` - :operator:`$nor` performs a logical ``NOR`` operation on the specified - array of ```` and selects the documents that + :operator:`$nor` performs a logical ``NOR`` operation on an array of + *two or more* ```` and selects the documents that fail all the ```` in the array. - - :operator:`$nor` requires at least two ````. In the above - syntax, ``N`` must be greater than or equal to 2. - **Example**: Select all documents in ``inventory`` where: - - ``price`` does *not* equal ``1.99`` **and** - - ``qty`` is *not* less than ``20`` **and** - - ``sale`` is *not* ``true`` - - including those documents that do not contain these field(s). + For example, the following query: .. code-block:: javascript db.inventory.find( { $nor: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] } ) - **Example**: Update a single document in ``inventory`` where: + select all documents in ``inventory`` where: + - ``price`` does *not* equal ``1.99`` **and** - - ``qty`` is *not* less than ``20``. - - This may be a document that does not contain these field(s). - - .. code-block:: javascript - - db.inventory.update( { $nor: [ { price: 1.99 }, { qty: 20 } ] }, { $set: {qty: 15} } ) - - A document fails *most* Boolean expressions if the document is - missing the field in the expression. The exception is the expression - ``{ missingField: { $exists: false } }``. The following query + - ``qty`` is *not* less than ``20`` **and** + - ``sale`` is *not* ``true`` + + including those documents that do not contain these field(s). + + The exception in returning documents that do not contain the field + in the `$nor` expression is when the :operator:`$nor` operator is + used with the :operator:`$exists` operator. The following query .. code-block:: javascript db.inventory.find( { $nor: [ { price: 1.99 }, { sale: true } ] } ) - will return all documents that: - - have ``price`` *not* equal to ``1.99`` *and* ``sale`` *is not* ``true`` **or** - - have ``price`` *not* equal to ``1.99`` *and* does *not* contain the ``sale`` field **or** - - does *not* contain the ``price`` field *and* ``sale`` *is not* ``true`` **or** - - does *not* contain the ``price`` field *and* does *not* contain the ``sale`` field + will return all documents that: + + - have ``price`` *not* equal to ``1.99`` *and* ``sale`` *is not* ``true`` **or** + - have ``price`` *not* equal to ``1.99`` *and* does *not* contain the ``sale`` field **or** + - does *not* contain the ``price`` field *and* ``sale`` *is not* ``true`` **or** + - does *not* contain the ``price`` field *and* does *not* contain the ``sale`` field whereas @@ -58,7 +49,10 @@ $nor { sale: true }, { sale: { $exists: false } } ] } ) will return all documents that: - - have ``price`` *not* equal to ``1.99`` *and* ``sale`` *is not* ``true``. + + - have ``price`` *not* equal to ``1.99`` *and* ``sale`` *is not* ``true``. - See also :method:`find() `, :method:`update() - `, :operator:`$set`, :operator:`$exists`. + .. seealso:: + + :method:`find() `, :method:`update() + `, :operator:`$set`, :operator:`$exists`. diff --git a/source/reference/operator/not.txt b/source/reference/operator/not.txt index 4066325c2a2..f9fa8e607bb 100644 --- a/source/reference/operator/not.txt +++ b/source/reference/operator/not.txt @@ -10,56 +10,62 @@ $not :operator:`$not` performs a logical ``NOT`` operation on the specified ```` and selects the documents that - do *not* match the ````. This includes documents that - do not contain the ``field``. + do *not* match the ````. This includes + documents that do not contain the ``field``. - :operator:`$not` only affects *other operators* and cannot - check fields and documents independently. - - Use :operator:`$ne` to test the contents of fields directly and - :operator:`$nor` for logical disjunctions instead. - - **Example**: Select all documents in ``inventory`` where the - ``price`` is *not* greater than ``1.99``. + For example, the following query: .. code-block:: javascript db.inventory.find( { price: { $not: { $gt: 1.99 } } } ) + + selects all documents where: - The query selects all documents where: - - ``price`` is less than or equal to ``1.99`` **or** - - ``price`` does not exist - - ``{ $not: { $gt: 1.99 } }`` is different from the :operator:`$lte` operator. - ``{ $lt: 1.99 }`` returns *only* the documents where ``price`` is less than or equal to ``1.99``. - - The operation of :operator:`$not` is consistent with the behavior of - other operators but may yield unexpected results with some data - types like arrays. + - ``price`` is less than or equal to ``1.99`` **or** + - ``price`` does not exist + + Notice that ``{ $not: { $gt: 1.99 } }`` is different from the + :operator:`$lte` operator. ``{ $lt: 1.99 }`` returns *only* the + documents where ``price`` is less than or equal to ``1.99``. + + Remember that :operator:`$not` only affects *other operators* and + cannot check fields and documents independently. So, use the + :operator:`$not` operator for logical disjunctions and the + :operator:`$ne` operator to test the contents of fields directly. + + Consider the following behaviors when using the :operator:`$or` + operator: + + - The operation of :operator:`$not` is consistent with the behavior + of other operators but may yield unexpected results with some data + types like arrays. - The :operator:`$not` operator does **not** support operations with - :operator:`$regex`. Instead use ``//`` or in your driver interfaces, - use your langauge's regular expression capability to create regular - expression objects. + - The :operator:`$not` operator does **not** support operations with + :operator:`$regex`. Instead use ``//`` or in your driver + interfaces, use your langauge's regular expression capability to + create regular expression objects. - **Example**: Select all documents in ``inventory`` where the - ``item`` does *not* start with the letter ``p`` using the pattern - match operator ``/^p.*/``. + Using the pattern match expression ``//``, the following query: + + .. code-block:: javascript - .. code-block:: javascript + db.inventory.find( { item: { $not: /^p.*/ } } ) - db.inventory.find( { item: { $not: /^p.*/ } } ) + selects all documents in ``inventory`` where the ``item`` does + *not* start with the letter ``p``. - **Example**: Select all documents in ``inventory`` where the - ``item`` does *not* start with the letter ``p`` in PyMongo using - ``re.compile()``. - - .. code-block:: python + If using PyMongo's ``re.compile()``, you can write + the above query as: + + .. code-block:: python - import re - for noMatch in db.inventory.find( { "item": { "$not": re.compile("^p.*") } } ): - print noMatch + import re + for noMatch in db.inventory.find( { "item": { "$not": re.compile("^p.*") } } ): + print noMatch - See also :method:`find() `, :method:`update() - `, :operator:`$set`, :operator:`$gt`, :operator:`$regex`, - :api:`PyMongo `, :term:`driver`. + .. seealso:: + + method:`find() `, :method:`update() + `, :operator:`$set`, :operator:`$gt`, + :operator:`$regex`, :api:`PyMongo `, + :term:`driver`. \ No newline at end of file diff --git a/source/reference/operator/or.txt b/source/reference/operator/or.txt index 49734769802..9cde70eaaa2 100644 --- a/source/reference/operator/or.txt +++ b/source/reference/operator/or.txt @@ -14,32 +14,80 @@ $or *Syntax*: ``{ $or: [ { }, { }, ... , { } ] }`` - :operator:`$or` performs a logical ``OR`` operation on the specified - array of ```` and selects the documents that satisfy + The :operator:`$or` operator performs a logical ``OR`` operation on an array of + *two or more* ```` and selects the documents that satisfy *at least* one of the ````. - - The :operator:`$or` requires at least two ````. In the above - syntax, ``N`` must be greater than or equal to 2. - **Examples**: Select all documents in ``inventory`` where: - - ``price`` equals ``1.99`` **and** - - **(** ``qty`` is less than ``20`` **or** ``sale`` is `true` **)**. + For example, the following query selects all documents in ``inventory`` where: + + - ``price`` equals ``1.99`` **and** + - either ``qty`` is less than ``20`` *or* ``sale`` is ``true``. .. code-block:: javascript db.inventory.find( { price:1.99, $or: [ { qty: { $lt: 20 } }, { sale: true } ] } ) - // or using the $and command + You could also write the same query using the explicit :operator:`$and` operator as: + + .. code-block:: javascript db.inventory.find( { $and: [ {price:1.99}, { $or: [ { qty: { $lt: 20 } }, { sale: true } ] } ] } ) - **Example**: Update a single document in ``inventory`` where + Additionally, you may use the :operator:`$or` operator to select + fields from embedded documents. + + For example, the following query updates a single document in + ``inventory`` where: + - ``price`` equals ``1.99`` **or** - - ``qty`` is less than ``20``. + - ``carrier.state`` equals ``NY``. .. code-block:: javascript - db.inventory.update( { $or: [ { price: 1.99 }, { qty: { $lt: 20 } } ] }, { $set: { qty: 15 } } ) + db.inventory.update( { $or: [ { price:10.99 }, { "carrier.state": "NY"} ] }, { $set: { sale: true } } ) + + When using :operator:`$or` with ```` that are + equality checks for the **same** key, using :operator:`$in` is + preferred over :operator:`$or`. + + For example, to select all documents in ``inventory`` where: + + - either ``price`` equals ``1.99`` *or* ``sale`` is ``true``, **and** + - either ``qty`` equals ``20`` *or* ``qty`` equals ``50``, + + the most effective query would be: + + .. code-block:: javascript + + db.inventory.find ( { $or: [ { price: 1.99 }, { sale: true } ], qty: { $in: [20, 50] } } ) + + Consider the following behaviors when using the :operator:`$or` + operator: + + - When using indexes with :operator:`$or` queries, remember that + each clause of an :operator:`$or` query will execute in parallel. + These clauses can each use their own index. This means that for + the query: + + .. code-block:: javascript + + db.inventory.find ( { $or: [ { price: 1.99 }, { sale: true } ] } ) + + you would create one index on ``price`` + ( ``db.inventory.ensureIndex( { price: 1 } )`` ) and another index on + ``sale`` ( ``db.inventory.ensureIndex( { sale: 1 } )`` ) + rather than a compound index. + + - Also, when using :operator:`$or` with :method:`sort() + ` in a query, the query will *not* use the indexes + on the :operator:`$or` fields. So, the above query: + + .. code-block:: javascript + + db.inventory.find ( { $or: [ { price: 1.99 }, { sale: true } ] } ).sort({item:1}) + + will not use the index on ``price`` nor the index on ``sale``. - See also :method:`find() `, :method:`update() - `, :operator:`$set`, :operator:`$and`. + .. seealso:: :method:`find() `, + :method:`update() `, :operator:`$set`, + :operator:`$and`, :method:`sort() `. diff --git a/source/reference/operator/type.txt b/source/reference/operator/type.txt index f399cf6f99c..6da6979b9c0 100644 --- a/source/reference/operator/type.txt +++ b/source/reference/operator/type.txt @@ -11,28 +11,29 @@ $type :operator:`$type` selects the documents where the *value* of the ``field`` is the specified :term:`BSON` type. - **Example**: Select all documents in ``inventory`` where the value - of ``price`` is a Double. - + For example, the query: + .. code-block:: javascript - db.inventory.find( { price: { $type : 1 } } ) + db.inventory.find( { price: { $type : 1 } } ) + selects all documents in ``inventory`` where the value of ``price`` + is a Double. + If the field is an array, :operator:`$type` operates on the array elements and **not** the field value as a whole. - **Example**: Select all documents in ``inventory`` where the - ``tags`` array contains an element that is of type array. + So, the query: .. code-block:: javascript db.inventory.find( { tags: { $type : 4 } } ) - To determine whether the field is an array, use the - :operator:`$where` operator. - - **Example**: Select all documents in ``inventory`` where ``tags`` is - of type array. + selects all documents in ``inventory`` where the ``tags`` array + contains an element that is of ``array`` type. + + If instead you want to determine whether the ``tags`` is an array + type, use the :operator:`$where` operator: .. code-block:: javascript @@ -40,15 +41,14 @@ $type See the :issue:`SERVER-1475` for more information about the array type. - - Refer to the following table for the - available :term:`BSON` types and their corresponding numbers. + Refer to the following table for the available :term:`BSON` types + and their corresponding numbers. ======================= ========== **Type** **Number** ----------------------- ---------- - Double 1 + Double 1 String 2 Object 3 Array 4 @@ -115,5 +115,8 @@ $type .. include:: /includes/warning-mixing-types.rst - See also :method:`find() `, :method:`insert() - `, :operator:`$where`, :term:`BSON`, :term:`shard key`, :term:`shard cluster` . \ No newline at end of file + .. seealso:: + + :method:`find() `, :method:`insert() + `, :operator:`$where`, :term:`BSON`, + :term:`shard key`, :term:`shard cluster` . From 8950a132ae7fbccfd81fc50a6c189906d7ddcfdd Mon Sep 17 00:00:00 2001 From: kay Date: Mon, 10 Sep 2012 22:39:57 -0400 Subject: [PATCH 3/3] DOCS-484, DOCS-382 Update of the operators reference documentation --- source/reference/operator/all.txt | 10 ++------- source/reference/operator/and.txt | 22 ++++++++++++-------- source/reference/operator/exists.txt | 18 ++++++++-------- source/reference/operator/gt.txt | 10 ++++----- source/reference/operator/gte.txt | 10 ++++----- source/reference/operator/in.txt | 16 +++++++------- source/reference/operator/lt.txt | 10 ++++----- source/reference/operator/lte.txt | 10 ++++----- source/reference/operator/mod.txt | 6 +++--- source/reference/operator/ne.txt | 15 +++++++------- source/reference/operator/nin.txt | 8 +++---- source/reference/operator/nor.txt | 16 +++++++------- source/reference/operator/not.txt | 11 +++++----- source/reference/operator/or.txt | 31 ++++++++++++---------------- source/reference/operator/type.txt | 4 ++-- source/reference/operators.txt | 1 - 16 files changed, 96 insertions(+), 102 deletions(-) diff --git a/source/reference/operator/all.txt b/source/reference/operator/all.txt index 6f4d52aed0d..5af5a826b53 100644 --- a/source/reference/operator/all.txt +++ b/source/reference/operator/all.txt @@ -20,19 +20,13 @@ $all to select all documents in ``inventory`` where ``tags`` contains all the elements in the array ``[ "appliances", "school" ]``. So, in the case of: - - a first document with ``tags`` equal to ``[ "school", "book", "bag", + - a document with ``tags`` equal to ``[ "school", "book", "bag", "headphone", "appliances" ]`` *and* - - a second document with ``tags`` equal to ``[ "appliances", + - a document with ``tags`` equal to ``[ "appliances", "school" ]``, the above query will return both documents. - - When used with indexed ``fields``, :operator:`$all` does lookups on - the first element of the index. In the example, ``tags`` is - indexed. Then, :operator:`$all` looks up the documents - MongoDB :operator:`$all` on a ``field`` that is indexed, - Although :operator:`$all` is most meaningful when queried against an array ``field``, you can use :operator:`$all` to query against a non-array ``field``. diff --git a/source/reference/operator/and.txt b/source/reference/operator/and.txt index adb138b98aa..9efee7e8b2c 100644 --- a/source/reference/operator/and.txt +++ b/source/reference/operator/and.txt @@ -14,16 +14,18 @@ $and *two or more* ```` and selects the documents that satisfy *all* the ```` in the array. - For example, the following query selects all documents in ``inventory`` where: + For example, you would query: + + .. code-block:: javascript + + db.inventory.find({ $and: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] } ) + + to 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 } ] } ) - MongoDB provides an implicit ``AND`` operation when specifying a comma separated list of expressions. For example, you can write the above query as: @@ -36,15 +38,17 @@ $and 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 can update a single document in ``inventory`` where: - - - ``price`` does not equal ``1.99`` **and** - - ``price`` exists. + 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() `, :method:`update() diff --git a/source/reference/operator/exists.txt b/source/reference/operator/exists.txt index 208f7033088..0d677b3192a 100644 --- a/source/reference/operator/exists.txt +++ b/source/reference/operator/exists.txt @@ -10,23 +10,23 @@ $exists :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`. + ``exists``. For SQL ``exists``, refer to the :operator:`$in` + operator. - For example, the following query: + For example, you would query: .. code-block:: javascript db.inventory.find( { $and: [ { qty: { $exists: true } }, { qty: { $nin: [ 5, 15 ] } } ] } ) - selects all documents in ``inventory`` where ``qty`` exists *and* does + 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. This - is true for all operations and not specific to the :operator:`$exists` - operator. + performs an ``AND`` operation on the value of a single field and is + not specific to the :operator:`$exists` operator. - .. seealso:: + .. seealso:: - :method:`find() `, :operator:`$and`, - :operator:`$nin``. + :method:`find() `, :operator:`$and`, + :operator:`$nin``, :operator:`$in``. diff --git a/source/reference/operator/gt.txt b/source/reference/operator/gt.txt index e8d6337e158..2bbe8f07b24 100644 --- a/source/reference/operator/gt.txt +++ b/source/reference/operator/gt.txt @@ -11,23 +11,23 @@ $gt :operator:`$gt` selects those documents where the ``field`` is greater than (i.e. ``>``) the specified ``value``. - For example, the following query: + For example, you would query: .. code-block:: javascript db.inventory.find( { qty: { $gt: 20 } } ) - select all documents in ``inventory`` where ``qty`` is greater than + 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, the query: + 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 } } ) - updates a single document in ``inventory`` where the field ``fee`` + to update a single document in ``inventory`` where the field ``fee`` from the embedded document ``carrier`` is greater than ``2``. .. seealso:: diff --git a/source/reference/operator/gte.txt b/source/reference/operator/gte.txt index 585ef6c87a0..8d36bd798c9 100644 --- a/source/reference/operator/gte.txt +++ b/source/reference/operator/gte.txt @@ -11,23 +11,23 @@ $gte :operator:`$gte` selects the documents where the ``field`` is greater than or equal to (i.e. ``>=``) the specified ``value``. - For example, the following query: + For example, you would query: .. code-block:: javascript db.inventory.find( { qty: { $gte: 20 } } ) - select all documents in ``inventory`` where ``qty`` is greater than + 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, the query: + 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 } } ) - updates a single document in ``inventory`` where the field ``fee`` + to update a single document in ``inventory`` where the field ``fee`` from the embedded document ``carrier`` is greater than ``2``. .. seealso:: diff --git a/source/reference/operator/in.txt b/source/reference/operator/in.txt index 230d0931034..f0e122dc9bf 100644 --- a/source/reference/operator/in.txt +++ b/source/reference/operator/in.txt @@ -11,21 +11,23 @@ $in :operator:`$in` selects the documents where the ``field`` equals any value in the specified ``array``. - For example, the query: + For example, you would query: .. code-block:: javascript db.inventory.find( { qty: { $in: [ 5, 15 ] } } ) - selects all documents in ``inventory`` where ``qty`` is either ``5`` or ``15``. + to select all documents in ``inventory`` where ``qty`` is either ``5`` or ``15``. - Although you can write the above query using the :operator:`$or` - operator, :operator:`$in` is preferred over :operator:`$or`. + 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 + For example, the query: + .. code-block:: javascript db.inventory.update( { tags: { $in: ["appliances", "school"] } }, { $set: { sale:true } } ) @@ -36,5 +38,5 @@ $in .. seealso:: - method:`find() `, :method:`update() - `, :operator:`$or`, :operator:`$set`. + method:`find() `, :method:`update() + `, :operator:`$or`, :operator:`$set`. diff --git a/source/reference/operator/lt.txt b/source/reference/operator/lt.txt index f535da35de2..764e71e3d48 100644 --- a/source/reference/operator/lt.txt +++ b/source/reference/operator/lt.txt @@ -11,23 +11,23 @@ $lt :operator:`$lt` selects the documents where the ``field`` is less than (i.e. ``<``) the specified ``value``. - For example, the following query: + For example, you would query: .. code-block:: javascript db.inventory.find( { qty: { $lt: 20 } } ) - select all documents in ``inventory`` where ``qty`` is less than + to select all documents in ``inventory`` where ``qty`` is less than ``20``. - You may use the :operator:`$lt` operator to select - fields from embedded documents. For example, the query: + 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 } } ) - updates a single document in ``inventory`` where the field ``fee`` + to update a single document in ``inventory`` where the field ``fee`` from the embedded document ``carrier`` is less than ``20``. .. seealso:: diff --git a/source/reference/operator/lte.txt b/source/reference/operator/lte.txt index 2d39e3d29fb..1a916279b6b 100644 --- a/source/reference/operator/lte.txt +++ b/source/reference/operator/lte.txt @@ -11,23 +11,23 @@ $lte :operator:`$lte` selects the documents where the ``field`` is less than or equal to (i.e. ``<=``) the specified ``value``. - For example, the following query: + For example, you would query: .. code-block:: javascript db.inventory.find( { qty: { $lte: 20 } } ) - select all documents in ``inventory`` where ``qty`` is less than or + to select all documents in ``inventory`` where ``qty`` is less than or equal to ``20``. - You may use the :operator:`$lt` operator to select - fields from embedded documents. For example, the query: + 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": { $lte: 5 } }, { $set: { price: 9.99 } } ) - updates a single document in ``inventory`` where the field ``fee`` + to update a single document in ``inventory`` where the field ``fee`` from the embedded document ``carrier`` is less than or equal to ``2``. diff --git a/source/reference/operator/mod.txt b/source/reference/operator/mod.txt index 7a78aeacfc0..ce88bdb957a 100644 --- a/source/reference/operator/mod.txt +++ b/source/reference/operator/mod.txt @@ -11,14 +11,14 @@ $mod :operator:`$mod` selects the documents where the ``field`` divided by the ``divisor`` has the specified ``remainder``. - For example, the query: + For example, you would query: .. code-block:: javascript db.inventory.find( { qty: { $mod: [ 4, 0 ] } } ) - selects all documents in ``inventory`` where the ``qty`` modulo - ``4`` equals 3, such as documents with ``qty`` equal to ``0`` or + to select all documents in ``inventory`` where the ``qty`` modulo + ``4`` equals ``3``, such as documents with ``qty`` equal to ``0`` or ``12``. In some cases, you can query using :operator:`$mod` rather than the diff --git a/source/reference/operator/ne.txt b/source/reference/operator/ne.txt index e686a38c3cc..1e1ba445603 100644 --- a/source/reference/operator/ne.txt +++ b/source/reference/operator/ne.txt @@ -12,26 +12,25 @@ $ne (i.e. ``!=``) to the specified ``value``. This includes documents that do not contain the ``field``. - For example, the following query: + For example, you would query: .. code-block:: javascript db.inventory.find( { qty: { $ne: 20 } } ) - selects all documents in ``inventory`` where ``qty`` does not equal + to select all documents in ``inventory`` where ``qty`` does not equal ``20``, including those documents that do not contain ``qty``. - You may use the :operator:`$or` operator to select - fields from embedded documents. - - For example, the query: + You may use the :operator:`$ne` operator to select fields from + embedded documents. For example, you would query: .. code-block:: javascript db.inventory.update( { "carrier.state": { $ne: "NY" } }, { $set: { qty: 20 } } ) - updates a single document in inventory where the ``"carrier.state"`` does - not equal "NY" or where the "``carrier.state``" does not exist. + to update a single document in inventory where the the field ``state`` + from the embedded document ``carrier`` does not equal "NY" or where the + the field does not exist. .. seealso:: diff --git a/source/reference/operator/nin.txt b/source/reference/operator/nin.txt index 89da6d0f62d..7b8ebfa9573 100644 --- a/source/reference/operator/nin.txt +++ b/source/reference/operator/nin.txt @@ -13,26 +13,26 @@ $nin - the ``field`` value is not in the specified ``array`` **or** - the ``field`` does not exist. - For example, the query: + For example, you would query: .. code-block:: javascript db.inventory.find( { qty: { $nin: [ 5, 15 ] } } ) - selects all documents in ``inventory`` where ``qty`` does **not** + to select all documents in ``inventory`` where ``qty`` does **not** equal ``5`` nor ``15``. The selected documents will include those documents that do *not* contain the ``qty`` field. If the ``field`` is an array, then ``{ field: { $nin: array } }`` is true **if** no element of the ``field`` is in the ``array``. - For example, the query: + For example, you would query: .. code-block:: javascript db.inventory.update( { tags: { $nin: [ "appliances", "school" ] } }, { $set: { sale: false } } ) - updates a single document in ``inventory`` where **none** of the + to update a single document in ``inventory`` where **none** of the elements of the ``tags`` array equals ``appliances`` nor ``school`` or where a document does not contain the field ``tags``. diff --git a/source/reference/operator/nor.txt b/source/reference/operator/nor.txt index d1a7a89c921..ba0ea6a9951 100644 --- a/source/reference/operator/nor.txt +++ b/source/reference/operator/nor.txt @@ -12,23 +12,23 @@ $nor *two or more* ```` and selects the documents that fail all the ```` in the array. - For example, the following query: + For example, you would query: .. code-block:: javascript db.inventory.find( { $nor: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] } ) - select all documents in ``inventory`` where: + to select all documents in ``inventory`` where: - - ``price`` does *not* equal ``1.99`` **and** - - ``qty`` is *not* less than ``20`` **and** - - ``sale`` is *not* ``true`` + - ``price`` does *not* equal ``1.99`` **and** + - ``qty`` is *not* less than ``20`` **and** + - ``sale`` is *not* ``true`` including those documents that do not contain these field(s). The exception in returning documents that do not contain the field - in the `$nor` expression is when the :operator:`$nor` operator is - used with the :operator:`$exists` operator. The following query + in the :operator:`$nor` expression is when the :operator:`$nor` operator is + used with the :operator:`$exists` operator. The following query: .. code-block:: javascript @@ -41,7 +41,7 @@ $nor - does *not* contain the ``price`` field *and* ``sale`` *is not* ``true`` **or** - does *not* contain the ``price`` field *and* does *not* contain the ``sale`` field - whereas + whereas .. code-block:: javascript diff --git a/source/reference/operator/not.txt b/source/reference/operator/not.txt index f9fa8e607bb..df7ae3b65e1 100644 --- a/source/reference/operator/not.txt +++ b/source/reference/operator/not.txt @@ -13,13 +13,13 @@ $not do *not* match the ````. This includes documents that do not contain the ``field``. - For example, the following query: + For example, you would query: .. code-block:: javascript db.inventory.find( { price: { $not: { $gt: 1.99 } } } ) - selects all documents where: + to select all documents where: - ``price`` is less than or equal to ``1.99`` **or** - ``price`` does not exist @@ -33,7 +33,7 @@ $not :operator:`$not` operator for logical disjunctions and the :operator:`$ne` operator to test the contents of fields directly. - Consider the following behaviors when using the :operator:`$or` + Consider the following behaviors when using the :operator:`$not` operator: - The operation of :operator:`$not` is consistent with the behavior @@ -45,13 +45,14 @@ $not interfaces, use your langauge's regular expression capability to create regular expression objects. - Using the pattern match expression ``//``, the following query: + For example, using the pattern match expression ``//``, you would + query: .. code-block:: javascript db.inventory.find( { item: { $not: /^p.*/ } } ) - selects all documents in ``inventory`` where the ``item`` does + to select all documents in ``inventory`` where the ``item`` does *not* start with the letter ``p``. If using PyMongo's ``re.compile()``, you can write diff --git a/source/reference/operator/or.txt b/source/reference/operator/or.txt index 9cde70eaaa2..c238bbb5862 100644 --- a/source/reference/operator/or.txt +++ b/source/reference/operator/or.txt @@ -18,34 +18,29 @@ $or *two or more* ```` and selects the documents that satisfy *at least* one of the ````. - For example, the following query selects all documents in ``inventory`` where: + For example, the you would query: - - ``price`` equals ``1.99`` **and** - - either ``qty`` is less than ``20`` *or* ``sale`` is ``true``. - .. code-block:: javascript db.inventory.find( { price:1.99, $or: [ { qty: { $lt: 20 } }, { sale: true } ] } ) - You could also write the same query using the explicit :operator:`$and` operator as: - - .. code-block:: javascript - - db.inventory.find( { $and: [ {price:1.99}, { $or: [ { qty: { $lt: 20 } }, { sale: true } ] } ] } ) - - Additionally, you may use the :operator:`$or` operator to select - fields from embedded documents. + to select all documents in ``inventory`` where: - For example, the following query updates a single document in - ``inventory`` where: + - ``price`` equals ``1.99`` **and** + - either ``qty`` is less than ``20`` *or* ``sale`` is ``true``. - - ``price`` equals ``1.99`` **or** - - ``carrier.state`` equals ``NY``. + Additionally, you may use the :operator:`$or` operator to select + fields from embedded documents. For example, you would query: .. code-block:: javascript db.inventory.update( { $or: [ { price:10.99 }, { "carrier.state": "NY"} ] }, { $set: { sale: true } } ) + to update a single document in ``inventory`` where: + + - ``price`` equals ``1.99`` **or** + - ``carrier.state`` equals ``NY``. + When using :operator:`$or` with ```` that are equality checks for the **same** key, using :operator:`$in` is preferred over :operator:`$or`. @@ -69,9 +64,9 @@ $or These clauses can each use their own index. This means that for the query: - .. code-block:: javascript + .. code-block:: javascript - db.inventory.find ( { $or: [ { price: 1.99 }, { sale: true } ] } ) + db.inventory.find ( { $or: [ { price: 1.99 }, { sale: true } ] } ) you would create one index on ``price`` ( ``db.inventory.ensureIndex( { price: 1 } )`` ) and another index on diff --git a/source/reference/operator/type.txt b/source/reference/operator/type.txt index 6da6979b9c0..2cbeda239c1 100644 --- a/source/reference/operator/type.txt +++ b/source/reference/operator/type.txt @@ -11,13 +11,13 @@ $type :operator:`$type` selects the documents where the *value* of the ``field`` is the specified :term:`BSON` type. - For example, the query: + For example, you would query: .. code-block:: javascript db.inventory.find( { price: { $type : 1 } } ) - selects all documents in ``inventory`` where the value of ``price`` + to select all documents in ``inventory`` where the value of ``price`` is a Double. If the field is an array, :operator:`$type` operates diff --git a/source/reference/operators.txt b/source/reference/operators.txt index 0591a719b2f..eba6c7e91ac 100644 --- a/source/reference/operators.txt +++ b/source/reference/operators.txt @@ -104,7 +104,6 @@ Element .. include:: operator/type.txt :start-after: mongodb - .. include:: operator/mod.txt :start-after: mongodb