• Reference >
• Database Commands >
• Geospatial Commands >
• geoNear

geoNear

Definition

geoNear

Deprecated since version 4.0

Starting in version 4.0, MongoDB deprecates the geoNear command. Use one of the following operations instead.

• $geoNear aggregation stage.
• $near query operator.
• $nearSphere query operator.

Returns documents in order of proximity to a specified point, from the nearest to farthest. geoNear requires a geospatial index.

The geoNear command accepts a document that contains the following fields. Specify all distances in the same units as the document coordinate system:

Field	Type	Description
geoNear	string	The collection to query.
near	GeoJSON point or legacy coordinate pair	The point for which to find the closest documents. If using a 2dsphere index, you can specify the point as either a GeoJSON point or legacy coordinate pair. If using a 2d index, specify the point as a legacy coordinate pair.
spherical	boolean	Determines how MongoDB calculates the distance between two points: When true, MongoDB uses $nearSphere semantics and calculates distances using spherical geometry. When false, MongoDB uses $near semantics: spherical geometry for 2dsphere indexes and planar geometry for 2d indexes. Default: false.
limit	number	Optional. The maximum number of documents to return. The default value is 100. See also the num option.
num	number	Optional. The num option provides the same function as the limit option. Both define the maximum number of documents to return. If both options are included, the num value overrides the limit value.
minDistance	number	Optional. The minimum distance from the center point that the documents must be. MongoDB filters the results to those documents that are at least the specified distance from the center point. Specify the distance in meters if the specified point is GeoJSON and in radians if the specified point is legacy coordinate pairs. New in version 2.6.
maxDistance	number	Optional. The maximum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall within the specified distance from the center point. Specify the distance in meters if the specified point is GeoJSON and in radians if the specified point is legacy coordinate pairs.
query	document	Optional. Limits the results to the documents that match the query. The query syntax is the usual MongoDB read operation query syntax. You cannot specify a $near predicate in the query field of the geoNear command.
distanceMultiplier	number	Optional. The factor to multiply all distances returned by the query. For example, use the distanceMultiplier to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth.
includeLocs	boolean	Optional. If this is true, the query returns the location of the matching documents in the results. The default is false. This option is useful when a location field contains multiple locations. To specify a field within an embedded document, use dot notation.
uniqueDocs	boolean	Optional. If this value is true, the query returns a matching document once, even if more than one of the document’s location fields match the query. Deprecated since version 2.6: Geospatial queries no longer return duplicate results. The $uniqueDocs operator has no impact on results.
readConcern	document	Optional. Specifies the read concern. The readConcern option has the following syntax: Changed in version 3.6. copy readConcern: { level: <value> } Possible read concern levels are: "local". This is the default read concern level. "available". This is the default for reads against secondaries when Read Operations and afterClusterTime and “level” are unspecified. The query returns the instance’s most recent data. "majority". Available for replica sets that use WiredTiger storage engine. "linearizable". Available for read operations on the primary only. For more formation on the read concern levels, see Read Concern Levels. For "local" (default) or "majority" read concern level, you can specify the afterClusterTime option to have the read operation return data that meets the level requirement and the specified after cluster time requirement. For more information, see Read Operations and afterClusterTime.
key	string	Optional. Specify the geospatial indexed field to use when calculating the distance. If your collection has multiple 2d and/or multiple 2dsphere indexes, you must use the key option to specify the indexed field path to use. Specify Which Geospatial Index to Use provides a full example. If there is more than one 2d index or more than one 2dsphere index and you do not specify a key, MongoDB will return an error. If you do not specify the key, and you have at most only one 2d index and/or only one 2dsphere index, MongoDB looks first for a 2d index to use. If a 2d index does not exists, then MongoDB looks for a 2dsphere index to use. New in version 4.0.

Considerations

The deprecated geoNear command requires a geospatial 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, geoNear implicitly uses the indexed field for the calculation.

Views do not support geoNear operations (i.e. $geoNear pipeline stage and the deprecated geoNear command).

You cannot specify a $near predicate in the query field of the geoNear command.

Command Syntax

2dsphere Index

If using a 2dsphere index, you can specify either a GeoJSON point or a legacy coordinate pair for the near value.

If you specify a GeoJSON point, MongoDB uses meters as the unit of measurement:

copy

db.runCommand( {
   geoNear : <collection> ,
   near : { type : "Point" , coordinates : [ <coordinates> ] } ,
   spherical : true,
   ...
} )

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:

copy

db.runCommand( {
   geoNear : <collection> ,
   near : [ <coordinates> ],
   spherical : true,
   ...
} )

2d Index

To query a 2d index, use the following syntax:

copy

db.runCommand( {
   geoNear : <collection>,
   near : [ <coordinates> ],
   ...
} )

If you specify spherical : true, MongoDB uses spherical geometry to calculate distances in radians. Otherwise, MongoDB uses planar geometry to calculate distances between points.

Behavior

geoNear sorts documents by distance. If you also include a sort() for the query, sort() re-orders the matching documents, effectively overriding the sort operation already performed by geoNear. When using sort() with geospatial queries, consider using $geoWithin operator, which does not sort documents, instead of geoNear.

Because geoNear orders the documents from nearest to farthest, the minDistance field effectively skips over the first n documents where n is determined by the distance requirement.

The geoNear command provides an alternative to the $near and $nearSphere operators. In addition to the functionality of $near and $nearSphere, geoNear returns diagnostic information.

In a sharded cluster, the geoNear command may return orphaned documents. To avoid this, consider using the $geoNear aggregation stage as an alternative.

Examples

The following examples run the geoNear command on the collection places that has a 2dsphere index.

Specify a Query Condition

The following geoNear command queries for documents whose category equals "public" and returns the matching documents in order of nearest to farthest to the specified point:

copy

db.runCommand(
   {
     geoNear: "places",
     near: { type: "Point", coordinates: [ -73.9667, 40.78 ] },
     spherical: true,
     query: { category: "public" }
   }
)

The operation returns the following output, the documents in the results from nearest to farthest:

copy

{
  "results" : [
     {
       "dis" : 0,
       "obj" : {
          "_id" : 2,
          "location" : { "type" : "Point", "coordinates" : [ -73.9667, 40.78 ] },
          "name" : "Central Park",
          "category" : "public"
       }
     },
     {
       "dis" : 3245.988787957091,
       "obj" : {
          "_id" : 3,
          "location" : { "type" : "Point", "coordinates" : [ -73.9836, 40.7538 ] },
          "name" : "Bryant Park",
          "category" : "public"
       }
     },
     {
       "dis" : 7106.506152782733,
       "obj" : {
          "_id" : 4,
          "location" : { "type" : "Point", "coordinates" : [ -73.9928, 40.7193 ] },
          "name" : "Sara D. Roosevelt Park",
          "category" : "public"
       }
     },

  ],
  "stats" : {
     "nscanned" : NumberLong(47),
     "objectsLoaded" : NumberLong(47),
     "avgDistance" : 3450.8316469132747,
     "maxDistance" : 7106.506152782733,
     "time" : 4
  },
  "ok" : 1
}

Specify a minDistance and maxDistance

The following example specifies a minDistance of 3000 meters and maxDistance of 7000 meters:

copy

db.runCommand(
   {
     geoNear: "places",
     near: { type: "Point", coordinates: [ -73.9667, 40.78 ] },
     spherical: true,
     query: { category: "public" },
     minDistance: 3000,
     maxDistance: 7000
   }
)

The operation returns the following output:

copy

{
  "results" : [
     {
       "dis" : 3245.988787957091,
       "obj" : {
          "_id" : 3,
          "location" : { "type" : "Point", "coordinates" : [ -73.9836, 40.7538 ] },
          "name" : "Bryant Park",
          "category" : "public"
       }
     }
  ],
  "stats" : {
      "nscanned" : NumberLong(11),
      "objectsLoaded" : NumberLong(11),
      "avgDistance" : 3245.988787957091,
      "maxDistance" : 3245.988787957091,
      "time" : 0
  },
  "ok" : 1
}

Specify Which Geospatial Index to Use

New in version 4.0.

Consider a places collection that has a 2dsphere index on the location field and a 2d index on the legacy field.

A document in the places collection resembles the following:

copy

{
   "_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 $geoNear operation rather than the legacy field values.

copy

db.runCommand(
   {
     geoNear : "places",
     near : { type : "Point", coordinates : [ -73.98142 , 40.71782 ] },
     key : "location",
     query : { "category" : "Parks" }
   }
)

The operation returns the following:

copy

{
   "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 "local", use the readConcern option.

The following operation on a replica set specifies a Read Concern of "majority" to read the most recent copy of the data confirmed as having been written to a majority of the nodes.

Note

• To use read concern level of "majority", replica sets must use WiredTiger storage engine.

  For MongoDB 4.0.3+ (and 3.6.1+), you can disable read concern "majority". For more information, see Disable Read Concern Majority.

• Regardless of the read concern level, the most recent data on a node may not reflect the most recent version of the data in the system.

copy

db.runCommand(
   {
      geoNear: "places",
      near: { type: "Point", coordinates: [ -73.9667, 40.78 ] },
      spherical: true,
      query: { category: "public" },
      readConcern: { level: "majority" }
   }
)

To ensure that a single thread can read its own writes, use "majority" read concern and "majority" write concern against the primary of the replica set.

Output

The geoNear command returns a document with the following fields:

geoNear.results

An array with the results of the geoNear command, sorted by distance with the nearest result listed first and farthest last.

geoNear.results[n].dis

For each document in the results, the distance from the coordinates defined in the geoNear command.

geoNear.results[n].obj

The document from the collection.

geoNear.stats

An object with statistics about the query used to return the results of the geoNear search.

geoNear.stats.nscanned

The total number of index entries scanned during the database operation.

geoNear.stats.objectsLoaded

The total number of documents read from disk during the database operation.

geoNear.stats.avgDistance

The average distance between the coordinates defined in the geoNear command and coordinates of the documents returned as results.

geoNear.stats.maxDistance

The maximum distance between the coordinates defined in the geoNear command and coordinates of the documents returned as results.

geoNear.stats.time

The execution time of the database operation, in milliseconds.

geoNear.ok

A value of 1 indicates the geoNear search succeeded. A value of 0 indicates an error.

←   Geospatial Commands geoSearch  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.