$geoNear (aggregation)¶

On this page

Definition
Behavior
Example

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 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.
`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 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.
`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 is `false`, 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. The distanceField 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:

distanceField is a mandatory field for the $geoNear pipeline operator; the option does not exist in the geoNear command.
includeLocs accepts a string in the $geoNear pipeline operator and a boolean in the geoNear command.

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:

copy

db.places.aggregate([
    {
      $geoNear: {
         near : { type : "Point", coordinates : [ -73.99279 , 40.719296 ] },
         distanceField: "dist.calculated",
         maxDistance: 2,
         query: { type: "public" },
         includeLocs: "dist.location",
         uniqueDocs: true,
         num: 5,
         spherical: true
      }
    }
])

The aggregation returns the following:

copy

{
   "result" : [
      {
        "_id" : 8,
        "name" : "Sara D. Roosevelt Park",
        "type" : "public",
        "location" : {
            "type" : "Point",
            "coordinates" : [ -73.9928, 40.7193 ]
         },
         "dist" : {
            "calculated" : 0.9546646278778689,
            "location" : {
               "type": "Point",
               "coordinates" : [ -73.9928, 40.7193 ]
            }
         }
      }
   ],
   "ok" : 1
}

The document in the result array contains two new fields:

dist.calculated field that contains the calculated distance, and
dist.location field that contains the location used in the calculation.

← $sort (aggregation) Group Aggregation Operators →