$nearSphere

Definition

  • $nearSphere
  • Specifies a point for which a geospatial query returns thedocuments from nearest to farthest. MongoDB calculates distances for$nearSphere using spherical geometry.

$nearSphererequires a geospatial index:

  • 2dsphere index for location data definedas GeoJSON points
  • 2d index for location data defined as legacycoordinate pairs. To use a 2d index onGeoJSON points, create the index on thecoordinates field of the GeoJSON object.The $nearSphere operator can specify either aGeoJSON point or legacy coordinate point.

To specify a GeoJSON Point, use the followingsyntax:

  1. {
  2.   $nearSphere: {
  3.      $geometry: {
  4.         type : "Point",
  5.         coordinates : [ <longitude>, <latitude> ]
  6.      },
  7.      $minDistance: <distance in meters>,
  8.      $maxDistance: <distance in meters>
  9.   }
  10. }
  • The optional$minDistance limits the results to thosedocuments that are at least the specified distance from thecenter point.

New in version 2.6.

To specify a point using legacy coordinates, use the followingsyntax:

  1. {
  2.   $nearSphere: [ <x>, <y> ],
  3.   $minDistance: <distance in radians>,
  4.   $maxDistance: <distance in radians>
  5. }
  • The optional$minDistance is available only if thequery uses the 2dsphere index.$minDistance limits the results to those documents thatare at least the specified distance from the center point.

New in version 2.6.

If you use longitude and latitude for legacy coordinates, specifythe longitude first, then latitude.

See also

2d Indexes and Geospatial Near Queries

Behavior

Special Indexes Restriction

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

Sharded Collections

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

In earlier MongoDB versions, $nearSphere 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

$nearSphere 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 $nearSphere. When usingsort() with geospatial queries, consider using$geoWithin operator, which does not sort documents, instead of$nearSphere.

Examples

Specify Center Point Using GeoJSON

Consider a collection places that contains documents with alocation field and has a 2dsphere index.

Then, the following example returns whose location is at least1000 meters from and at most 5000 meters from the specifiedpoint, ordered from nearest to farthest:

  1. db.places.find(
  2.    {
  3.      location: {
  4.         $nearSphere: {
  5.            $geometry: {
  6.               type : "Point",
  7.               coordinates : [ -73.9667, 40.78 ]
  8.            },
  9.            $minDistance: 1000,
  10.            $maxDistance: 5000
  11.         }
  12.      }
  13.    }
  14. )

Specify Center Point Using Legacy Coordinates

2d Index

Consider a collection legacyPlaces that contains documents withlegacy coordinates pairs in the location field and has a 2d index.

Then, the following example returns those documents whose locationis at most 0.10 radians from the specified point, ordered fromnearest to farthest:

  1. db.legacyPlaces.find(
  2.    { location : { $nearSphere : [ -73.9667, 40.78 ], $maxDistance: 0.10 } }
  3. )

2dsphere Index

If the collection has a 2dsphere index instead, you can alsospecify the optional $minDistance specification. For example,the following example returns the documents whose location is atleast 0.0004 radians from the specified point, ordered from nearestto farthest:

  1. db.legacyPlaces.find(
  2.    { location : { $nearSphere : [ -73.9667, 40.78 ], $minDistance: 0.0004 } }
  3. )