Database Manual / Reference / Query Language / Query Predicates / Geospatial

$nearSphere

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点的位置数据的2dsphere索引。
  • 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索引。要在GeoJSON点上使用2d索引，请在GeoJSON对象的坐标字段上创建索引。

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

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

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.您不能将需要特殊地理空间索引的$nearSphere运算符与需要另一个特殊索引的查询运算符或命令组合使用。例如，您不能将$nearSphere与$text查询结合使用。

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.$nearSphere是一个匹配执行运算符，不允许在聚合管道中使用。

Validation验证

Starting in MongoDB 8.0, $near, $nearSphere, and $geoNear validate that the type of the specified GeoJSON points is Point. Any other input type returns an error.从MongoDB 8.0开始，$near、$nearSphere和$geoNear验证指定的GeoJSON点的类型是否为Point。任何其他输入类型都会返回错误。

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索引的集合places。

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. 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:如果集合具有2dsphere索引，则还可以指定可选的$minDistance规范。例如，以下示例返回location距离指定点至少0.0004弧度的文档，按从最近到最远的顺序排列：

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