- Reference >
- Database Commands >
- Geospatial Commands >
- geoNear
geoNear¶
On this page
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 thenum
option.num
number Optional. The num
option provides the same function as thelimit
option. Both define the maximum number of documents to return. If both options are included, thenum
value overrides thelimit
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 thequery
field of thegeoNear
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 isfalse
. 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.
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 theprimary
only.
For more formation on the read concern levels, see Read Concern Levels.
For
"local"
(default) or"majority"
read concern level, you can specify theafterClusterTime
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 multiple2dsphere
indexes, you must use thekey
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 one2dsphere
index and you do not specify akey
, MongoDB will return an error.If you do not specify the
key
, and you have at most only one2d
index and/or only one2dsphere
index, MongoDB looks first for a2d
index to use. If a2d
index does not exists, then MongoDB looks for a2dsphere
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:
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:
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:
The operation returns the following output, the documents in the results
from
nearest to farthest:
Specify a minDistance
and maxDistance
¶
The following example specifies a minDistance
of 3000
meters
and maxDistance
of 7000
meters:
The operation returns the following output:
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:
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.
The operation returns the following:
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.
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.