- Reference >
- Operators >
- Aggregation Framework Operators >
- Pipeline Aggregation Operators >
- $geoNear (aggregation)
$geoNear (aggregation)¶
On this page
Definition¶
-
$geoNear
¶ New in version 2.4.
$geoNear
returns documents in order of nearest to farthest from a specified point and pass the documents through the aggregation pipeline. You can only use$geoNear
as the first stage of a pipeline.The
$geoNear
operator accepts a document that contains the following fields. Specify all distances in the same units as those of the processed documents’ coordinate system:Field Type Description 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.query
document Optional. Limits the results to the documents that match the query. The query syntax is the usual MongoDB read operation query syntax. spherical
Boolean Required if using a 2dsphere index. For use with
2dsphere
indexes,spherical
must betrue
.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.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. If this value isfalse
, the query returns a document multiple times if the document has multiple matching location fields. See$uniqueDocs
for more information.near
GeoJSON point or legacy coordinate pairs The point for which to find the closest documents. distanceField
string The output field that contains the calculated distance. To specify a field within a subdocument, use dot notation. maxDistance
number Optional. A distance from the center point. Specify the distance in radians. MongoDB limits the results to those documents that fall within the specified distance from the center point. includeLocs
string Optional. This specifies the output field that identifies the location used to calculate the distance. This option is useful when a location field contains multiple locations. To specify a field within a subdocument, use dot notation.
Behavior¶
When using $geoNear
, consider that:
- You must include the
distanceField
option. ThedistanceField
option specifies the field that will contain the calculated distance. - The collection must have a geospatial index.
- The
$geoNear
requires that a collection have at most only one 2d index and/or only one 2dsphere index. - If using a 2dsphere index, you must
specify
spherical: true
.
The options for $geoNear
are similar to the
geoNear
command with the following exceptions:
Example¶
Consider a collection places
that has a 2dsphere
index. The following
aggregation finds at most 5
unique documents with a location at
most 2 units from the center [ -73.99279 , 40.719296 ]
and have type
equal
to public
:
The aggregation returns the following:
The document in the result
array contains two new fields:
dist.calculated
field that contains the calculated distance, anddist.location
field that contains the location used in the calculation.