OPTIONS

geoNear

Definition

geoNear

Specifies a point for which a geospatial query returns the closest documents first. The query returns the documents from nearest to farthest. The geoNear command provides an alternative to the $near operator. In addition to the functionality of $near, geoNear returns additional diagnostic information.

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 pairs The point for which to find the closest documents.
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.

Only available for use with 2dsphere index.

Specify the distance in meters for GeoJSON data and in radians for 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 for GeoJSON data and in radians for 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.

spherical Boolean

Required if using a 2dsphere index. For use with 2dsphere indexes, spherical must be true.

The default value is false.

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 a subdocument, 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.

Considerations

The geoNear command can use either a GeoJSON point or legacy coordinate pairs. Queries that use a 2d index return a limit of 100 documents.

The geoNear command requires that a collection have at most only one 2d index and/or only one 2dsphere.

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

Behavior

geoNear always returns the documents sorted by distance. Any other sort order requires to sort the documents in memory, which can be inefficient. To return results in a different sort order, use the $geoWithin operator and the sort() method.

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.

Command Format

2dsphere Index

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

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

You must include spherical: true.

2d Index

To query a 2d index, use:

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

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:

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:

{
  "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:

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:

{
  "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
}

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.