diff --git a/source/applications/2d.txt b/source/applications/2d.txt index e21b241a4c9..3a18e3bc660 100644 --- a/source/applications/2d.txt +++ b/source/applications/2d.txt @@ -47,13 +47,13 @@ To store location data as legacy coordinate pairs, use either an array .. code-block:: javascript - loc : [ , ] + loc : [ , ] Or an embedded document: .. code-block:: javascript - loc : { long : , lat : } + loc : { lng : , lat : } Arrays are preferred as certain languages do not guarantee associative map ordering. diff --git a/source/applications/2dsphere.txt b/source/applications/2dsphere.txt index bd075690325..9409c8c9dbf 100644 --- a/source/applications/2dsphere.txt +++ b/source/applications/2dsphere.txt @@ -15,8 +15,6 @@ supports legacy coordinate pairs by converting the data to the GeoJSON The ``2dsphere`` index supports all MongoDB geospatial queries: queries for inclusion, intersection and proximity. -MongoDB allows one ``2dsphere`` index per collection. - A :ref:`compound ` ``2dsphere`` index can reference multiple location and non-location fields within a collection’s documents. You can arrange the fields in any order. @@ -106,18 +104,20 @@ The following are four example commands for creating a ``2dsphere`` index: .. code-block:: javascript db.collection.ensureIndex( { loc : "2dsphere" } ) - db.collection.ensureIndex( { loc : "2dsphere", type : 1 } ) - db.collection.ensureIndex( { type : 1, loc : "2dsphere" } ) - db.collection.ensureIndex( { loc : "2dsphere", type : 1, rating : -1 } ) + db.collection.ensureIndex( { loc : "2dsphere" , type : 1 } ) + db.collection.ensureIndex( { rating : 1 , loc : "2dsphere" } ) + db.collection.ensureIndex( { loc : "2dsphere" , rating : 1 , category : -1 } ) The first example creates a simple geospatial index on the location field ``loc``. The second example creates a compound index where the second field contains non-location data. The third example creates an index where the location field is not the primary field: the location field does not have to be the first field in a ``2dsphere`` index. The -fourth example creates a compound index with three fields: you can +fourth example creates a compound index with three fields. You can include as many fields as you like in a ``2dsphere`` index. +.. _geospatial-indexes-query-2dsphere: + Query a ``2dsphere`` Index -------------------------- @@ -158,8 +158,12 @@ Intersections of GeoJSON Objects .. versionadded:: 2.4 -The :operator:`$geoIntersects` operator queries for location data that -intersects a GeoJSON object. Use the following syntax: +The :operator:`$geoIntersects` operator queries for locations that +intersect a specified GeoJSON object. A location intersects the object +if the intersection is non-empty. This includes documents that have a +shared edge. + +The :operator:`$geoIntersects` operator uses the following syntax: .. code-block:: javascript @@ -183,9 +187,6 @@ indexed points and shapes that intersect with the polygon defined by the coordinates: [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] } } } } ) -The query returns true if the intersection between shapes is non-empty. -This includes documents that have a shared edge. - Proximity to a GeoJSON Point ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -205,7 +206,7 @@ The :operator:`$near` uses the following syntax: { $near : { $geometry : { type : "Point" , - coordinates : [ , ] } , + coordinates : [ , ] } , $maxDistance : } } } ) diff --git a/source/applications/geohaystack.txt b/source/applications/geohaystack.txt index a9a166a1b1a..84f8f2c86e8 100644 --- a/source/applications/geohaystack.txt +++ b/source/applications/geohaystack.txt @@ -58,9 +58,9 @@ To build a haystack index, use the following syntax: .. code-block:: javascript - { _id : 100, pos: { long : 126.9, lat : 35.2 } , type : "restaurant"} - { _id : 200, pos: { long : 127.5, lat : 36.1 } , type : "restaurant"} - { _id : 300, pos: { long : 128.0, lat : 36.7 } , type : "national park"} + { _id : 100, pos: { lng : 126.9, lat : 35.2 } , type : "restaurant"} + { _id : 200, pos: { lng : 127.5, lat : 36.1 } , type : "restaurant"} + { _id : 300, pos: { lng : 128.0, lat : 36.7 } , type : "national park"} The following operations create a haystack index with buckets that store keys within 1 unit of longitude or latitude. diff --git a/source/applications/geospatial-indexes.txt b/source/applications/geospatial-indexes.txt index 60e71faf640..2c9e48058cc 100644 --- a/source/applications/geospatial-indexes.txt +++ b/source/applications/geospatial-indexes.txt @@ -25,15 +25,16 @@ MongoDB offers two surface types: ` index. Store your location data as GeoJSON objects with this coordinate-axis - order: **longitude, latitude**. The default coordinate reference - system for GeoJSON uses the :term:`WGS84` datum. MongoDB does not yet - support non-default coordinate reference systems in GeoJSON. + order: **longitude, latitude**. The coordinate reference system for + GeoJSON is the :term:`WGS84` datum. - **Flat** To calculate distances on a Euclidean plane, store your location data as legacy coordinate pairs and use a :doc:`2d ` index. +.. _geo-overview-location-data: + Location Data ------------- @@ -48,6 +49,14 @@ If you choose spherical surface calculations, you store location data as is new in version 2.4. Prior to version 2.4, all geospatial data was stored as coordinate pairs. + MongoDB supports the following GeoJSON objects: + + - Point + + - LineString + + - Polygon + - :term:`Legacy coordinate pairs ` MongoDB supports spherical surface calculations on legacy coordinate diff --git a/source/core/geospatial-indexes.txt b/source/core/geospatial-indexes.txt index 6b11a8eb880..3e39e953edc 100644 --- a/source/core/geospatial-indexes.txt +++ b/source/core/geospatial-indexes.txt @@ -80,11 +80,11 @@ example: { _id : ObjectId(...), locs : [ [ 55.5 , 42.3 ] , [ -74 , 44.74 ] , - { long : 55.5 , lat : 42.3 } ] + { lng : 55.5 , lat : 42.3 } ] } The values of the array may be either arrays, as in ``[ 55.5, 42.3 ]``, -or embedded documents, as in ``{ long : 55.5 , lat : 42.3 }``. +or embedded documents, as in ``{ lng : 55.5 , lat : 42.3 }``. You could then create a geospatial index on the ``locs`` field, as in the following: diff --git a/source/reference/command/geoNear.txt b/source/reference/command/geoNear.txt index c894b173e4b..6ffee9a2e20 100644 --- a/source/reference/command/geoNear.txt +++ b/source/reference/command/geoNear.txt @@ -29,8 +29,8 @@ geoNear { geoNear : , near : [ ] } - `geoNear` provides the following options (specify all - distances in the same units as the document coordinate system): + The :dbcommand:`geoNear` command provides the following options. Specify all + distances in the same units as the document coordinate system: :field near: Can use either a GeoJSON point or legacy points, as shown above. diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index e1807576e2c..fc94bfd0fe8 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -902,8 +902,9 @@ Glossary GeoJSON is a geospatial data interchange format based on JavaScript Object Notation (JSON) and is used in geospatial queries. - For details, see the - `GeoJSON Format Specification `_ + For supported GeoJSON objects, see :ref:`geo-overview-location-data`. + For the GeoJSON format specification, see + `http://geojson.org/geojson-spec.html `_ legacy coordinate pairs The format used for geospatial data prior to MongoDB version 2.4. diff --git a/source/reference/operator/geoIntersects.txt b/source/reference/operator/geoIntersects.txt index 12edee48671..f48bef7db7f 100644 --- a/source/reference/operator/geoIntersects.txt +++ b/source/reference/operator/geoIntersects.txt @@ -9,16 +9,11 @@ $geoIntersects .. versionadded:: 2.4 The :operator:`$geoIntersects` operator is a geospatial query - operator that selects all points that intersect with one of the - following :term:`GeoJSON` objects: - - - Point - - - LineString - - - Polygon - - The :operator:`$geoIntersects` operator uses spherical geometry. + operator that selects all locations that intersect with a + :term:`GeoJSON` object. A location intersects a GeoJSON object if the + intersection is non-empty. This includes documents that have a shared + edge. The :operator:`$geoIntersects` operator uses spherical + geometry. The ``2dsphere`` geospatial index supports :operator:`$geoIntersects`. @@ -50,6 +45,3 @@ $geoIntersects { type : "Polygon" , coordinates: [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] } } } } } ) - - The query returns true if the intersection between shapes is - non-empty. This includes documents that have a shared edge. diff --git a/source/reference/operator/geoWithin.txt b/source/reference/operator/geoWithin.txt index 11da20843c8..9eb0b648dac 100644 --- a/source/reference/operator/geoWithin.txt +++ b/source/reference/operator/geoWithin.txt @@ -46,7 +46,7 @@ $geoWithin { $geoWithin : { $geometry : { type : "Polygon" , - coordinates : [ [ [ , ] , [ , ] ... ] ] + coordinates : [ [ [ , ] , [ , ] ... ] ] } } } } ) .. important:: Specify coordinates in this order: **"longitude, latitude."** @@ -59,8 +59,8 @@ $geoWithin { $geoWithin : { $geometry : { type : "Polygon" , - coordinates : [ [ [ , ] , [ , ] ... ] - [ [ , ] , [ , ] ... ] ] + coordinates : [ [ [ , ] , [ , ] ... ] + [ [ , ] , [ , ] ... ] ] } } } } ) The following example selects all indexed points and shapes that diff --git a/source/reference/operator/near.txt b/source/reference/operator/near.txt index 02be966df3e..9c8a990d69a 100644 --- a/source/reference/operator/near.txt +++ b/source/reference/operator/near.txt @@ -25,7 +25,7 @@ $near GeoJSON points, use a ``2dsphere`` index. For legacy coordinate pairs, use a ``2d`` index. - If querying on GeoJSON data, use the following syntax: + For queries on GeoJSON data, use the following syntax: .. code-block:: javascript @@ -33,7 +33,7 @@ $near { $near : { $geometry : { type : "Point" , - coordinates : [ , ] } , + coordinates : [ , ] } , $maxDistance : } } } ) @@ -48,11 +48,11 @@ $near db.places.find( { loc : { $near : { $geometry : { type : "Point" , - coordinates: [ 40 , 5 ] } } , + coordinates: [ 40 , 5 ] } , $maxDistance : 100 } } } ) - If querying on legacy coordinate pairs, use the following syntax: + For queries on legacy coordinate pairs, use the following syntax: .. code-block:: javascript diff --git a/source/reference/operator/nearSphere.txt b/source/reference/operator/nearSphere.txt index 1cc7404ac44..e01cd244346 100644 --- a/source/reference/operator/nearSphere.txt +++ b/source/reference/operator/nearSphere.txt @@ -9,35 +9,53 @@ $nearSphere .. versionadded:: 1.8 The :operator:`$nearSphere` operator specifies a point for which a - :term:`geospatial` query returns the 100 closest documents. The - :operator:`$nearSphere` operator queries for points defined by legacy - coordinate pairs or :term:`GeoJSON` objects and calculates distances - using spherical geometry. The query sorts the documents from nearest - to farthest. + :term:`geospatial` query returns the 100 closest documents, sorted + from nearest to farthest. MongoDB calculates distances for + :operator:`$nearSphere` using spherical geometry. + + The :operator:`$nearSphere` operator queries for points defined by + either :term:`GeoJSON` objects or legacy coordinate pairs. The optional :operator:`$maxDistance` operator limits a - :operator:`$nearSphere` query to return only those documents that fall - within a maximum distance of a point. Specify the maximum distance in - the units specified by the coordinate system. + :operator:`$nearSphere` query to return only those documents that + fall within a maximum distance of a point. If you use + :operator:`$maxDistance` on GeoJSON points, the distance is measured + in meters. If you use :operator:`$maxDistance` on legacy coordinate + pairs, the distance is measured in radians. The :operator:`$nearSphere` operator requires a geospatial index. The - ``2dsphere`` and ``2d`` indexes both support the - :operator:`$nearSphere` operator. In a ``2dsphere`` index, a grid - coordinate is interpreted as a GeoJSON point. + ``2dsphere`` and ``2d`` indexes both support :operator:`$nearSphere`. + In a ``2dsphere`` index, a grid coordinate is interpreted as a + GeoJSON point. + + For queries on GeoJSON data, use the following syntax: + + .. code-block:: javascript + + db..find( { : + { $nearSphere : + { $geometry : + { type : "Point" , + coordinates : [ , ] } , + $maxDistance : + } } } ) + + .. important:: If you use longitude and latitude, specify **longitude first**. - The :operator:`$nearSphere` operator uses the following syntax: + For queries on legacy coordinate pairs, use the following syntax: .. code-block:: javascript db..find( { : { $nearSphere: [ , ] , - $maxDistance: + $maxDistance: } } ) .. important:: If you use longitude and latitude, specify **longitude first**. - The following example selects the 100 documents with coordinates - nearest to ``[ 40 , 5 ]`` as calculated by spherical geometry: + The following example selects the 100 documents with legacy + coordinates pairs nearest to ``[ 40 , 5 ]``, as calculated by + spherical geometry: .. code-block:: javascript diff --git a/source/reference/operator/polygon.txt b/source/reference/operator/polygon.txt index 2488faa6e01..f420277d518 100644 --- a/source/reference/operator/polygon.txt +++ b/source/reference/operator/polygon.txt @@ -9,9 +9,9 @@ $polygon .. versionadded:: 1.9 The :operator:`$polygon` operator specifies a polygon for a - :term:`geospatial` :operator:`$geoWithin` query. The query returns - legacy coordinate pairs that are within the bounds of the polygon. - The operator does *not* query for GeoJSON objects. + :term:`geospatial` :operator:`$geoWithin` query on legacy coordinate + pairs. The query returns pairs that are within the bounds of the + polygon. The operator does *not* query for GeoJSON objects. The :operator:`$polygon` operator calculates distances using flat (planar) geometry. @@ -35,7 +35,7 @@ $polygon like. The following query returns all documents that have coordinates that - exist within the polygon defined by ``[ 0 , 0 ]``, ``[ 3 , 3 ]``, and + exist within the polygon defined by ``[ 0 , 0 ]``, ``[ 3 , 6 ]``, and ``[ 6 , 0 ]``: .. code-block:: javascript