DOCS-799 Port mongo query language wiki

Author: kay-kim

source/administration/indexes.txt

@@ -44,7 +44,7 @@ all documents in a collection for documents that match the query.
       db.records.find( { user_id: 2 } )
 
    However, the following query, on the ``profile_url`` field is not
-   supported by this index::
+   supported by this index:
 
    .. code-block:: javascript
 

source/core/read-operations.txt

@@ -34,7 +34,7 @@ In the :program:`mongo` shell, the :method:`find()
 <db.collection.find()>` and :method:`findOne()
 <db.collection.findOne()>` methods perform read operations. The
 :method:`find() <db.collection.find()>` method has the following
-syntax:
+syntax [#formal-query-structure]_:
 
 .. code-block:: javascript
 
@@ -69,7 +69,7 @@ syntax:
   necessarily consistent unless you specify a sort (:method:`sort()
   <cursor.sort()>`).
 
-For example, the following operation on the ``inventory`` collection,
+For example, the following operation on the ``inventory`` collection
 selects all documents where the ``type`` field equals ``'food'`` and
 the ``price`` field has a value less than ``9.95``. The projection
 limits the response to the ``item`` and ``qty``, and ``_id`` field:
@@ -93,6 +93,20 @@ For additional documentation and examples of the main MongoDB read
 operators, refer to the :doc:`/applications/read` page of the
 :doc:`/crud` section.
 
+.. [#formal-query-structure]
+   :method:`db.collection.find( \<query\>, \<projection\> )
+   <db.collection.find()>` is a wrapper for the more formal query
+   structure with the :operator:`$query` operator:
+
+   .. code-block:: javascript
+
+      db.collection.find( { $query: <query>, ... }, <projection> )
+
+   Within the formal structure, in addition to the :operator:`$query`
+   operator, you can use the :doc:`meta query operators
+   </reference/meta-query-operators>` to modify the behavior of the
+   query.
+
 .. _read-operations-query-document:
 .. _read-operations-query-argument:
 
@@ -411,7 +425,7 @@ the query used an index. This query:
 - returned 5 documents, as indicated by the :data:`n` field;
 
 - scanned 5 documents from the index, as indicated by the
-  :data:`nscanned`` field;
+  :data:`nscanned` field;
 
 - then read 5 full documents from the collection, as indicated by
   the :data:`nscannedObjects` field.

source/reference/meta-query-operators.txt

@@ -13,23 +13,26 @@ In addition to the :doc:`MongoDB Query Operators
 </reference/operators>`, there are a number of "meta" operators that
 you may use to modify the output or behavior of a
 query. Specify these modifiers to a :method:`db.collection.find()` query, in the
-following form (for the :program:`mongo` shell):
+following forms (for the :program:`mongo` shell):
 
 .. code-block:: javascript
 
-   db.collection.find( { [QUERY] } )._addSpecial( [MODIFIER] )
-
-Here, the query specified by ``[QUERY]`` runs on the collection
-named ``collection`` with the operation specified by the
-``[MODIFIER]``. The results are then processed by a modifier expression
-selected from the following list. Many of the operators have
-corresponding :doc:`methods in the shell </reference/javascript>`. For
-the proposes of this reference, this document assumes the above form
-where possible.
+   db.collection.find( { <QUERY> } )._addSpecial( <MODIFIER> )
+   db.collection.find( { $query: { <QUERY> }, <MODIFIER> } )
+ 
+Here, the query specified by ``<QUERY>`` runs on the collection named
+``collection`` with the operation specified by the ``<MODIFIER>``. The
+results are then processed by a modifier expression selected from the
+following list. MongoDB treats the query and the
+modifiers as a single object, with the :operator:`$query` and the meta
+operators included in a single document.
 
 Modifiers
 ---------
 
+Many of the operators have corresponding :doc:`methods
+in the shell </reference/javascript>`. 
+
 .. include:: operator/returnKey.txt
    :start-after: mongodb
 
@@ -42,6 +45,9 @@ Modifiers
 .. include:: operator/comment.txt
    :start-after: mongodb
 
+.. include:: operator/max.txt
+   :start-after: mongodb
+   
 .. include:: operator/min.txt
    :start-after: mongodb
 

source/reference/operator/comment.txt

@@ -7,13 +7,12 @@ $comment
 .. operator:: $comment
 
    The :operator:`$comment` makes it possible to attach a comment to a
-   query. Because these comments propagate to the
-   :dbcommand:`profile` log, adding :operator:`$comment` modifiers can
-   make your profile data much easier to interpret and trace. Consider
-   the following example:
+   query. Because these comments propagate to the :dbcommand:`profile`
+   log, adding :operator:`$comment` modifiers can make your profile
+   data much easier to interpret and trace. Use one of the following
+   forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$comment" , "[COMMENT]" )
-
-   Here, ``[COMMENT]`` represents the text of the comment.
+      db.collection.find( { <QUERY> } )._addSpecial( "$comment", <comment to add> )
+      db.collection.find( { $query: { <QUERY> }, $comment: <comment to add> } )

source/reference/operator/explain.txt

@@ -6,14 +6,19 @@ $explain
 
 .. operator:: $explain
 
-   Use the :operator:`$explain` operator to return a :term:`document`
-   that describes the process and indexes used to return the
-   query. This may provide useful insight when attempting to optimize
-   a query. Consider the following example:
+   :operator:`$explain` operator provides information on the query
+   plan. It returns a :ref:`document <explain-output>` that describes
+   the process and indexes used to return the query. This may provide
+   useful insight when attempting to optimize a query.
+
+   Retrieve the query plan by adding the :operator:`$explain` operator
+   to a :method:`find() <db.collection.find()>` query, as in the
+   following examples:
 
    .. code-block:: javascript
 
        db.collection.find()._addSpecial( "$explain", 1 )
+       db.collection.find( { $query: {}, $explain: 1 } )
 
    The JavaScript function :method:`cursor.explain()` provides equivalent
    functionality in the :program:`mongo` shell. See the following

source/reference/operator/hint.txt

@@ -9,13 +9,21 @@ $hint
    Use the :operator:`$hint` operator to force the query optimizer to
    use a specific index to fulfill the query.  Use :operator:`$hint`
    for testing query performance and indexing strategies. Consider
-   the following form:
+   the following operations:
 
    .. code-block:: javascript
 
        db.collection.find()._addSpecial( "$hint", { _id : 1 } )
+       db.collection.find( { $query: {}, $hint: { _id : 1 } } )
 
-   This operation returns all documents in the collection named
+   These are equivalent to the following :method:`cursor.hint()` method that
+   may be more familiar to you:
+
+   .. code-block:: javascript
+
+      db.collection.find().hint( { _id: 1 } )
+
+   These operations return all documents in the collection named
    ``collection`` using the index on the ``_id`` field. Use this
    operator to override MongoDB's default index selection process and
    pick indexes manually.

source/reference/operator/max.txt

@@ -6,22 +6,34 @@ $max
 
 .. operator:: $max
 
-   Specify a :operator:`$max` value to specify an upper boundary for
-   the value of a field. :program:`mongod` enforces this boundary with
-   an index of that field.
+   Specify a :operator:`$max` value to specify the *exclusive* upper
+   bound for a specific index in order to constrain the results of
+   :method:`find() <db.collection.find()>`. Consider the following
+   operations on a collection named ``collection`` that has an index
+   ``{ age: 1 }``:
 
    .. code-block:: javascript
 
-       db.collection.find()._addSpecial("$max" , { value : 100 })
+       db.collection.find()._addSpecial( "$max", { age : 100 } )
+       db.collection.find( { $query: {}, $max: { age: 100 } } )
 
-   This operation above limits the documents returned to those that
-   match the query described by ``[QUERY]`` where the field
-   ``value`` is less than ``20``. :program:`mongod` infers the
-   index based on on the ``query`` unless specified by the
-   :method:`cursor.hint()` function.
+   These are equivalent to the following :method:`cursor.max()` method that
+   may be more familiar to you:
+
+   .. code-block:: javascript
+
+      db.collection.find().max( { age: 100 } )
+      
+   This operation above limits the query to those documents where the
+   field ``age`` is less than ``100`` using the index ``{ age: 1 }``.
+   You can explicitly specify the particular index with the
+   :operator:`$hint`. Otherwise, MongoDB selects the index using the
+   fields in the ``indexbounds``; however, if multiple indexes exist on
+   same fields with different sort orders, the selection of the index
+   may be ambiguous.
 
    Use operation alone or in conjunction with :operator:`$min`
-   to limit results to a specific range.
+   to limit results to a specific range for the same index.
 
    .. note::
 

source/reference/operator/maxScan.txt

@@ -7,11 +7,12 @@ $maxScan
 .. operator:: $maxScan
 
    Constrains the query to only scan the specified number of documents
-   when fulfilling the query. Use the following form:
+   when fulfilling the query. Use one of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$maxScan" , 50 )
+      db.collection.find( { <QUERY> } )._addSpecial( "$maxScan" , <number> )
+      db.collection.find( { $query: { <QUERY> }, $maxScan: <number> } )
 
    Use this modifier to prevent potentially long running queries from
    disrupting performance by scanning through too much data.

source/reference/operator/min.txt

@@ -6,22 +6,34 @@ $min
 
 .. operator:: $min
 
-   Specify a :operator:`$min` value to specify a lower boundary for
-   the value of a field. :program:`mongod` enforces this boundary with
-   an index of the field.
+   Specify a :operator:`$min` value to specify the *inclusive* lower
+   bound for a specific index in order to constrain the results of
+   :method:`find() <db.collection.find()>`. Consider the following
+   operations on a collection named ``collection`` that has an index
+   ``{ age: 1 }``:
 
    .. code-block:: javascript
 
-      db.collection.find( { [QUERY] } )._addSpecial("$min" , { value : 20})
+      db.collection.find()._addSpecial("$min" , { age : 20 } )
+      db.collection.find( { $query: {}, $min: { age: 20 } } )
 
-   This operation above limits the documents returned to those that
-   match the query described by ``[QUERY]`` where the field
-   ``value`` is at least ``20``. :program:`mongod` infers the
-   index based on the ``query`` unless specified by the
-   :method:`cursor.hint()` function.
+   These are equivalent to the following :method:`cursor.min()` method that
+   may be more familiar to you:
 
-   Use operation alone or in conjunction with :operator:`$max`
-   to limit results to a specific range.
+   .. code-block:: javascript
+
+      db.collection.find().min( { age: 20 } )
+      
+   These operations limits the query to those documents where the field
+   ``age`` is at least ``20`` using the index ``{ age: 1 }``. You can
+   explicitly specify the particular index with :operator:`$hint`.
+   Otherwise, MongoDB selects the index using the fields in the
+   ``indexbounds``; however, if multiple indexes exist on same fields
+   with different sort orders, the selection of the index may be
+   ambiguous.
+
+   Use operation alone or in conjunction with :operator:`$max` to limit
+   results to a specific range for the same index.
 
    .. note::
 

source/reference/operator/orderby.txt

@@ -7,28 +7,31 @@ $orderby
 .. operator:: $orderby
 
    The :operator:`$orderby` operator sorts the results of a query in
-   ascending or descending order. Consider the following syntax:
+   ascending or descending order. Consider the following operations:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$orderby", { age : -1} )
+      db.collection.find()._addSpecial( "$orderby", { age : -1 } )
+      db.collection.find( { $query: {}, $orderby: { age : -1 } } )
 
-   This is equivalent to the following :method:`cursor.sort()` method that
+   These are equivalent to the following :method:`cursor.sort()` method that
    may be more familiar to you:
 
    .. code-block:: javascript
 
       db.collection.find().sort( { age: -1 } )
 
-   Both of these examples return all documents in the collection named
-   ``collection`` sorted for in descending order from greatest to
-   smallest. Specify a value to :operator:`$orderby` of negative one
-   (e.g. ``-1``, as above) to sort in descending order or a positive
-   value (e.g. ``1``) to sort in ascending order.
+   These examples return all documents in the collection named
+   ``collection`` sorted by the ``age`` field in descending order.
+   Specify a value to :operator:`$orderby` of negative one (e.g.
+   ``-1``, as above) to sort in descending order or a positive value
+   (e.g. ``1``) to sort in ascending order.
 
    Unless you have a index for the specified key pattern, use
    :operator:`$orderby` in conjunction with :operator:`$maxScan` and/or
    :method:`cursor.limit()` to avoid requiring MongoDB to perform a large
    in-memory sort. :method:`cursor.limit()` increases the speed and reduce
    the amount of memory required to return this query by way of an
    optimized algorithm.
+   
+   .. seealso:: :operator:`$query` operator

source/reference/operator/query.txt

@@ -7,15 +7,18 @@ $query
 .. operator:: $query
 
    The :operator:`$query` operator provides an interface to describe
-   queries. Consider the following operation.
+   queries. Consider the following operation:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial( "$query" : { value : 100 } )
+      db.collection.find( { $query: { age : 25 } } )
 
    This is equivalent to the following :method:`db.collection.find()` method that
    may be more familiar to you:
 
    .. code-block:: javascript
 
-      db.collection.find( { value : 100 } )
+      db.collection.find( { age : 25 } )
+      
+   These operations return only those documents in the collection named
+   ``collection`` where the ``age`` field equals ``25``.

source/reference/operator/returnKey.txt

@@ -6,9 +6,12 @@ $returnKey
 
 .. operator:: $returnKey
 
-   Only return the index key (i.e. :term:`_id`) or keys for the
-   results of the query. Use the following form:
+   Only return the index key or keys for the results of the query. If
+   :operator:`$returnKey` is set to ``true`` and the query does not use
+   an index to perform the read operation, the returned documents will
+   not contain any fields. Use one of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial("$returnKey" , true )
+      db.collection.find( { <QUERY> } )._addSpecial( "$returnKey", true )
+      db.collection.find( { $query: { <QUERY> }, $returnKey: true } )

source/reference/operator/showDiskLoc.txt

@@ -6,9 +6,11 @@ $showDiskLoc
 
 .. operator:: $showDiskLoc
 
-   Use the following modifier to display the disk location:
+   Use the following modifier to display the disk location information
+   as an additional field ``$diskLoc`` in the returned documents. Use
+   one of the following forms:
 
    .. code-block:: javascript
 
-      db.collection.find()._addSpecial("$showDiskLoc" , true)
-
+      db.collection.find( { <QUERY> } )._addSpecial("$showDiskLoc" , true)
+      db.collection.find( { $query: { <QUERY> }, $showDiskLoc: true } )