$nearSphere¶

On this page

Definition
Behavior
Examples

Definition¶

$nearSphere¶

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

$nearSphere requires a geospatial index:

2dsphere index for location data defined as GeoJSON points
2d index for location data defined as legacy coordinate pairs. To use a 2d index on GeoJSON points, create the index on the coordinates field of the GeoJSON object.

The $nearSphere operator can specify either a GeoJSON point or legacy coordinate point.

To specify a GeoJSON Point, use the following syntax:

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

The optional $minDistance is available only if the query uses the 2dsphere index. $minDistance limits the results to those documents that are at least the specified distance from the center point.

2.6 新版功能.
The optional $maxDistance is available for either index.

To specify a point using legacy coordinates, use the following syntax:

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

The optional $minDistance is available only if the query uses the 2dsphere index. $minDistance limits the results to those documents that are at least the specified distance from the center point.

2.6 新版功能.
The optional $maxDistance is available for either index.

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

参见

2d Indexes and Geospatial Near Queries

Behavior¶

Special Indexes Restriction¶

You cannot combine the $nearSphere operator, which requires a special geospatial index, with a query operator or command that requires another special index. For example you cannot combine $nearSphere with the $text query.

Sharded Collections Restrictions¶

For sharded collections, queries using $nearSphere are not supported. You can instead use either the geoNear command or the $geoNear aggregation stage.

Sort Operation¶

$nearSphere sorts documents by distance. If you also include a sort() for the query, sort() re-orders the matching documents, effectively overriding the sort operation already performed by $nearSphere. When using sort() 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 a location field and has a 2dsphere index.

Then, the following example returns whose location is at least 1000 meters from and at most 5000 meters from the specified point, ordered from nearest to farthest:

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

Specify Center Point Using Legacy Coordinates¶

`2d` Index¶

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

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

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

`2dsphere` Index¶

If the collection has a 2dsphere index instead, you can also specify the optional $minDistance specification. For example, the following example returns the documents whose location is at least 0.0004 radians from the specified point, ordered from nearest to farthest:

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

← $near $geometry →