> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $nearSphere (query predicate operator)

## Definition

Specifies a point for which a [geospatial](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-geospatial) query returns the documents from nearest to farthest. MongoDB calculates distances for [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) using spherical geometry.

[`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) *requires* a geospatial index:

- [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-2dsphere-index) index for location data defined as GeoJSON points.

- [2d](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2d.md#std-label-2d-index) index for location data defined as legacy coordinate pairs. To use a `2d` index on [GeoJSON points](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-geojson-point), create the index on the `coordinates` field of the GeoJSON object.

The [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) operator can specify either a [GeoJSON](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-GeoJSON) point or legacy coordinate point.

To specify a [GeoJSON Point](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-geojson-point), use the following syntax:

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

- The *optional* [`$minDistance`](https://www.mongodb.com/docs/manual/reference/operator/query/mindistance.md#mongodb-query-op.-minDistance) limits the results to those documents that are *at least* the specified distance from the center point.

- The *optional* [`$maxDistance`](https://www.mongodb.com/docs/manual/reference/operator/query/maxdistance.md#mongodb-query-op.-maxDistance) is available for either index.

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

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

- The *optional* [`$minDistance`](https://www.mongodb.com/docs/manual/reference/operator/query/mindistance.md#mongodb-query-op.-minDistance) is available only if the query uses the [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-2dsphere-index) index. [`$minDistance`](https://www.mongodb.com/docs/manual/reference/operator/query/mindistance.md#mongodb-query-op.-minDistance) limits the results to those documents that are *at least* the specified distance from the center point.

- The *optional* [`$maxDistance`](https://www.mongodb.com/docs/manual/reference/operator/query/maxdistance.md#mongodb-query-op.-maxDistance) is available for either index.

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

## Behavior

### Special Indexes Restriction

You cannot combine the [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) operator, which requires a special [geospatial index](https://www.mongodb.com/docs/manual/geospatial-queries.md#std-label-index-feature-geospatial), with a query operator or command that requires another special index. For example you cannot combine [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) with the [`$text`](https://www.mongodb.com/docs/manual/reference/operator/query/text.md#mongodb-query-op.-text) query.

### Sort Operation

The [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) operator sorts documents by distance.

- If you use the [`sort()`](https://www.mongodb.com/docs/manual/reference/method/cursor.sort.md#mongodb-method-cursor.sort) method in your query, MongoDB performs a second sort operation, re-ordering the matching documents.  When querying large collections, this can negatively affect query performance.

- If the order of the documents is not important to you, consider using the [`$geoWithin`](https://www.mongodb.com/docs/manual/reference/operator/query/geowithin.md#mongodb-query-op.-geoWithin) operator instead, as it returns unsorted results.

- [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) is a Match Execution operator and is not permitted in aggregation pipelines.

### Validation

Starting in MongoDB 8.0, [`$near`](https://www.mongodb.com/docs/manual/reference/operator/query/near.md#mongodb-query-op.-near), [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere), and [`$geoNear`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/geonear.md#mongodb-pipeline-pipe.-geoNear) validate that the type of the specified [GeoJSON points](https://www.mongodb.com/docs/manual/reference/geojson.md#std-label-geojson-point) is `Point`. Any other input type returns an error.

### Memory Use

Starting in MongoDB 9.0, MongoDB tracks the memory that [`$nearSphere`](https://www.mongodb.com/docs/manual/reference/operator/query/nearsphere.md#mongodb-query-op.-nearSphere) uses to buffer results and to remove duplicate records. If the query exceeds the 100 megabyte memory limit for the stage, MongoDB ends the query and returns an error.

Only queries that match a large number of documents reach the limit. To reduce the memory that the query requires, specify `maxDistance` to restrict the search area. This memory counts toward the per-operation memory limit. To learn more, see [Per-Operation Memory Limit.](https://www.mongodb.com/docs/manual/core/aggregation-pipeline-limits.md#std-label-operation-memory-limit)

## Examples

### Specify Center Point Using GeoJSON

Consider a collection `places` that contains documents with a `location` field and has a [2dsphere](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2dsphere.md#std-label-2dsphere-index) 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:

```javascript
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](https://www.mongodb.com/docs/manual/core/indexes/index-types/geospatial/2d.md#std-label-2d-index) 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:

```javascript
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`](https://www.mongodb.com/docs/manual/reference/operator/query/mindistance.md#mongodb-query-op.-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:

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