geoNear¶

On this page

Definition
Considerations
Command Syntax
Behavior
Examples
Output

Definition¶

geoNear¶

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	Required if using a `2dsphere` index. Determines how MongoDB calculates the distance. The default value is `false`. If `true`, then MongoDB uses spherical geometry to calculate distances in meters if the specified (`near`) point is a GeoJSON point and in radians if the specified (`near`) point is a legacy coordinate pair. If `false`, then MongoDB uses 2d planar geometry to calculate distance between points. If using a 2dsphere index, `spherical` must be `true`.
`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 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 option has the following syntax: copy readConcern: { level: <value> } Possible read concern values are: `"local"`. This is the default read concern level. `"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.

Considerations¶

geoNear requires a geospatial index.

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

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

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.

You must include spherical: true in the syntax.

With spherical: true, 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,
   ...
} )

With spherical: true, if you specify 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 operator. In addition to the functionality of $near, geoNear returns additional diagnostic information.

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
}

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",
- you must start the mongod instances with the --enableMajorityReadConcern command line option (or the replication.enableMajorityReadConcern set to true if using a configuration file).
- replica sets must use WiredTiger storage engine and election protocol version 1.
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 →

geoNear¶

Definition¶

Considerations¶

Command Syntax¶

2dsphere Index¶

2d Index¶

Behavior¶

Examples¶

Specify a Query Condition¶

Specify a minDistance and maxDistance¶

Override Default Read Concern¶

Output¶

`2dsphere` Index¶

`2d` Index¶

Specify a `minDistance` and `maxDistance`¶