Docs Home → MongoDB Manual

$nearSphere

On this page本页内容

Definition定义

$nearSphere

Specifies a point for which a geospatial query returns the documents from nearest to farthest. 指定geospatial查询从最近到最远返回文档的点。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点的位置数据的2dsphere索引。
  • 2d index for location data defined as legacy coordinate pairs. 用于定义为遗留坐标对的位置数据的2d索引。To use a 2d index on GeoJSON points, create the index on the coordinates field of the GeoJSON object.要在GeoJSON点上使用2d索引，请在GeoJSON对象的coordinates字段上创建索引。

The $nearSphere operator can specify either a GeoJSON point or legacy coordinate point.$nearSphere运算符可以指定GeoJSON点或传统坐标点。

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.可选的$minDistance将结果限制为距离中心点至少指定距离的文档。
  • The optional $maxDistance is available for either index.可选的$maxDistance可用于任一索引。

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. 只有当查询使用2dsphere索引时，可选的$minDistance才可用。$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.可选的$maxDistance可用于任一索引。

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

Tip

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. 不能将需要特殊地理空间索引的$nearSphere运算符与需要其他特殊索引的查询运算符或命令组合使用。For example you cannot combine $nearSphere with the $text query.例如，不能将$nearSphere与$text查询组合在一起。

Sharded Collections分片集合

Prior to MongoDB 4.0, $nearSphere queries are not supported for sharded collections. 在MongoDB 4.0之前，分片集合不支持$nearSphere查询。Instead, you can use the $geoNear aggregation stage or the geoNear command.相反，您可以使用$geoNear聚合阶段或geoNear命令。

Sort Operation排序操作

The $nearSphere operator sorts documents by distance.$nearSphere运算符按距离对文档进行排序。

  • If you use the 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.如果在查询中使用sort()方法，MongoDB将执行第二次排序操作，重新排序匹配的文档。查询大型集合时，这可能会对查询性能产生负面影响。
  • If the order of the documents is not important to you, consider using the $geoWithin operator instead, as it returns unsorted results.如果文档的顺序对您来说并不重要，请考虑使用$geoWithin运算符，因为它会返回未排序的结果。
  • $nearSphere is a Match Execution operator and is not permitted in aggregation pipelines.是Match Execution运算符，不允许在聚合管道中使用。

Examples实例

Specify Center Point Using GeoJSON使用GeoJSON指定中心点

Consider a collection places that contains documents with a location field and has a 2dsphere index.考虑一个集合，其中包含带有location字段的文档，并具有2dsphere索引。

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:然后，以下示例按从最近到最远的顺序返回其位置，该位置距离指定点至少1000米，最多5000米：

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，该集合包含location字段中具有旧坐标对的文档，并且具有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. 如果集合具有2dsphere索引，则也可以指定可选的$minDistance规范。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 } }
)