diff --git a/source/includes/apiargs-dbcommand-geoNear-field.yaml b/source/includes/apiargs-dbcommand-geoNear-field.yaml index dcd46ff9cad..15da8d078e5 100644 --- a/source/includes/apiargs-dbcommand-geoNear-field.yaml +++ b/source/includes/apiargs-dbcommand-geoNear-field.yaml @@ -28,16 +28,17 @@ type: --- arg_name: field description: | - Required if using a ``2dsphere`` index. Determines how MongoDB - calculates the distance. The default value is ``false``. + Determines how MongoDB calculates the distance between two points: + + - When ``true``, MongoDB uses :query:`$nearSphere` semantics and + calculates distances using spherical geometry. + + - When ``false``, MongoDB uses :query:`$near` semantics: + spherical geometry for :doc:`2dsphere ` + indexes and planar geometry for :doc:`2d ` indexes. - .. include:: /includes/extracts/geoNear-distance-calculation-spherical-field.rst + *Default: false.* - If ``false``, then MongoDB uses 2d planar geometry to calculate - distance between points. - - If using a :doc:`2dsphere ` index, ``spherical`` must - be ``true``. interface: command name: spherical operation: geoNear @@ -74,8 +75,6 @@ description: | be. MongoDB filters the results to those documents that are *at least* the specified distance from the center point. - Only available for use with :doc:`2dsphere ` index. - Specify the distance in meters if the specified point is :term:`GeoJSON` and in radians if the specified point is :term:`legacy coordinate pairs `. @@ -173,4 +172,28 @@ optional: true operation: geoNear arg_name: field interface: dbcommand +--- +arg_name: field +name: key +type: string +operation: geoNear +interface: dbcommand +position: 13 +description: | + Specify the geospatial index to use when calculating the distance. + If your collection has multiple geospatial indexes, you **must** + use the ``key`` option to specify the indexed field path to use. + {{example}} provides a full example. + + If you do not specify the field over which to perform the search with + ``key``, MongoDB will attempt to look for a usable ``2d`` or + ``2dsphere`` index, in that order. If there is more than one ``2d`` + index or more than one ``2dsphere`` index, MongoDB will return an + error. + + .. versionadded:: 4.0 + +replacement: + example: ":ref:`dbcommand-geoNear-key-param-example`" +optional: true ... diff --git a/source/includes/apiargs-pipeline-geoNear-field.yaml b/source/includes/apiargs-pipeline-geoNear-field.yaml index 9fc577feb4f..afae7c3ff12 100644 --- a/source/includes/apiargs-pipeline-geoNear-field.yaml +++ b/source/includes/apiargs-pipeline-geoNear-field.yaml @@ -86,7 +86,7 @@ source: file: apiargs-dbcommand-geoNear-field.yaml ref: uniqueDocs --- -position: 10 +position: 11 name: minDistance type: number optional: true @@ -103,4 +103,14 @@ description: | interface: pipeline operation: geoNear arg_name: field +--- +arg_name: field +interface: pipeline +operation: geoNear +source: + file: apiargs-dbcommand-geoNear-field.yaml + ref: key +replacement: + example: ":ref:`pipeline-geoNear-key-param-example`" +position: 12 ... diff --git a/source/reference/command/geoNear.txt b/source/reference/command/geoNear.txt index 8ccf069e8ad..b164a08b3ae 100644 --- a/source/reference/command/geoNear.txt +++ b/source/reference/command/geoNear.txt @@ -41,10 +41,10 @@ Considerations -------------- .. include:: /includes/extracts/geoNear-command-index-requirement.rst - -However, the :dbcommand:`geoNear` command requires that a collection -have *at most* only one :doc:`2dsphere ` and/or only -one :doc:`2d index ` . +If you have more than one geospatial index on the collection, use the +``keys`` parameter to specify which field to use in the calculation. If +you have only one geospatial index, :dbcommand:`geoNear` implicitly uses +the indexed field for the calculation. .. include:: /includes/extracts/views-unsupported-geoNear.rst @@ -60,29 +60,28 @@ Command Syntax If using a ``2dsphere`` index, you can specify either a ``GeoJSON`` point or a legacy coordinate pair for the ``near`` value. -You must include ``spherical: true`` in the syntax. - -With ``spherical: true``, if you specify a GeoJSON point, MongoDB uses +If you specify a GeoJSON point, MongoDB uses meters as the unit of measurement: .. code-block:: javascript db.runCommand( { - geoNear: , - near: { type: "Point" , coordinates: [ ] } , - spherical: true, + geoNear : , + near : { type : "Point" , coordinates : [ ] } , + spherical : true, ... } ) -With ``spherical: true``, if you specify a legacy coordinate pair, +If you specify a legacy coordinate pair, you *must* specify ``spherical : true`` +With ``spherical : true`` and a legacy coordinate pair, MongoDB uses radians as the unit of measurement: .. code-block:: javascript db.runCommand( { - geoNear: , - near: [ ], - spherical: true, + geoNear : , + near : [ ], + spherical : true, ... } ) @@ -94,12 +93,12 @@ To query a :doc:`2d ` index, use the following syntax: .. code-block:: javascript db.runCommand( { - geoNear: , + geoNear : , near : [ ], ... } ) -If you specify ``spherical: true``, MongoDB uses spherical geometry to +If you specify ``spherical : true``, MongoDB uses spherical geometry to calculate distances in radians. Otherwise, MongoDB uses planar geometry to calculate distances between points. @@ -115,16 +114,15 @@ farthest, the ``minDistance`` field effectively skips over the first *n* documents where *n* is determined by the distance requirement. The :dbcommand:`geoNear` command provides an alternative to the -:query:`$near` operator. In addition to the functionality of -:query:`$near`, :dbcommand:`geoNear` returns additional diagnostic +:query:`$near` and :query:`$nearSphere` operators. +In addition to the functionality of +:query:`$near` and :query:`$nearSphere`, :dbcommand:`geoNear` returns diagnostic information. In a :term:`sharded cluster`, the :dbcommand:`geoNear` command may return :term:`orphaned documents `. To avoid this, consider using the :pipeline:`$geoNear` aggregation stage as an alternative. -.. read-lock, slave-ok - Examples -------- @@ -240,8 +238,100 @@ The operation returns the following output: "ok" : 1 } +.. _dbcommand-geoNear-key-param-example: + +Specify Which Geospatial Index to Use +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.0 + +Consider a ``places`` collection that has a :doc:`2dsphere +` index on the ``location`` field **and** a +:doc:`2d ` index on the ``legacy`` field. + +A document in the ``places`` collection resembles the following: + +.. code-block:: javascript + + { + "_id" : 3, + "name" : "Polo Grounds", + "location": { + "type" : "Point", + "coordinates" : [ -73.9375, 40.8303 ] + }, + "legacy" : [ -73.9375, 40.8303 ], + "category" : "Stadiums" + } + +The following example uses the ``keys`` parameter to specify that the +operation should use the ``location`` field values for the +:pipeline:`$geoNear` operation rather than the ``legacy`` field values. + +.. code-block:: javascript + + db.runCommand( + { + geoNear : "places", + near : { type : "Point", coordinates : [ -73.98142 , 40.71782 ] }, + key : "location", + query : { "category" : "Parks" } + } + ) + +The operation returns the following: + +.. code-block:: javascript + + { + "results" : [ + { + "dis" : 974.175764916902, + "obj" : { + "_id" : 2, + "name" : "Sara D. Roosevelt Park", + "location" : { + "type" : "Point", + "coordinates" : [ + -73.9928, + 40.7193 + ] + }, + "category" : "Parks" + } + }, + { + "dis" : 5887.92792958097, + "obj" : { + "_id" : 1, + "name" : "Central Park", + "location" : { + "type" : "Point", + "coordinates" : [ + -73.97, + 40.77 + ] + }, + "legacy" : [ + -73.97, + 40.77 + ], + "category" : "Parks" + } + } + ], + "stats" : { + "nscanned" : 19, + "objectsLoaded" : 6, + "avgDistance" : 3431.051847248936, + "maxDistance" : 5887.92792958097, + "time" : 2946 + }, + "ok" : 1 + + Override Default Read Concern -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To override the default read concern level of :readconcern:`"local"`, use the ``readConcern`` option. diff --git a/source/reference/operator/aggregation/geoNear.txt b/source/reference/operator/aggregation/geoNear.txt index b1341a8ce36..a6593d9c0e2 100644 --- a/source/reference/operator/aggregation/geoNear.txt +++ b/source/reference/operator/aggregation/geoNear.txt @@ -44,19 +44,10 @@ When using :pipeline:`$geoNear`, consider that: the calculated distance. - .. include:: /includes/extracts/geoNear-stage-index-requirement.rst - -- The :pipeline:`$geoNear` requires that a collection have *at most* - only one :doc:`2d index ` and/or only one - :doc:`2dsphere index `. - -- You do not need to specify which field in - the documents hold the coordinate pair or point. Because - :pipeline:`$geoNear` requires that the collection have a single - geospatial index, :pipeline:`$geoNear` implicitly uses the indexed - field. - -- If using a :doc:`2dsphere index `, you must specify - ``spherical: true``. + If you have more than one geospatial index on the collection, use the + ``keys`` parameter to specify which field to use in the calculation. + If you have only one geospatial index, :pipeline:`$geoNear` implicitly + uses the indexed field for the calculation. .. |geoNear| replace:: :pipeline:`$geoNear` stage @@ -152,3 +143,86 @@ specified distance from the center point. } } ]) + +.. _pipeline-geoNear-key-param-example: + +Specify Which Geospatial Index to Use +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.0 + +Consider a ``places`` collection that has a :doc:`2dsphere +` index on the ``location`` field and a +:doc:`2d ` index on the ``legacy`` field. + +A document in the ``places`` collection resembles the following: + +.. code-block:: javascript + + { + "_id" : 3, + "name" : "Polo Grounds", + "location": { + "type" : "Point", + "coordinates" : [ -73.9375, 40.8303 ] + }, + "legacy" : [ -73.9375, 40.8303 ], + "category" : "Stadiums" + } + +The following example uses the ``keys`` option to specify that the +aggregation should use the ``location`` field values for the +:pipeline:`$geoNear` operation rather than the ``legacy`` field values. + +.. code-block:: javascript + + db.places.aggregate([ + { + $geoNear: { + near: { type: "Point", coordinates: [ -73.98142 , 40.71782 ] }, + key: "location", + distanceField: "dist.calculated", + query: { "category": "Parks" } + } + } + ]) + +The aggregation returns the following: + +.. code-block:: javascript + + { + "_id" : 2, + "name" : "Sara D. Roosevelt Park", + "location" : { + "type" : "Point", + "coordinates" : [ + -73.9928, + 40.7193 + ] + }, + "category" : "Parks", + "dist" : { + "calculated" : 974.175764916902 + } + } + { + "_id" : 1, + "name" : "Central Park", + "location" : { + "type" : "Point", + "coordinates" : [ + -73.97, + 40.77 + ] + }, + "legacy" : [ + -73.97, + 40.77 + ], + "category" : "Parks", + "dist" : { + "calculated" : 5887.92792958097 + } + } + diff --git a/source/reference/operator/query/minDistance.txt b/source/reference/operator/query/minDistance.txt index 6f64bcec440..174fb157101 100644 --- a/source/reference/operator/query/minDistance.txt +++ b/source/reference/operator/query/minDistance.txt @@ -21,9 +21,6 @@ Definition :query:`$nearSphere` query to those documents that are *at least* the specified distance from the center point. - :query:`$minDistance` is available for use with :doc:`2dsphere - ` index only. - If :query:`$near` or :query:`$nearSphere` query specifies the center point as a :ref:`GeoJSON point `, specify the distance as a non-negative number in *meters*. diff --git a/source/reference/operator/query/near.txt b/source/reference/operator/query/near.txt index 764d9585a61..e1328d37b4c 100644 --- a/source/reference/operator/query/near.txt +++ b/source/reference/operator/query/near.txt @@ -54,8 +54,6 @@ Definition - :query:`$minDistance` limits the results to those documents that are *at least* the specified distance from the center point. - :query:`$minDistance` is only available for use with - :doc:`2dsphere ` index. .. versionadded:: 2.6 diff --git a/source/reference/operator/query/nearSphere.txt b/source/reference/operator/query/nearSphere.txt index 8596cd69403..710fc0ab362 100644 --- a/source/reference/operator/query/nearSphere.txt +++ b/source/reference/operator/query/nearSphere.txt @@ -48,10 +48,9 @@ Definition } } - - The *optional* :query:`$minDistance` is available only if the - query uses the :doc:`2dsphere ` index. - :query:`$minDistance` limits the results to those documents that - are *at least* the specified distance from the center point. + - The *optional* :query:`$minDistance` limits the results to those + documents that are *at least* the specified distance from the + center point. .. versionadded:: 2.6 diff --git a/source/release-notes/4.0.txt b/source/release-notes/4.0.txt index 11a7af1fe09..b5c6f5c17cf 100644 --- a/source/release-notes/4.0.txt +++ b/source/release-notes/4.0.txt @@ -706,13 +706,6 @@ support matrix. General Improvements -------------------- -Query Operators -~~~~~~~~~~~~~~~ - -- The geospatial query operators :query:`$near` and - :query:`$nearSphere` now supports querying on sharded collections. - - Commands ~~~~~~~~ @@ -758,6 +751,26 @@ Commands running on a :binary:`~bin.mongos`. When run on the ``mongos``, :dbcommand:`killOp` can kill queries that are running in more than one shard. +Geospatial Query Improvements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The geospatial query operators :query:`$near` and + :query:`$nearSphere` now supports querying on sharded collections. + +- As of MongoDB 4.0, the :pipeline:`$geoNear` aggregation operator and + :dbcommand:`geoNear` command support using the ``minDistance`` option + with :doc:`2d ` indexes. Similarly, :query:`$near` and + :query:`$nearSphere` support the ``$minDistance`` option for :doc:`2d + ` indexes. Previously, ``minDistance`` and ``$minDistance`` + were only available for :doc:`2dsphere ` indexes. + +- MongoDB 4.0 adds a ``key`` option for the :pipeline:`$geoNear` + aggregation operator and :dbcommand:`geoNear` command that enables + users to specify which geospatial index to use when querying a + collection with multiple geospatial indexes. Previously, to use the + :pipeline:`$geoNear` aggregation operator or :dbcommand:`geoNear` + command, the collection could only have one geospatial index. + Network Layer Improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -888,4 +901,3 @@ of the related projects. /release-notes/4.0-downgrade-standalone /release-notes/4.0-downgrade-replica-set /release-notes/4.0-downgrade-sharded-cluster -