- Reference >
- Operators >
- Query and Projection Operators >
- Geospatial Query Operators >
- $nearSphere
$nearSphere¶
- $nearSphere¶
Specifies a point for which a geospatial query returns the documents from nearest to farthest. MongoDB calculates distances for $nearSphere using spherical geometry.
The $nearSphere operator requires a geospatial index and can use either 2dsphere index or 2d index for location data defined as GeoJSON points or 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.
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 up to 100 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 } }
)