DOCS-641 Geospatial

Author: Bob Grabar

bin/builder_data.py

@@ -53,6 +53,7 @@
      ('$(public-branch-output)/reference/mongo-shell-reference', 'mongo-shell', 'redirect'),
      ('$(public-branch-output)/reference/method/getShardDistribution', 'db.collection.getShardDistribution', 'redirect'),
      ('$(public-branch-output)/reference/method/getDB', 'Mongo.getDB', 'redirect'),
+     ('$(public-branch-output)/reference/operator/within', 'geoWithin', 'redirect'),
      ('$(public-branch-output)/reference/method/getShardVersion', 'db.collection.getShardVersion', 'redirect'),
      ('$(public-branch-output)/reference/command/whatsMyUri', 'whatsmyuri', 'redirect'),
      ('$(public-branch-output)/reference/command/writeBackListen', 'writebacklisten', 'redirect'),

source/administration/indexes.txt

@@ -99,10 +99,6 @@ Special Creation Options
    TTL collections use a special ``expire`` index option. See
    :doc:`/tutorial/expire-data` for more information.
 
-.. note::
-
-   To create geospatial indexes, see :ref:`geospatial-indexes-create`.
-
 .. index:: index; sparse
 .. _index-sparse-index:
 

source/applications/2d.txt

@@ -0,0 +1,268 @@
+==============
+``2d`` Indexes
+==============
+
+.. default-domain:: mongodb
+
+Use a ``2d`` index for data stored as points on a two-dimensional plane. The
+``2d`` index is intended for legacy coordinate pairs used in MongoDB 2.2
+and earlier.
+
+Use a ``2d`` index if:
+
+- your database has legacy location data from MongoDB 2.2 or earlier, *and*
+
+- you do not intend to store any location data as :term:`GeoJSON` objects.
+
+Do not use a ``2d`` index if your location data includes GeoJSON objects. To
+index on both legacy coordinate pairs *and* GeoJSON objects, use a
+:doc:`2dsphere index </applications/2dsphere>`.
+
+The ``2d`` index supports calculations on a flat, Euclidean plane. The
+``2d`` index also supports *distance-only* calculations on a sphere, but
+for *geometric* calculations on a sphere, store data as GeoJSON objects
+and use the ``2dsphere`` index type.
+
+A ``2d`` index can reference two fields. The first must be the location
+field. A ``2d`` compound index constructs queries that select first on
+the location field and second on the additional field. If the location
+criteria selects a large number of documents, the additional criteria
+only filters the result set. The additional criteria *does not* result
+in a more targeted query.
+
+MongoDB allows one ``2d`` index per collection.
+
+.. important:: You cannot use a ``2d`` index as a shard key when
+   sharding a collection. However, you can create and maintain a
+   geospatial index on a sharded collection by using a different field
+   as the shard key.
+
+.. _geospatial-indexes-store-grid-coordinates:
+
+Store Points on a 2D Plane
+--------------------------
+
+To store location data as legacy coordinate pairs, use either an array
+(preferred):
+
+.. code-block:: javascript
+
+   loc : [ <long> , <lat> ]
+
+Or an embedded document:
+
+.. code-block:: javascript
+
+   loc : { long : <long> , lat : <lat> }
+
+Arrays are preferred as certain languages do not guarantee associative
+map ordering.
+
+Whether as an array or document, if you use longitude and latitude,
+store coordinates in this order: **longitude, latitude**.
+
+.. _geospatial-create-2d-index:
+
+Create a ``2d`` Index
+---------------------
+
+To build a geospatial ``2d`` index, use the :method:`ensureIndex()
+<db.collection.ensureIndex()>` method and specify ``2d``. Use the
+following syntax:
+
+.. code-block:: javascript
+
+   db.<collection>.ensureIndex( { <location field> : "2d" , <additional field> : <value> } ,
+                                { <index-specification options> } )
+
+The ``2d`` index uses the following optional index-specification
+options:
+
+.. code-block:: javascript
+
+   { min : <lower bound> , max : <upper bound> ,
+     bits : <bit precision> }
+
+.. _geospatial-indexes-range:
+
+Define Location Range for a ``2d`` Index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, a ``2d`` index assumes longitude and latitude and has boundaries
+of -180 inclusive and 180 non-inclusive (i.e. ``[ -180 , 180 ]``). If
+documents contain coordinate data outside of the specified range,
+MongoDB returns an error.
+
+.. important:: The default boundaries allow applications to insert
+   documents with invalid latitudes greater than 90 or less than -90.
+   The behavior of geospatial queries with such invalid points is not
+   defined.
+
+On ``2d`` indexes you can change the location range.
+
+You can build a ``2d`` geospatial index with a location range other than
+the default. Use the ``min`` and ``max`` options when creating the
+index. Use the following syntax:
+
+.. code-block:: javascript
+
+   db.collection.ensureIndex( { <location field> : "2d" } ,
+                              { min : <lower bound> , max : <upper bound> } )
+
+.. _geospatial-indexes-precision:
+
+Define Location Precision for a ``2d`` Index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, a ``2d`` index on legacy coordinate pairs uses 26 bits of
+precision, which is roughly equivalent to 2 feet or 60 centimeters of
+precision using the default range of -180 to 180. Precision is measured
+by the size in bits of the :term:`geohash` values used to store location
+data. You can configure geospatial indexes with up to 32 bits of
+precision.
+
+Index precision does not affect query accuracy. The actual grid coordinates
+are always used in the final query processing. Advantages to lower
+precision are a lower processing overhead for insert operations and use
+of less space. An advantage to higher precision is that queries scan
+smaller portions of the index to return results.
+
+To configure a location precision other than the default, use the
+``bits`` option when creating the index. Use following syntax:
+
+.. code-block:: javascript
+
+   db.<collection>.ensureIndex( {<location field> : "<index type>"} ,
+                                { bits : <bit precision> } )
+
+For information on the internals of geohash values, see
+:ref:`geospatial-indexes-geohash`.
+
+Query a ``2d`` Index
+--------------------
+
+The following sections describe queries supported by the ``2d`` index.
+For an overview of recommended geospatial queries, see
+:doc:`/reference/geospatial-queries`.
+
+Points within a Shape Defined on a Flat Surface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To select all legacy coordinate pairs found within a given shape on a flat
+surface, use the :operator:`$geoWithin` operator along with a shape
+operator. Use the following syntax:
+
+.. code-block:: javascript
+
+   db.<collection>.find( { <location field> :
+                            { $geoWithin :
+                               { $box|$polygon|$center : <coordinates>
+                         } } } )
+
+The following queries for documents within a rectangle defined by ``[ 0
+, 0 ]`` at the bottom left corner and by ``[ 100 , 100 ]`` at the top
+right corner.
+
+.. code-block:: javascript
+
+   db.places.find( { loc : { $geoWithin : { $box :
+                                             [ [ 0 , 0 ] ,
+                                               [ 100 , 100 ] ] } } } )
+
+The following queries for documents that are within the circle centered
+on ``[ -74 , 40.74 ]`` and with a radius of ``10``:
+
+.. code-block:: javascript
+
+   db.places.find( { loc: { $geoWithin :
+                             { $center : [ [-74, 40.74], 10 ] }
+                   } } )
+
+For syntax and examples for each shape, see the following:
+
+  - :operator:`$box`
+
+  - :operator:`$polygon`
+
+  - :operator:`$center` (defines a circle)
+
+Points within a Circle Defined on a Sphere
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB supports rudimentary spherical queries on flat ``2d`` indexes for
+legacy reasons. In general, spherical calculations should use a ``2dsphere``
+index, as described in :doc:`/applications/2dsphere`.
+
+To query for legacy coordinate pairs in a "spherical cap" on a sphere,
+use :operator:`$geoWithin` with the :operator:`$centerSphere` operator.
+Specify an array that contains:
+
+- The grid coordinates of the circle's center point
+
+- The circle's radius measured in radians. To calculate radians, see
+  :doc:`/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes`.
+
+Use the following syntax:
+
+.. code-block:: javascript
+
+   db.<collection>.find( { <location field> :
+                            { $geoWithin :
+                               { $centerSphere : [ [ <x>, <y> ] , <radius> ] }
+                         } } )
+
+The following example query returns all documents within a 10-mile
+radius of longitude ``88 W`` and latitude ``30 N``. The example converts
+distance to radians by dividing distance by the approximate radius of
+the earth, 3959 miles:
+
+.. code-block:: javascript
+
+   db.<collection>.find( { loc : { $geoWithin :
+                                    { $centerSphere :
+                                       [ [ 88 , 30 ] , 10 / 3959 ]
+                         } } } )
+
+Proximity to a Point on a Flat Surface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Proximity queries return the 100 legacy coordinate pairs closest to the
+defined point and sort the results by distance. Use either the
+:operator:`$near` operator or :dbcommand:`geoNear` command. Both require
+a ``2d`` index.
+
+The :operator:`$near` operator uses the following syntax:
+
+.. code-block:: javascript
+
+   db.<collection>.find( { <location field> :
+                            { $near : [ <x> , <y> ]
+                         } } )
+
+For examples, see :operator:`$near`.
+
+The :dbcommand:`geoNear` command uses the following syntax:
+
+.. code-block:: javascript
+
+   db.runCommand( { geoNear: <collection>, near: [ <x> , <y> ] } )
+
+The :dbcommand:`geoNear` command offers more options and returns more
+information than does the :operator:`$near` operator. To run the
+command, see :dbcommand:`geoNear`.
+
+.. index:: geospatial queries
+.. index:: geospatial queries; exact
+.. _geospatial-indexes-exact-match:
+
+Exact Matches on a Flat Surface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the :method:`db.collection.find()` method to query for an
+exact match on a location. These queries use the following syntax:
+
+.. code-block:: javascript
+
+   db.<collection>.find( { <location field>: [ <x> , <y> ] } )
+
+This query will return any documents with the value of ``[ <x> , <y> ]``.