Geo operators

draft/applications/geospatial-indexes.txt

@@ -208,8 +208,8 @@ Circles
 
 To return results within the :ref:`bounds <geospatial-query-bounded>`
 of a circle, you must specify the center and the radius of the circle,
-using the :operator:`$within` operator and the :operator:`$circle`
-option. Consider the following prototype query:
+using the :operator:`$within` operator and the :operator:`$center`
+operator. Consider the following prototype query:
 
 .. code-block:: javascript
 
@@ -364,6 +364,8 @@ their distance from the ``[ -74, 40.74 ]`` point.
 
 .. TODO add in distanceMultiplier description
 
+.. _geospatial-query-multi-location:
+
 Multi-location Documents
 ------------------------
 
@@ -429,4 +431,6 @@ in the following example:
 
    db.records.ensureIndex( { "addresses.loc": "2d" } )
 
+.. TODO include: includeLocs field
+
 .. includes:: /includes/geospatial-sharding.rst

source/reference/commands.txt

@@ -948,8 +948,8 @@ Geospatial Commands
 
    Here, :dbcommand:`geoNear` returns the 10 items nearest to the
    coordinates ``[50,50]`` in the collection named
-   ``places``. `geoNear` provides the following options (specify all
-   distances in the same units as the document coordinate system:)
+   ``places``. The :dbcommand:`geoNear` command provides the following options (specify all
+   distances in the same units as the document coordinate system.)
 
    :field near: Takes the coordinates (e.g. ``[ x, y ]``) to use as
                 the center of a geospatial query.
@@ -973,6 +973,26 @@ Geospatial Commands
                              by multiplying by the radius of the
                              Earth.
 
+   :field box: Specifies a rectangle or box shape to query within. To
+               specify the bounds of the rectangle, you must specify
+               the bottom left and top right corners of the rectangle
+               in an array object.
+
+   .. TODO is this really 'circle'??? 
+
+   :field circle: Specifies a circular shape to query within. To
+                  specify the bounds of the circle, you must specify
+                  the center point in an array and the radius of the circle.
+
+   :field polygon: Specifies a polygon shape to query within. To
+                   specify the bounds of the polygon, you must specify
+                   an array of points. The last point will
+                   automatically be joined with the first one.
+
+   :option boolean spherical: Specifies whether to use spherical
+                              coordinate system to calculate
+                              distances.
+
    .. read-lock, slave-ok
 
 .. dbcommand:: geoSearch

source/reference/operators.txt

@@ -271,62 +271,138 @@ Geospatial
       db.collection.find( { location: { $within: { shape } } } );
 
    Replace ``{ shape }`` with a document that describes a shape. The
-   :operator:`$within` command supports three shapes. These shapes and the
-   relevant expressions follow:
+   :operator:`$within` operator supports three basic shape types. These
+   shapes and the relevant expressions follow:
 
-   - Rectangles. Use the :operator:`$box` shape, consider the following
-     variable and :operator:`$within` document:
+   .. operator:: $box
 
-     .. code-block:: javascript
+      The :operator:`$box` operator specifies a box or rectangle shape
+      for the :operator:`$within` operator. 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:
 
-        db.collection.find( { location: { $within: { $box: [[100,0], [120,100]] } } } );
+      .. 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: [0,0], [0,100], [100,0], and [100,100].
+
+   .. operator:: $center
+
+      This specifies a circle shape for the :operator:`$within`
+      operators. To define the bounds of a query using
+      :operator:`$center`, you must specify:
 
-     Here a box, ``[[100,120], [100,0]]`` describes the parameter
-     for the query. As a minimum, you must specify the lower-left and
-     upper-right corners of the box.
+         - the center point, and
 
-   - Circles. Specify circles in the following form:
+	 - the radius
 
-     .. code-block:: javascript
+      Considering the following example:
 
-        db.collection.find( { location: { $within: { $circle: [ center, radius } } } );
+      .. 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].
 
-   - Polygons. Specify polygons with an array of points. See the
-     following example:
+   .. operator:: $polygon
 
-     .. code-block:: javascript
+      The :operator:`$polygon` operator specifies a polygon shape for
+      the :operator:`$within` operator. To define the bounds of the
+      polygon, you must specify an array of coordinate points. The
+      last point is always implicitly connected to the first
+      point. You can specify an arbitrary number of points to create
+      an multipoint polygon. See the following example:
+
+      .. code-block:: javascript
 
-        db.collection.find( { location: { $within: { $box: [[100,120], [100,100], [120,100], [240,200]] } } } );
+         db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0]  ] } } } )
 
-     The last point of a polygon is implicitly connected to the first
-     point.
+      This will return all the documents that are within the polygon
+      [0,0], [3,6], [6,0]. This is useful for searching within
+      specific areas that correspond to irregularly shaped areas such
+      as a dense urban neighborhood.
 
    All shapes include the border of the shape as part of the shape,
    although this is subject to the imprecision of floating point
-   numbers.
+   calculations.
+
+.. operator:: $nearSphere
+
+   The :operator:`$nearSphere` operator returns all documents near a
+   point using spherical representation system to calculate distances.
+
+   .. code-block:: javascript
+
+      db.collection.find( { loc: { $nearSphere: [0,0] } } )
+
+   This will return all documents near [0,0] using a spherical
+   representation system to calculate distances from [0,0].
+
+.. operator:: $centerSphere
+
+   The :operator:`$centerSphere` operator returns all the documents that
+   are within a certain radius from a point using spherical
+   representation. To define the bounds of the :operator:`$centerSphere` operator,
+   you must specify the center point and the radius.
+
+   Considering the following example:
+
+   .. code-block:: javascript
+
+      db.collection.find( { loc: { $centerSphere: { [0,0], 10 / 3959 } } } )
+
+   This will return all documents with a coordinate pair that is
+   within a 10 mile radius of [0,0] using a spherical representation
+   system to calculate distances from [0,0].
+
+   .. note::
+
+      For spherical queries, you must convert distances to radians for
+      proper results.
 
 .. 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 default query
+   behavior when :ref:`multiple location documents
+   <geospatial-query-multi-location>` are used.
+
+   .. TODO check this functionality again.
+
+   When querying multiple location documents using the
+   :operator:`$within` operator, MongoDB will return matching documents
+   once, even if there are multiple matches in the location fields.
+
+   By specifying ``$uniqueDocs: false`` in the :operator:`$within`
+   operator, matching documents may be returned multiple times if
+   there are multiple matches.
+
+   .. code-block:: javascript
+
+      db.places.find( { loc : { $within : { $center : [[0.5, 0.5], 20], $uniqueDocs : true } } } )
+
+   When using the :dbcommand:`geoNear` command, if a document contains
+   more than one field with coordinate values, MongoDB will return the
+   same document multiple times.
+
+   If you specify ``uniqueDocs: true`` as an option to the
+   :dbcommand:`geoNear` command, then MongoDB will only return a
+   single document, even if there are multiple matches.
+
+   .. code-block:: javascript
+
+      db.runCommand( { geoNear : "collection" , near : [0,0], num : 10, uniqueDocs : false } )
+
+   .. note::
 
-   The :operator:`$uniqueDocs` operator overrides these default
-   behaviors.
+      You cannot specify :operator:`$uniqueDocs` with
+      :operator:`$near` or haystack queries.
 
-   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.
 
-   You cannot specify :operator:`$uniqueDocs` with :operator:`$near`
-   or haystack queries.
 
 .. index:: query selectors; logical
 .. _query-selectors-logical: