$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.要对2d index on 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提示

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

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).在早期的MongoDB版本中，分片集合不支持$nearSphere查询；相反，对于分片集群，必须使用$geoNear聚合阶段或geoNear命令（在MongoDB4.0和更早版本中可用）。

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. 如果还为查询包含sort()，sort()将对匹配的文档重新排序，从而有效地覆盖$nearSphere已经执行的排序操作。When using sort() with geospatial queries, consider using $geoWithin operator, which does not sort documents, instead of $nearSphere.在对地理空间查询使用sort()时，请考虑使用$geoWithin运算符，而不是使用$nearSphere，因为$geoWithin不会对文档进行排序。

Examples示例

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

Consider a collection places that contains documents with a location field and has a 2dsphere index.考虑一个集合places，其中包含具有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:然后，以下示例返回其location距离指定点至少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 } }
)
←  $near$box →