- Reference >
- Database Commands >
- Geospatial Commands >
- geoNear
geoNear¶
On this page
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 isfalse
.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 betrue
.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.
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 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 default level is
"local"
.To use a read concern level of
"majority"
, you must use the WiredTiger storage engine and start themongod
instances with the--enableMajorityReadConcern
command line option (or thereplication.enableMajorityReadConcern
setting if using a configuration file).Only replica sets using
protocol version 1
support"majority"
read concern. Replica sets running protocol version 0 do not support"majority"
read concern.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.New in version 3.2.
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 .
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:
With spherical: true
, if you specify 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
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:
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:
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 a read concern level of
"majority"
, you must use the WiredTiger storage engine and start themongod
instances with the--enableMajorityReadConcern
command line option (or thereplication.enableMajorityReadConcern
setting if using a configuration file).Only replica sets using
protocol version 1
support"majority"
read concern. Replica sets running protocol version 0 do not support"majority"
read concern.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.