DOCS-934 centerSphere and within

Author: Bob Grabar

source/core/geospatial-indexes.txt

@@ -7,20 +7,22 @@
 Overview
 --------
 
-``2d`` geospatial indexes support efficient queries using
-location-based data in a document, and special geospatial query
-operators. You can store two-dimensional location coordinates in
-documents and with a geospatial index on this field, construct
-location-based queries. For example, you can query for documents based
+Geospatial indexing allows you to associate a document with a location
+in two-dimensional space, such as a point on a map. You store
+two-dimensional coordinates in a location field in your documents,
+create a geospatial index on that field, and construct location-based
+queries. Geospatial indexes provide special geospatial query operators.
+For example, you can query for documents based
 on proximity to another location or based on inclusion in a specified
 region.
 
-Additionally, geospatial indexes support queries on both the
-coordinate field *and* another field. For example, you might write a
+Geospatial indexes support queries on both the coordinate field *and*
+another field, such as a type of business or attraction. For example,
+you might write a
 query to find restaurants a specific distance from a hotel or to find
-museums found within a certain defined neighborhood.
+museums within a certain defined neighborhood.
 
-This document describes how to include location data in your documents
+This document describes how to store location data in your documents
 and how to create geospatial indexes. For information on querying data
 stored in geospatial indexes, see :doc:`/applications/geospatial-indexes`.
 
@@ -31,17 +33,17 @@ Store Location Data
 
 To use ``2d`` geospatial indexes, you must model location data on a
 predetermined two-dimensional coordinate system, such as longitude
-and latitude. You store location data as two-dimensional coordinates
+and latitude. You store a document's location data as two coordinates
 in a field that holds either a two-dimensional array or an embedded
-document.  Consider the following two examples:
+document with two fields.  Consider the following two examples:
 
 .. code-block:: javascript
 
    loc : [ x, y ]
 
    loc : { x: 1, y: 2 }
 
-All documents must store location data in the same order; however, if
+All documents must store location data in the same order. If
 you use latitude and longitude as your coordinate system, always store
 longitude first. MongoDB's :ref:`2d spherical index operators
 <geospatial-indexes-spherical>` only recognize ``[ longitude, latitude
@@ -63,7 +65,7 @@ location field of your collection. Consider the following prototype:
 
    db.collection.ensureIndex( { <location field> : "2d" } )
 
-MongoDB's special :ref:`geospatial operations
+MongoDB's :ref:`geospatial operations
 <geospatial-query-operators>` use this index when querying for location
 data.
 
@@ -87,12 +89,12 @@ Location Range
 ~~~~~~~~~~~~~~
 
 All ``2d`` geospatial indexes have boundaries defined by a coordinate
-range. By default, ``2s`` geospatial indexes assume longitude and
+range. By default, ``2d`` geospatial indexes assume longitude and
 latitude have boundaries of -180 inclusive and 180 non-inclusive
 (i.e. ``[-180, 180)``). MongoDB returns an error and rejects documents
 with coordinate data outside of the specified range.
 
-To build an index with a different location range other than the
+To build an index with a location range other than the
 default, use the ``min`` and ``max`` options with the
 :method:`ensureIndex() <db.collection.ensureIndex()>` operation when
 creating a ``2d`` index, as in the following prototype:
@@ -253,8 +255,8 @@ for geospatial information based on a sphere or earth.
 .. admonition:: Spherical Queries Use Radians for Distance
 
    For spherical operators to function properly, you must convert
-   distances to radians, and convert from radians to distances units
-   for your application.
+   distances to radians, and convert from radians to the distances units
+   used by your application.
 
    To convert:
 

source/includes/note-geospatial-index-must-exist.rst

@@ -5,3 +5,8 @@
    operators *without* having a geospatial index; however, geospatial
    indexes will support much faster geospatial queries than the
    unindexed equivalents.
+
+.. note::
+
+   A geospatial index *must* exist on a field and the field must hold coordinates
+   before you can use any of the geolocation query operators.

source/reference/operator/centerSphere.txt

@@ -10,16 +10,26 @@ $centerSphere
 
    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.
+   spherical geometry to define a circle for use by the
+   :operator:`$within` operator in :term:`geospatial` queries.
 
-   Considering the following example:
+   To define the bounds of a query using :operator:`$centerSphere`, you
+   must specify:
 
-   .. code-block:: javascript
+   - The center point
+
+   - The radian. To calculate the radian, divide the radius of
+     the circle by the radius of the sphere.
 
       db.collection.find( { loc: { $within: { $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.
+   The following example returns all documents within a 10 mile radius
+   of longitude ``88 W`` and latitude ``30 N``. The document determines
+   the radian by dividing 10 miles by the approximate radius of the earth:
+   3960 miles.
+
+   .. code-block:: javascript
+
+      db.collection.find( { loc: { $within: { $centerSphere: [ [ 88 , 30 ], 10 / 3960 ] } } } )
 
    .. include:: /includes/note-geospatial-index-must-exist.rst

source/reference/operator/within.txt

@@ -15,7 +15,7 @@ $within
       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
+   :operator:`$within` command supports the following shapes. These shapes and the
    relevant expressions follow:
 
    - Rectangles. Use the :operator:`$box` operator, consider the following
@@ -35,6 +35,9 @@ $within
 
         db.collection.find( { location: { $within: { $center: [ center, radius } } } );
 
+   - Circles measured by spherical geometry. Use the
+     :operator:`$centerSphere` operator. For the syntax, see :operator:`$centerSphere`.
+
    - Polygons. Use the :operator:`$polygon` operator. Specify polygons with an array of points. See the
      following example:
 

source/reference/operators.txt

@@ -105,6 +105,15 @@ Geospatial
 - :operator:`$near`
 - :operator:`$within`
 
+.. include:: operator/near.txt
+   :start-after: mongodb
+
+.. include:: operator/nearSphere.txt
+   :start-after: mongodb
+
+.. include:: operator/within.txt
+   :start-after: mongodb
+
 Use the following operators within the context of
 :operator:`$within`:
 
@@ -115,6 +124,24 @@ Use the following operators within the context of
 - :operator:`$polygon`
 - :operator:`$uniqueDocs`
 
+.. include:: operator/maxDistance.txt
+   :start-after: mongodb
+
+.. include:: operator/center.txt
+   :start-after: mongodb
+
+.. include:: operator/centerSphere.txt
+   :start-after: mongodb
+
+.. include:: operator/box.txt
+   :start-after: mongodb
+
+.. include:: operator/polygon.txt
+   :start-after: mongodb
+
+.. include:: operator/uniqueDocs.txt
+   :start-after: mongodb
+
 .. index:: query selectors; array
 .. _query-selectors-array: