OPTIONS

$geoNear (aggregation)

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.

The $geoNear operator accepts a document that contains the following fields. Specify all distances in the same unites as the document coordinate system:

Field Type Description
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.
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.
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.
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 stage.

spherical Boolean Optional. If true, MongoDB references points using a spherical surface. 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.
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.
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.

Behavior

When using $geoNear, consider that:

  • You can only use $geoNear as the first stage of a pipeline.
  • 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.
  • You cannot specify a $near predicate in the query field of the $geoNear stage.

Generally, 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

The following aggregation finds at most 5 unique documents with a location at most .008 from the center [40.72, -73.99] and have type equal to public:

db.places.aggregate([
                      {
                        $geoNear: {
                                    near: [40.724, -73.997],
                                    distanceField: "dist.calculated",
                                    maxDistance: 0.008,
                                    query: { type: "public" },
                                    includeLocs: "dist.location",
                                    num: 5
                                  }
                      }
                   ])

The aggregation returns the following:

{
  "result" : [
               { "_id" : 7,
                 "name" : "Washington Square",
                 "type" : "public",
                 "location" : [
                                [ 40.731, -73.999 ],
                                [ 40.732, -73.998 ],
                                [ 40.730, -73.995 ],
                                [ 40.729, -73.996 ]
                              ],
                 "dist" : {
                            "calculated" : 0.0050990195135962296,
                            "location" : [ 40.729, -73.996 ]
                          }
               },
               { "_id" : 8,
                 "name" : "Sara D. Roosevelt Park",
                 "type" : "public",
                 "location" : [
                                [ 40.723, -73.991 ],
                                [ 40.723, -73.990 ],
                                [ 40.715, -73.994 ],
                                [ 40.715, -73.994 ]
                              ],
                 "dist" : {
                            "calculated" : 0.006082762530298062,
                            "location" : [ 40.723, -73.991 ]
                          }
               }
             ],
  "ok" : 1
}

The matching documents in the result field contain two new fields:

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