DOCS-151 - adding box and circle to operators list

source/reference/command/geoNear.txt

@@ -26,15 +26,15 @@ geoNear
 
    :field num: Specifies the maximum number of documents to return.
 
-   :field maxDistance: Limits the results to those falling within
+   :field maxDistance: Optional. Limits the results to those falling within
                        a given distance of the center coordinate.
 
-   :field query: Further narrows the results using any standard
+   :field query: Optional. Further narrows the results using any standard
                  MongoDB query operator or selection. See :method:`db.collection.find()`
                  and ":doc:`/reference/operators`" for more
                  information.
 
-   :field distanceMultipler: Specifies a factor to multiply
+   :field distanceMultipler: Optional. Specifies a factor to multiply
                              all distances returned by
                              :dbcommand:`geoNear`. For example, use
                              ``distanceMultiplier`` to convert from
@@ -43,4 +43,24 @@ geoNear
                              by multiplying by the radius of the
                              Earth.
 
+
+                             .. TODO include
+                                :ref:`geospatial-spherical-geometry`
+                                link when geospatial materials are
+                                merged in.
+
+   :field includeLocs: Optional. Default: ``false``. When specified
+                       ``true``, the location of matching documents
+                       are returned in the result.
+
+   :field uniqueDocs: Optional. Default ``true``. The default settings
+                      will only return a matching document once, even
+                      if more than one of its location fields match
+                      the query. When specified ``false``, documents
+                      with multiple location fields matching the query
+                      will be returned for each match.
+
+                      .. seealso:: :operator:`$uniqueDocs`
+
+
    .. read-lock, slave-ok

source/reference/operator/box.txt

@@ -0,0 +1,24 @@
+====
+$box
+====
+
+.. default-domain:: mongodb
+
+.. operator:: $box
+
+   .. versionadded:: 1.4
+
+   The :operator:`$box` operator specifies a rectangular shape for the
+   :operator:`$within` operator in :term:`geospatial` queries. To use
+   the :operator:`$box` operator, you must specify the bottom left and
+   top right corners of the rectangle in an array object. Consider the
+   following example:
+
+   .. code-block:: javascript
+
+      db.collection.find( { loc: { $within: { $box: [ [0,0], [100,100] ] } } } )
+
+   This will return all the documents that are within the box having
+   points at: ``[0,0]``, ``[0,100]``, ``[100,0]``, and ``[100,100]``.
+
+   .. include:: /includes/note-geospatial-index-must-exist.rst

source/reference/operator/center.txt

@@ -0,0 +1,28 @@
+=======
+$center
+=======
+
+.. default-domain:: mongodb
+
+.. operator:: $center
+
+   .. versionadded:: 1.4
+
+   This specifies a circle shape for the :operator:`$within` operator
+   in :term:`geospatial` queries. To define the bounds of a query
+   using :operator:`$center`, you must specify:
+
+      - the center point, and
+
+      - the radius
+
+   Considering the following example:
+
+   .. code-block:: javascript
+
+      db.collection.find( { location: { $within: { $center: [ [0,0], 10 } } } );
+
+   The above command returns all the documents that fall within a
+   10 unit radius of the point ``[0,0]``.
+
+   .. include:: /includes/note-geospatial-index-must-exist.rst

source/reference/operator/centerSphere.txt

@@ -0,0 +1,25 @@
+=============
+$centerSphere
+=============
+
+.. default-domain:: mongodb
+
+.. operator:: $centerSphere
+
+   .. versionadded:: 1.8
+
+   The :operator:`$centerSphere` operator is the spherical equivalent
+   of the :operator:`$center` operator. :operator:`$centerSphere` uses
+   spherical geometry to calculate distances in a circle specified by
+   a point and radius.
+
+   Considering the following example:
+
+   .. code-block:: javascript
+
+      db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 } } } )
+
+   This query will return all documents within a 10 mile radius of
+   ``[0,0]`` using a spherical geometry to calculate distances.
+
+   .. include:: /includes/note-geospatial-index-must-exist.rst

source/reference/operator/nearSphere.txt

@@ -0,0 +1,19 @@
+===========
+$nearSphere
+===========
+
+.. default-domain:: mongodb
+
+.. operator:: $nearSphere
+
+   .. versionadded:: 1.8
+
+   The :operator:`$nearSphere` operator is the spherical equivalent of
+   the :operator:`$near` operator. :operator:`$nearSphere` returns all
+   documents near a point, calculating distances using spherical geometry.
+
+   .. code-block:: javascript
+
+      db.collection.find( { loc: { $nearSphere: [0,0] } } )
+
+   .. include:: /includes/note-geospatial-index-must-exist.rst

source/reference/operator/polygon.txt

@@ -0,0 +1,27 @@
+========
+$polygon
+========
+
+.. default-domain:: mongodb
+
+.. operator:: $polygon
+
+   .. versionadded:: 1.9
+
+   Use :operator:`$polygon` to specify a polgon for a bounded query
+   using the :operator:`$within` operator for :term:`geospatial`
+   queries. To define the polygon, you must specify an array of
+   coordinate points, as in the following:
+
+       [ [ x1,y1 ], [x2,y2], [x3,y3] ]
+
+   The last point specified is always implicitly connected to the
+   first. You can specify as many points, and therfore sides, as you
+   like. Consider the following bounded query for documents with
+   coordinates within a polygon:
+
+   .. code-block:: javascript
+
+      db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0]  ] } } } )
+
+   .. include:: /includes/note-geospatial-index-must-exist.rst

source/reference/operator/uniqueDocs.txt

@@ -6,23 +6,113 @@ $uniqueDocs
 
 .. operator:: $uniqueDocs
 
-   When using the :dbcommand:`geoNear`, if document contains more than
-   one field with coordinate values, MongoDB will return the same
-   document multiple times. When using the :operator:`$within`,
-   however, MongoDB provides opposite behavior: if a document contains
-   more than one field with coordinate values, MongoDB will only
-   return the document once.
-
-   The :operator:`$uniqueDocs` operator overrides these default
-   behaviors.
-
-   By specifying ``$uniqueDocs: false`` in a :operator:`$within`
-   query, will cause the query to return a single document multiple
-   times if there is more than one match.
-
-   By contrast, if you specify ``uniqueDocs: true`` as an option to
-   the a :dbcommand:`geoNear` command, then :dbcommand:`geoNear` only
-   returns a single document even if there are multiple matches.
+   .. versionadded:: 2.0
+
+   For :term:`geospatial` queries, MongoDB may reuturn a single
+   document more than once for a single query, because geospatial
+   indexes may include multiple coordinate pairs in a single
+   document, and therefore return the same document more than once.
+
+   The :operator:`$uniqueDocs` operator inverts the default behavior
+   of these queres. By default, :dbcommand:`geoNear` will always
+   return multiple instances of the same document, while the
+   :operator:`$within` operator will *never* return the same document
+   more than once. Consider the following:
+
+   - For :dbcommand:`geoNear` queries, the default
+     :operator:`$uniqueDocs` setting is ``false``. If you specify a
+     value of ``true`` for :operator:`uniqueDocs`, MongoDB will
+     return multiple instances of a single document.
+
+   - For :operator:`$within` queries, the default
+     :operator:`$uniqueDocs` setting is ``true``. If you specify a
+     value of ``false`` for :operator:`uniqueDocs`, MongoDB will
+     return multiple instances of a single document.
+
+   .. example::
+
+      Given a document in the following form:
+
+      .. code-block:: javascript
+
+         { addresses: [ { name: "Home", loc:[55.5,42.3]}, {name:"Work",loc:[32.3,44.2]}]}
+
+      The following queries would return the same document multiple
+      times:
+
+      .. code-block:: javascript
+
+         > db.runCommand( { geoNear: "geo", near: [55,44], uniqueDocs: false })
+
+         > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty()
+
+      The following queries would return each matching document, only
+      once:
+
+      .. code-block:: javascript
+
+         > db.runCommand( { geoNear: "geo", near: [55,44], uniqueDocs: true })
+
+         > db.geo.find( {"address.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:true } }}).pretty()
+
+.. 
+   The following example commands in the :program:`mongo` shell
+   illustrate this feature:
+
+   .. code-block:: javascript
+
+      > db.geoExample.insert( )
+      > db.geoExample.ensureIndex({"addresses.loc":"2d"})
+
+      /* this will return the entry once - default for $within */
+      > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ] } }})
+      /* this will return the entry twice */
+      > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty()
+
+
+   .. Above code output:
+
+         .. code-block:: javascript
+
+            > db.geoExample.find( {"addresses.loc":{"$within": {"$box": [ [0,0],[100,100] ], $uniqueDocs:false } }}).pretty()
+            {
+               "_id" : ObjectId("504900870826ac3f09e25db6"),
+               "addresses" : [
+                  {
+                     "name" : "Home",
+                     "loc" : [
+                        55.5,
+                        42.3
+                     ]
+                  },
+                  {
+                     "name" : "Work",
+                     "loc" : [
+                        32.3,
+                        44.2
+                     ]
+                  }
+               ]
+            }
+            {
+               "_id" : ObjectId("504900870826ac3f09e25db6"),
+               "addresses" : [
+                  {
+                     "name" : "Home",
+                     "loc" : [
+                        55.5,
+                        42.3
+                     ]
+                  },
+                  {
+                     "name" : "Work",
+                     "loc" : [
+                        32.3,
+                        44.2
+                     ]
+                  }
+               ]
+            }
 
    You cannot specify :operator:`$uniqueDocs` with :operator:`$near`
    or haystack queries.

source/reference/operator/within.txt

@@ -7,7 +7,7 @@ $within
 .. operator:: $within
 
    The :operator:`$within` operator allows you to select items that exist
-   within a shape on a coordinate system. This operator uses the
+   within a shape on a coordinate system for :term:`geospatial` queries. This operator uses the
    following syntax:
 
    .. code-block:: javascript
@@ -18,7 +18,7 @@ $within
    :operator:`$within` command supports three shapes. These shapes and the
    relevant expressions follow:
 
-   - Rectangles. Use the :operator:`$box` shape, consider the following
+   - Rectangles. Use the :operator:`$box` operator, consider the following
      variable and :operator:`$within` document:
 
      .. code-block:: javascript
@@ -29,13 +29,13 @@ $within
      for the query. As a minimum, you must specify the lower-left and
      upper-right corners of the box.
 
-   - Circles. Specify circles in the following form:
+   - Circles. Use the :operator:`$center` operator. Specify circles in the following form:
 
      .. code-block:: javascript
 
         db.collection.find( { location: { $within: { $circle: [ center, radius } } } );
 
-   - Polygons. Specify polygons with an array of points. See the
+   - Polygons. Use the :operator:`$polygon` operator. Specify polygons with an array of points. See the
      following example:
 
      .. code-block:: javascript
@@ -49,4 +49,21 @@ $within
    although this is subject to the imprecision of floating point
    numbers.
 
+   Use :operator:`uniqueDocs` to control whether documents with
+   many location fields show up multiple times when more than one
+   of its fields match the query.
+
    .. include:: /includes/note-geospatial-index-must-exist.rst
+
+   .. include:: /reference/operator/box.txt
+      :start-after: mongodb
+
+   .. include:: /reference/operator/polygon.txt
+      :start-after: mongodb
+
+   .. include:: /reference/operator/center.txt
+      :start-after: mongodb
+
+   .. include:: /reference/operator/uniqueDocs.txt
+      :start-after: mongodb
+

source/reference/operators.txt

@@ -98,7 +98,10 @@ Geospatial
 .. include:: operator/within.txt
    :start-after: mongodb
 
-.. include:: operator/uniqueDocs.txt
+.. include:: operator/nearSphere.txt
+   :start-after: mongodb
+
+.. include:: operator/centerSphere.txt
    :start-after: mongodb
 
 .. index:: query selectors; logical