$nearSphere (Near, Spherical)
Last updated: 2026-10-09
$nearSphere (Near, Spherical)
$nearSphere returns geospatial documents ordered by spherical (great-circle) distance. `{ loc: { $nearSphere: { $geometry: { type: 'Point', coordinates: [lng, lat] }, $maxDistance: 5000 } } }`. Unlike $near, it always computes spherical distance in meters (planar distance is only used by $near on a 2d index). Requires a 2dsphere index.
| Category | Geospatial |
|---|---|
| MongoDB Version | 2.4+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ <location field>: { $nearSphere: { $geometry: <Point>, $maxDistance: <meters> } } }⚙️ Parameters
| position field | The field storing the location. |
|---|---|
| Point geometry | A GeoJSON Point with [longitude, latitude]. |
| maxDistance | Optional; maximum spherical distance in meters. |
Returns：Cursor of matching documents (ascending by spherical distance)
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $nearSphere: stores within 5 km (spherical)
// Coordinates are [longitude, latitude]
db.stores.find({
loc: { $nearSphere: {
$geometry: { type: 'Point', coordinates: [-73.97, 40.75] },
$maxDistance: 5000
} }
})Output：
// Returns stores within 5 km, ordered by spherical distance📌 Notes
- Always spherical distance — right for worldwide proximity queries
- Coordinates are [longitude, latitude]; reversing them points to the wrong place
- Use $near or $nearSphere, never both
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QWhat is the difference between $nearSphere and $near?
A$nearSphere always uses spherical distance in meters; $near uses planar distance on a 2d index.
QWhat is the coordinate order?
AGeoJSON is [longitude, latitude]; reversing them lands far off.
QCan I use $near and $nearSphere together?
ANo, only one of them may appear in a query.
