diff --git a/source/applications/2d.txt b/source/applications/2d.txt index 49b7a17b1b9..f44ab03aa2b 100644 --- a/source/applications/2d.txt +++ b/source/applications/2d.txt @@ -165,9 +165,11 @@ right corner. .. code-block:: javascript - db.places.find( { loc : { $geoWithin : { $box : - [ [ 0 , 0 ] , - [ 100 , 100 ] ] } } } ) + 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``: @@ -175,8 +177,8 @@ on ``[ -74 , 40.74 ]`` and with a radius of ``10``: .. code-block:: javascript db.places.find( { loc: { $geoWithin : - { $center : [ [-74, 40.74], 10 ] } - } } ) + { $center : [ [-74, 40.74 ] , 10 ] + } } } ) For syntax and examples for each shape, see the following: diff --git a/source/applications/2dsphere.txt b/source/applications/2dsphere.txt index 4cb2498bc8a..50b69524d37 100644 --- a/source/applications/2dsphere.txt +++ b/source/applications/2dsphere.txt @@ -6,10 +6,11 @@ .. versionadded:: 2.4 -A ``2dsphere`` index supports queries that calculate geometries on a -sphere. The index supports data stored as both :term:`GeoJSON` objects -and as legacy coordinate pairs. The ``2dsphere`` index supports legacy -coordinate pairs by converting the data to the GeoJSON Point type. +A ``2dsphere`` index supports queries that calculate geometries on an +earth-like sphere. The index supports data stored as both +:term:`GeoJSON` objects and as legacy coordinate pairs. The index +supports legacy coordinate pairs by converting the data to the GeoJSON +"Point" type. The ``2dsphere`` index supports all MongoDB geospatial queries: queries for inclusion, intersection and proximity. @@ -20,8 +21,8 @@ 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. -The default datum for a sphere in MongoDB 2.4 is WGS84 - SRID 4326. -Coordinate-axis order is "longitude, latitude." +The default datum for an earth-like sphere in MongoDB 2.4 is :term:`WGS84`. +Coordinate-axis order is **longitude, latitude**. .. important:: You cannot use a ``2d`` index as a shard key when sharding a collection. However, you can create and maintain a @@ -127,7 +128,8 @@ For an overview of recommended geospatial queries, see GeoJSON Objects Bounded by a Polygon ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To select all points and shapes found within a GeoJSON polygon, your +The :operator:`$geoWithin` operator queries for location data found +within a GeoJSON polygon. Your location data must be stored in GeoJSON format. Use the following syntax: .. code-block:: javascript diff --git a/source/applications/geospatial-indexes.txt b/source/applications/geospatial-indexes.txt index b04a0870d04..60e71faf640 100644 --- a/source/applications/geospatial-indexes.txt +++ b/source/applications/geospatial-indexes.txt @@ -20,23 +20,19 @@ MongoDB offers two surface types: - **Spherical** - To calculate geometries and distances on the earth, store your - location data on a spherical surface. Spherical surface calculations - requires slighly larger data sets but provide accurate data for - calculations on the earth. + To calculate geometry over an Earth-like sphere, store your location + data on a spherical surface and use :doc:`2dsphere + ` index. - The default datum for a sphere in MongoDB 2.4 is WGS84 - SRID 4326. - Coordinate-axis order is "longitude, latitude." - - If you perform calculations on a sphere, store your location data as - GeoJSON objects and use a ``2dsphere`` index. See - :doc:`/applications/2dsphere`. + 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. - **Flat** To calculate distances on a Euclidean plane, store your location data - as points on a flat surface. Use the ``2d`` index. See - :doc:`/applications/2d`. + as legacy coordinate pairs and use a :doc:`2d ` index. Location Data ------------- @@ -45,7 +41,8 @@ If you choose spherical surface calculations, you store location data as - :term:`GeoJSON` objects (preferred). - Queries on GeoJSON objects always calculate on a sphere. + Queries on GeoJSON objects always calculate on a sphere. The default + coordinate reference system for GeoJSON uses the :term:`WGS84` datum. .. versionadded:: 2.4 The storage and querying of GeoJSON objects is new in version 2.4. Prior to version 2.4, all geospatial data was @@ -65,7 +62,7 @@ Query Operations MongoDB's geospatial query operators let you query for: - **Inclusion**. MongoDB can query for locations contained entirely - within a specified geometry. Inclusion queries use the + within a specified polygon. Inclusion queries use the :operator:`$geoWithin` operator. - **Intersection**. MongoDB can query for locations that intersect with @@ -73,7 +70,8 @@ MongoDB's geospatial query operators let you query for: surface. These queries use the :operator:`$geoIntersects` operator. - **Proximity**. MongoDB can query for the points nearest to another - point. Proximity queries use the :operator:`$near` operator. + point. Proximity queries use the :operator:`$near` operator. The + :operator:`$near` operator requires a ``2d`` or ``2dsphere`` index. Geospatial Indexes ------------------ diff --git a/source/core/geospatial-indexes.txt b/source/core/geospatial-indexes.txt index 3d03df583e2..6b11a8eb880 100644 --- a/source/core/geospatial-indexes.txt +++ b/source/core/geospatial-indexes.txt @@ -4,7 +4,7 @@ Geospatial Index Internals .. default-domain:: mongodb -This document provides a more in-depth explanation of the internals supporting +This document provides a more in-depth explanation of the internals of MongoDB's geospatial features. This material is not necessary for normal operations or application development but may be useful for troubleshooting and for further understanding MongoDB's behavior and approach. diff --git a/source/includes/table-geospatial-queries.yaml b/source/includes/table-geospatial-queries.yaml index 3748b2e9ee7..5bd9dc5e926 100644 --- a/source/includes/table-geospatial-queries.yaml +++ b/source/includes/table-geospatial-queries.yaml @@ -40,7 +40,7 @@ query2: | .. code-block:: javascript { $geoWithin : { - $geometry : + $geometry : } } geometry2: | polygon diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 35255b9ff62..e1807576e2c 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -911,10 +911,11 @@ Glossary coordinate system. datum - A datum is a set of values used to define measurements on the earth. MongoDB's - :doc:`2dsphere index ` uses the WGS84 - SRID 4326 - datum. + A datum is a set of values used to define measurements on the + earth. MongoDB uses the :term:`WGS84` datum. WGS84 - The :term:`datum` MongoDB uses to define measurements in - geospatial queries for locations on the earth. + The default :term:`datum` MongoDB uses to calculate geometry over + an Earth-like sphere. MongoDB uses the WGS84 datum for geospatial + queries on :term:`GeoJSON` objects. See + `http://spatialreference.org/ref/epsg/4326/ `_. diff --git a/source/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes.txt b/source/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes.txt index b35c86019a8..9547cbe2a7f 100644 --- a/source/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes.txt +++ b/source/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes.txt @@ -108,8 +108,8 @@ The output of the above command would be: Distance Multiplier ------------------- -The ``distanceMultiplier`` option :dbcommand:`geoNear` returns distances -only after multiplying the results by an assigned value. This allows +The ``distanceMultiplier`` option of the :dbcommand:`geoNear` command returns +distances only after multiplying the results by an assigned value. This allows MongoDB to return converted values, and removes the requirement to convert units in application logic.