$nearSphere

On this page本页内容

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.MongoDB使用球形几何体计算$nearSphere的距离。

$nearSphere requires a geospatial index:需要地理空间索引：

  • 2dsphere index for location data defined as GeoJSON points定义为GeoJSON点的位置数据索引
  • 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:要指定GeoJSON点，请使用以下语法：

{
  $nearSphere: {
     $geometry: {
        type : "Point",
        coordinates : [ <longitude>, <latitude> ]
     },
     $minDistance: <distance in meters>,
     $maxDistance: <distance in meters>
  }
}
  • The optional $minDistance limits the results to those documents that are at least the specified distance from the center point.
  • 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.
  • The optional $maxDistance is available for either index.

If you use longitude and latitude for legacy coordinates, specify the longitude first, then latitude.如果对传统坐标使用经度和纬度，请先指定经度，然后指定纬度。

See also参阅

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分片集合

Starting in MongoDB 4.0, $nearSphere queries are supported for sharded collections.从MongoDB 4.0开始，分片集合支持$nearSphere查询。

In earlier MongoDB versions, $nearSphere queries are not supported for sharded collections; instead, for sharded clusters, you must use the $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 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使用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.考虑一个集合legacyPlaces，其中包含位置字段中具有旧坐标对的文档，并且具有2d索引。

Then, the following example returns those documents whose location is at most 0.10 radians from the specified point, ordered from nearest to farthest:然后，以下示例返回其location距离指定点最多0.10弧度的文档，按从最近到最远的顺序排列：

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:例如，以下示例返回其location距离指定点至少0.0004弧度的文档，按从最近到最远的顺序排列：

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