diff --git a/source/core/geospatial-indexes.txt b/source/core/geospatial-indexes.txt index 03b81542949..4cdda3a8e8c 100644 --- a/source/core/geospatial-indexes.txt +++ b/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,9 +33,9 @@ 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 @@ -41,7 +43,7 @@ document. Consider the following two examples: 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 ` only recognize ``[ longitude, latitude @@ -63,7 +65,7 @@ location field of your collection. Consider the following prototype: db.collection.ensureIndex( { : "2d" } ) -MongoDB's special :ref:`geospatial operations +MongoDB's :ref:`geospatial operations ` 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() ` 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: diff --git a/source/includes/note-geospatial-index-must-exist.rst b/source/includes/note-geospatial-index-must-exist.rst index e3ca61410ea..77c2b77fc3e 100644 --- a/source/includes/note-geospatial-index-must-exist.rst +++ b/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. diff --git a/source/reference/operator/centerSphere.txt b/source/reference/operator/centerSphere.txt index 50914b0b0d9..10fda510217 100644 --- a/source/reference/operator/centerSphere.txt +++ b/source/reference/operator/centerSphere.txt @@ -10,16 +10,24 @@ $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 angular distance in radians (distance along the surface of the + earth). - db.collection.find( { loc: { $within: { $centerSphere: [ [0,0], 10 / 3959 ] } } } ) + The following example returns all documents within a 10 mile radius + of longitude ``88 W`` and latitude ``30 N``. The distance (10 miles) + is converted to radians by dividing by the approximate radius of the + earth (3959 miles). + + .. code-block:: javascript - This query will return all documents within a 10 mile radius of - ``[0,0]`` using a spherical geometry to calculate distances. + db.collection.find( { loc: { $within: { $centerSphere: { [88,30], 10 /* miles */ / 3959 /* miles */ } } } } ) .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/within.txt b/source/reference/operator/within.txt index c1475fb7eb4..37bb3e2ca71 100644 --- a/source/reference/operator/within.txt +++ b/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 } } } ); + - Circular distance on a sphere. 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: diff --git a/source/reference/operators.txt b/source/reference/operators.txt index 366b8dc4aae..eb0b6c93985 100644 --- a/source/reference/operators.txt +++ b/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: