$near

Definition

• $near
• Specifies a point for which a geospatial query returns thedocuments from nearest to farthest. The $near operator canspecify either a GeoJSON point or legacy coordinate point.

$near requires a geospatial index:

• 2dsphere index if specifying aGeoJSON point,
• 2d index if specifying a point using legacycoordinates.To specify a GeoJSON point, $near operator requiresa 2dsphere index and has the followingsyntax:

{
   <location field>: {
     $near: {
       $geometry: {
          type: "Point" ,
          coordinates: [ <longitude> , <latitude> ]
       },
       $maxDistance: <distance in meters>,
       $minDistance: <distance in meters>
     }
   }
}

If specifying latitude and longitude coordinates, list thelongitude first and then latitude:

• Valid longitude values are between -180 and 180, bothinclusive.

• Valid latitude values are between -90 and 90, bothinclusive.When specifying a GeoJSON point, you can use the optional$minDistance and $maxDistance specifications tolimit the $near results by distance in meters:

• $minDistance limits the results to those documents thatare at least the specified distance from the center point.

New in version 2.6.

• $maxDistance limits the results to those documents thatare at most the specified distance from the center point.

To specify a point using legacy coordinates, $near requiresa 2d index and has the following syntax:

{
  $near: [ <x>, <y> ],
  $maxDistance: <distance in radians>
}

When specifying a legacy coordinate, you can use the optional$maxDistance specification to limit the $nearresults by distance in radians. $maxDistance limits theresults to those documents that are at most the specified distancefrom the center point.

Behavior

Special Indexes Restriction

You cannot combine the $near operator, which requires aspecial geospatial index, with aquery operator or command that requires another special index. Forexample you cannot combine $near with the $textquery.

Sharded Collections

Starting in MongoDB 4.0, $near queries are supported forsharded collections.

In earlier MongoDB versions, $near queries are not supportedfor sharded collections; instead, for sharded clusters, you must usethe $geoNear aggregation stage or the geoNear command(available in MongoDB 4.0 and earlier).

Sort Operation

$near sorts documents by distance. If you also include asort() for the query, sort()re-orders the matching documents, effectively overriding the sortoperation already performed by $near. When usingsort() with geospatial queries, consider using$geoWithin operator, which does not sort documents, instead of$near.

See also

2d Indexes and Geospatial Near Queries

Examples

Query on GeoJSON Data

Important

If specifying latitude and longitude coordinates, list thelongitude first and then latitude:

• Valid longitude values are between -180 and 180, bothinclusive.
• Valid latitude values are between -90 and 90, bothinclusive.

Consider a collection places that has a 2dsphere index.

The following example returns documents that are at least 1000meters from and at most 5000 meters from the specified GeoJSONpoint, sorted from nearest to farthest:

db.places.find(
   {
     location:
       { $near :
          {
            $geometry: { type: "Point",  coordinates: [ -73.9667, 40.78 ] },
            $minDistance: 1000,
            $maxDistance: 5000
          }
       }
   }
)

Query on Legacy Coordinates

Important

If specifying latitude and longitude coordinates, list thelongitude first and then latitude:

• Valid longitude values are between -180 and 180, bothinclusive.
• Valid latitude values are between -90 and 90, bothinclusive.

Consider a collection legacy2d that has a 2d index.

The following example returns documents that are at most 0.10radians from the specified legacy coordinate pair, sorted from nearestto farthest:

db.legacy2d.find(
   { location : { $near : [ -73.9667, 40.78 ], $maxDistance: 0.10 } }
)