re-editing geospatial core document

Author: Andrew Leung

draft/applications/geospatial-indexes.txt

@@ -167,6 +167,12 @@ please see the :ref:`geospatial-query-distance` section.
    queries with ``num`` option will only return the specified number
    of documents unsorted.
 
+.. note::
+
+   Limits in geospatial queries are always applied to the geospatial
+   component first. This will affect the results if you specify
+   additional sort operations.
+
 .. index:: geospatial queries; distance limit
 
 .. _geospatial-query-distance:

draft/core/geospatial-indexes.txt

@@ -9,14 +9,16 @@ Overview
 
 MongoDB supports location-based queries and geospatial data with a
 special index for coordinate data. The geospatial index stores :ref:`geohashes
-<geospatial-geohash>`, and makes it possible to return documents
-based on proximity to a point or within a bounded region. MongoDB can
-calculate distances between points using flat or spherical geometry.
+<geospatial-geohash>`, and makes it possible to query documents
+based on proximity or within a bounded region. MongoDB can
+calculate distances using flat or spherical geometry.
 Additionally, geospatial haystack indexes provide additional
-support for certain classes of region-based queries.
+support for tuning indexes.
 
-This document introduces the core concepts
-that underpin geospatial queries and indexes in MongoDB. For more information,
+.. TODO double check haystack benefits.
+
+This document introduces the core concepts that underpin geospatial
+indexes in MongoDB. For more information,
 :doc:`/applications/geospatial-indexes` provide complete documentation
 of all location-based operations and queries.
 
@@ -30,59 +32,60 @@ Geospatial Indexes
 .. see:: :ref:`geospatial-coordinates` for an overview on modeling
    location data in MongoDB.
 
-To use geospatial functions in MongoDB, model
-location data in a 2D array, then create an index using the
-:func:`ensureIndex <db.collection.ensureIndex()>` method on this field
-using the ``2d`` option. Consider the following prototype operation:
+To use geospatial operators in MongoDB, use the :func:`ensureIndex
+<db.collection.ensureIndex()>` method with the ``2d`` value on
+location field of your collection. Consider the following prototype
+operation:
 
 .. code-block:: javascript
 
    db.collection.ensureIndex( { <location field> : "2d" } )
 
-After the ``2d`` index has been created, all queries using coordinates
-will use this geospatial index.  The index uses a :term:`geohash`
-calculated from the coordinates.  For more information on
-:term:`geohash`, please refer to the :ref:`geohash
-<geospatial-geohash>` section.
+Almost all geospatial operators will query this index for location
+data.  The index comprises of :term:`geohashes <geohash>` calculated
+from location values and the index's geospatial :ref:`range
+<geospatial-indexes-range`.  For more information on :term:`geohash`,
+please refer to the :ref:`geohash <geospatial-geohash>` section.
 
 To perform queries on your geospatial data, please see
 :doc:`/applications/geospatial-indexes`.
 
 .. note::
 
-   MongoDB only supports *one* geospatial index per collection. As
-   with any MongoDB index, any single query can only
-   use one index. Creating more than one geospatial index with a
+   MongoDB only supports *one* geospatial index per
+   collection. Creating more than one geospatial index with a
    collection will produce unexpected results.
 
 .. _geospatial-indexes-range:
 
 Range
 ~~~~~
 
-All geospatial indexes are bounded. MongoDB will
-return an error and reject documents with coordinate data outside of
-the specified range. The default range assumes latitude and longitude
-data, and are between -180 inclusive and 180
-non-inclusive (i.e. ``[-180, 180)``.)
+All geospatial indexes are bounded to a range as this range is used to
+compute :term:`geohash` values. MongoDB will return an error and
+reject documents with coordinate data outside of the specified range,
+because the :term:`geohash` value will be invalid. The default range
+assumes latitude and longitude data, and are between -180 inclusive
+and 180 non-inclusive (i.e. ``[-180, 180)``.)
 
 To configure the range of a geospatial index, use the ``min`` and
 ``max`` options with the :func:`ensureIndex() <db.collection.ensureIndex()>`
-operation, as in the following prototype.
+operation, as in the following prototype:
 
 .. code-block:: javascript
 
    db.collection.ensureIndex( { <location field>: "2d" } ,
                               { min: <lower bound> , max: <upper bound> } )
 
-The following operation will create an index on the  ``places``
-collection, for coordinates in the ``loc`` field, with the range
-between ``-90`` and ``90``:
+.. TODO this might not be necessary...
+
+The following example command will create a geospatial index with a
+range between ``-90`` and ``90``:
 
 .. code-block:: javascript
 
    db.places.ensureIndex( { loc: "2d" } ,
-                           { min: 90 , max: 90 } )
+                          { min: -90 , max: 90 } )
 
 For more information see the :ref:`geospatial precision
 <geospatial-indexes-precision>` and :ref:`geohash
@@ -93,57 +96,63 @@ For more information see the :ref:`geospatial precision
 Precision
 ~~~~~~~~~
 
-Geospatial indexes use "bits" to represent precision, or
-resolution. Higher bit values allow MongoDB to return more precise
-results, at the expense of speed. For more information on the
+Geospatial indexes consist of :term:`geohash` values and the number of
+bits determine the precision of the index. More bits create more
+precise :term:`geohash` values, which allow MongoDB to return more
+precise results. Fewer bits create a shorter :term:`geohash` value,
+which allow for faster processing. For more information on the
 relationship between bits and precision, see the :ref:`geohash
 <geospatial-geohash>` section.
 
-By default, geospatial indexes in MongoDB have 26 bits of precision,
-although precision is configurable upon index creation and MongoDB
-supports up to 32 bits of precision. With 26 bits of precision, using
-the default range of -180 to 180, geospatial data can be precise to roughly 2
-feet or about 60 centimeters.
+The precision of geospatial indexes can be configured upto 32 bits. By
+default, geospatial indexes use 26 bits of precision, which is precise
+to roughly 2 feet or about 60 centimeters using the default range of
+-180 to 180.
 
-You can set the precision of a geospatial index during creation by
+The precision of a geospatial index can be configured during creation by
 specifying the ``bits`` option to the :func:`ensureIndex()
 <db.command.ensureIndex()>` method, as in the following prototype:
 
+.. TODO question: would the index recalculate geohashes if we
+.. reconfigure the bits option after the index has been made? or do we
+.. need to drop the index?
+
 .. code-block:: javascript
 
    db.collection.ensureIndex( {<location field>: "2d"} ,
                               { bits: <bit precision> } )
 
-Only create an index with fewer than 26 bits *if* your the data in
-your collection is less precise and/or you're willing to sacrifice
+Only create an index with fewer than 26 bits *if* the data in your
+collection is less precise and/or you're willing to sacrifice
 precision for query speed.
 
 Compound Indexes
 ~~~~~~~~~~~~~~~~
 
-MongoDB supports :ref:`compound indexes <index-type-compound>` where
-one component holds coordinate data. For queries that include these
-fields, MongoDB will use this index for a larger portion of these
-operations, which will improve performance for these queries.
+:ref:`Compound indexes <index-type-compound>` can be used with
+geospatial data to improve performance that query all these fields.
 
-Use an operation that resembles the following to create a geospatial
-index with a compound key.
+To create compound index with geospatial data and another field, the
+prototype form is:
 
 .. code-block:: javascript
 
    db.collection.ensureIndex( { <location field>: "2d", <field>: 1 } );
 
-These indexes support regular geospatial queries as well as queries where you must filter both by
-location and by another field. For example, if you need to return a
-list of restaurants near a given point, but you want to optionally
-filter restaurants by type, such as "take-out," or
-"bar" stored in the ``type`` field.
+This index will now support regular geospatial queries as well as
+queries where you must filter both by location and by another field.
 
-.. note::
+For example, to create a compound index on the ``loc`` field and the
+``type`` field, the command is:
+
+.. code-block:: javascript
 
-   Limits in geospatial queries are always applied to the geospatial
-   component first. This will affect the results if you specify
-   additional sort operations.
+   db.storeInfo.ensureIndex( { loc: "2d", type: 1 } );
+
+This will support geospatial queries as well as any query on the
+``type`` field. This index can return a list of restaurants near a
+given point, which can optionally filter restaurants by the ``type``,
+such as "take-out," or "bar".
 
 .. see also: ":ref:`<index-type-compound>`" and ":ref:`<geospatial-haystack-index>`"
 
@@ -152,37 +161,39 @@ filter restaurants by type, such as "take-out," or
 Haystack Index
 ~~~~~~~~~~~~~~
 
-Geospatial haystack indexes make it possible to tune the
-distribution of your data and build a special bucket
-index. Haystack indexes improve query performance for queries limited
-to a specific area.
+Geospatial haystack indexes make it possible to tune the index to the
+distribution of your data and build a special bucket index. Haystack
+indexes improve query performance for queries limited to a specific
+area.
 
 .. note::
 
-   Haystack indexes are not suited to returning the closest documents to
-   a particular location, as the closest documents could be far away
-   compared to the ``bucketSize``.
+   Haystack indexes are tuned to the ``bucketSize`` and are not suited
+   to returning the closest documents to a particular location,
+   because the closest documents could be further away than to the
+   ``bucketSize``.
 
-To build a :term:`geoHaystack` index, specify the ``geoHaystack`` for the
-location field and a ``bucketSize`` parameter . The ``bucketSize``
-parameter determines the granularity of the bucket index. A
-``bucketSize`` of ``1`` creates an index that stores keys within a single unit
-in the coordinate in the same bucket.
+The following command is the prototype to build a :term:`geoHaystack`
+index:
 
 .. code-block:: javascript
 
    db.collection.ensureIndex({ <location field>: "geoHaystack", type: 1 },
                              { bucketSize: <bucket value> })
 
-By default, all queries that use a geospatial haystack index will return 50
-documents.
+The ``bucketSize`` parameter determines the granularity of the
+index. A bucket value of ``5`` creates an index that stores keys
+within 5 units of the coordinate in the same bucket.
 
-To query geohaystack indexes, you *must* use the :dbcommand:`geoSearch`
+Geohaystack indexes are only queried by the :dbcommand:`geoSearch`
 command, please see the :ref:`Querying Haystack Indexes
-<geospatial-haystack-queries>` section.
+<geospatial-haystack-queries>` section for command details.
 
 :ref:`Spherical queries <geospatial-spherical-geometry>` are not
-supported by haystack indexes.
+supported by geohaystack indexes.
+
+By default, all queries that use a geospatial haystack index will return 50
+documents.
 
 .. _geospatial-spherical-geometry:
 
@@ -195,18 +206,16 @@ Spatial Representation Systems
 ------------------------------
 
 MongoDB supports two geometry systems for calculating distances
-between points. The default is flat geometry and assumes coordinates
-points are on a flat surface, which is sufficient for many
-applications. To calculate distance using spherical geometry, such as
-points that refer to locations on a spherical surface,
-(i.e. coordinates on Earth) MongoDB's spherical query operatorss will
-provide results using this geometrical system.
+between points. The default calculation is based on flat geometry,
+which points lie on a flat surface. User spherical query operators to
+calculate distances between points that lie on a spherical surface
+(i.e. coordinates on Earth.)
 
 .. note::
 
    There is no difference between flat and spherical *data* as stored
-   in MongoDB. Rather, the only difference is between the distance
-   calculation in spherical and flat geometry systems.
+   in MongoDB. Rather, the only difference is the distance
+   formulas to calculate in flat and spherical geometry.
 
 For more information on query operations for spherical geometry see the
 :ref:`spherical queries <geospatial-query-spherical>` section.
@@ -217,7 +226,8 @@ Geohash
 -------
 
 To create a geospatial index, MongoDB computes the :term:`geohash`
-value for the coordinate pair in the specified values.
+value for coordinate pairs within the specified :term:`range
+<geospatial-indexes-range>`.
 
 To calculate a geohash value, continuously divide a 2D map into
 quadrants. Then, assign each quadrant a two bit value. For example, a
@@ -230,18 +240,18 @@ two bit representation of four quadrants would be:
    00  10
 
 These two bit values, ``00``, ``01``, ``10``, and ``11``, represent
-each of the quadrants, and points within that quadrant. For a
-:term:`geohash` with two bits of resolution, a point in the bottom
+each of the quadrants, and all points within that quadrant. For a
+:term:`geohash` with two bits of resolution, all points in the bottom
 left quadrant would have a geohash of ``00``.  The top left quadrant
 would have the geohash of ``01``. The bottom right and top right would
 have a geohash of ``10`` and ``11``, respectively.
 
 To provide additional precision, continue dividing each quadrant into
-sub-quadrants. To identify quadrants within a sub-quadrant, take the
-geohash for the containing quadrant (e.g. ``01``) and concatenate the geohash for
-the sub-quadrant. Therefore, the geohash for
-the upper-right quadrant is ``11``, the geohash for the sub-quadrants would be:
-``1101``, ``1111``, ``1110``, and ``1100``.
+sub-quadrants. Each sub-quadrant would have the geohash value of the
+containing quadrant concatenated with the value of the
+sub-quadrant. The geohash for the upper-right quadrant is ``11``, and
+the geohash for the sub-quadrants would be: (clockwise from the top
+left) ``1101``, ``1111``, ``1110``, and ``1100``, respectfully.
 
 To calculate a more precise :term:`geohash`, continue dividing the
 sub-quadrant, concatenate the two-bit identifier for each division. The