DOCS-11099: clarifies spherical behavior, adds keys param to geoNear

Author: schmalliso

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 </core/2dsphere>`
+    indexes and planar geometry for :doc:`2d </core/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 </core/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 </core/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 <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
 ...

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
 ...

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 </core/2dsphere>` and/or only
-one :doc:`2d index </core/2d>` .
+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: <collection> ,
-      near: { type: "Point" , coordinates: [ <coordinates> ] } ,
-      spherical: true,
+      geoNear : <collection> ,
+      near : { type : "Point" , coordinates : [ <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: <collection> ,
-      near: [ <coordinates> ],
-      spherical: true,
+      geoNear : <collection> ,
+      near : [ <coordinates> ],
+      spherical : true,
       ...
    } )
 
@@ -94,12 +93,12 @@ To query a :doc:`2d </core/2d>` index, use the following syntax:
 .. code-block:: javascript
 
    db.runCommand( {
-      geoNear: <collection>,
+      geoNear : <collection>,
       near : [ <coordinates> ],
       ...
    } )
 
-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 <orphaned document>`. 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
+</core/2dsphere>` index on the ``location`` field **and** a
+:doc:`2d </core/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.

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 </core/2d>` and/or only one
-  :doc:`2dsphere index </core/2dsphere>`.
-
-- 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 </core/2dsphere>`, 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
+</core/2dsphere>` index on the ``location`` field and a
+:doc:`2d </core/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
+      }
+   }
+

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
-  </core/2dsphere>` index only.
-
   If :query:`$near` or :query:`$nearSphere` query specifies the center
   point as a :ref:`GeoJSON point <geojson-point>`, specify the distance
   as a non-negative number in *meters*.