DOCS-238 reorganizing geospatial content

Author: Sam Kleinman

draft/applications/geospatial-indexes.txt

@@ -15,204 +15,7 @@ the geospatial indexes and its operations see :doc:`Geospatial Indexes
 
 .. _geospatial-coordinates:
 
-Geospatial Coordinates
-----------------------
-
-For geospatial indexes, you must model your coordinate data in a field
-that holds a 2 dimensional array. The preferred form is:
-
-.. code-block:: javascript
-
-   [ x, y ]
-
-Consistency is crucial: all documents must store the values in the
-same order. you may also use an embeded document, as in:
-
-.. code-block:: javascript
-
-   { x: 1, y: 2 }
-
-MongoDB will not read field names in embedded documents, so order is
-still important when using this model.
-
-.. note::
-
-   If you use latitude/longitude data as your coordinate system,
-   always store latitude values first: MongoDB's :ref:`spherical
-   queries <geospatial-query-spherical>` only recognize ``[
-   latitude, longitude ]`` ordering.
-
-.. _geospatial-indexes:
-
-Geospatial Indexes
-------------------
-
-.. see:: :ref:`geospatial-coordinates` for an overview on modeling
-   location data in MongoDB.
-
-To create a geospatial index, use an operation modeled on the
-following prototype:
-
-.. code-block:: javascript
-
-   db.collection.ensureIndex( { <location field> : "2d" } )
-
-These operations will create a special index on location field in the
-specified collection. These indexes use :ref:`geospatial-geohash`. All
-geospatial queries will use this geospatial index.
-
-.. note::
-
-   MongoDB only supports *one* geospatial index per collection. As
-   with all indexes in MongoDB, any single query will only be able to
-   use one index. If a collection were to have more than one
-   geospatial index, geospatial queries could not return consistent
-   results.
-
-.. _geospatial-indexes-range:
-
-Range
-~~~~~
-
-All geospatial indexes are bounded and MongoDB will return an error
-and reject documents with coordinate pairs outside of these
-boundaries. The default boundaries support global coordinate data
-(i.e. latitude and longitude for points on Earth,) are between -180
-inclusive, and 180 non-inclusive.
-
-To specify the boundaries of a geospatial index, use the ``min`` and
-``max`` operators with the :func:`ensureIndex() <db.collection.ensureIndex()>`
-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 boundaries
-between ``-90`` and ``90``:
-
-.. code-block:: javascript
-
-   db.places.ensureIndex( { loc: "2d" } ,
-                           { min: 90 , max: 90 } )
-
-.. _geospatial-indexes-precision:
-
-Precision
-~~~~~~~~~
-
-Geospatial indexes record precision, or resolution, in "bits", which
-are configurable during index creation. If a geospatial index has a
-higher bits setting, MongoDB will be able to return more precise
-results from the index. However, lower resolution indexes provide
-faster performance. For more information, please refer to the
-:ref:`precision <geospatial-indexes-precision>` section.
-
-By default, geospatial indexes in MongoDB have 26 bits of precision
-and supports as many as 32 bits of precision. You can set the
-precision of a geospatial index during creation by specifying the
-``bits`` option to the :func:`ensureIndex()
-<db.command.ensureIndex()>` method, as in the following example.
-
-.. code-block:: javascript
-
-   db.collection.ensureIndex( {<location field>: "2d"} ,
-                              { bits: <bit precision> } )
-
-You may 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
-precision in exchange for query speed.
-
-Compound Indexes
-~~~~~~~~~~~~~~~~
-
-MongoDB supports :term:`compound indexes <compound index>` where one component is a
-coordinate in a geospatial index, and the other coordinate is one or
-more fields. This means that, for some operations, MongoDB will be
-able to use this index for a larger portion of an operation, which
-will improve performance for these queries.
-
-Use an operation that resembles the following prototype command to
-create a compound geospatial index.
-
-.. code-block:: javascript
-
-   db.collection.ensureIndex( { <location field>: "2d", <field>: 1 } );
-
-These compound indexes support 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
-select only restaurants that match a certain type (i.e. "take-out," or
-"bar" stored in a ``type`` field.)
-
-See the :ref:`index-type-compound` section for more information on
-geospatial indexes.
-
-.. note::
-
-   Limits in geospatial queries are always applied to the geospatial
-   component first. This will affect your result set if you specify
-   additional sort operations.
-
-Haystack Indexing
-~~~~~~~~~~~~~~~~~
-
-Geospatial haystack indexes makes it possible to build a special ``bucket``
-collection that can better support queries that operate within a
-limited area. For more information, please refer to :doc:`Geospatial
-Indexes </core/geospatial-indexes>`
-
-Build a geospatial index and 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 where keys within 1 unit of
-longitude or latitude are stored in the same bucket.
-
-.. code-block:: javascript
-
-   db.collection.ensureIndex({ <location field>: "geoHaystack", type: 1 },
-                             { bucketSize: <bucket value> })
-
-By default, all queries on a geospatial haystack index returns 50
-documents.
-
-For example, to index all restaurants in a particular area with a
-given maximum distance of 6 degrees longitude or latitude to accelerate
-searches in this area, create the index using the following command:
-
-.. code-block:: javascript
-
-   db.places.ensureIndex({ loc: "geoHaystack", type: 1} ,
-                          { bucketSize: 6 } )
-
-.. _geospatial-spherical-representation:
-
-Spatial Representation Systems
-------------------------------
-
-MongoDB supports two systems for representing and returning geospatial
-results. The default representation is flat and assumes that the
-coordinates represent points on a flat plane. While this
-representation is sufficient for many applications, if the points
-refer to locations on a spherical plane (i.e. coordinates on Earth)
-then sphical queries will provide more accurate results.
-
-.. note::
-
-   There is no difference between flat and spherical *data* as stored
-   in MongoDB. Rather, the only difference between spherical and flat
-   geospatial systems in MongoDB is in the **queries**.
-
-In general, the flat system is easier and accurate for system data
-sets, but will return imprecise or skewed results if your coordinate
-system reflects points on a curved plane, like the Earth's surface.
-
-For more information on spherical and flat queries see the
-:ref:`geospatial-representation-system` section and for more
-information on query operations for spherical systems see the
-:ref:`spherical queries <geospatial-query-spherical>` section.
+.. include:: /includes/geospatial-coordinates.rst
 
 .. index:: geospatial queries
 .. _geospatial-queries:
@@ -624,12 +427,4 @@ in the following example:
 
    db.records.ensureIndex( { "addresses.loc": "2d" } )
 
-Geospatial Indexes and Sharding
--------------------------------
-
-You cannot use a geospatial index as a :term:`shard key` to shard a
-collection. However, you *can* create and maintain a geospatial index
-on a sharded collection, as long as the shard key is another
-field. Your application may query for geospatial data using
-:dbcommand:`geoNear` and :operator:`$within`; however, queries using
-:operator:`$near` are not supported.
+.. includes:: /includes/geospatial-sharding.rst