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

$near

Definition定义

$near

Specifies a point for which a geospatial query returns the documents from nearest to farthest. The $near operator can specify either a GeoJSON point or legacy coordinate point.指定地理空间查询从最近到最远返回文档的点。$near运算符可以指定GeoJSON点或传统坐标点。

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

  • 2dsphere index if specifying a GeoJSON point.如果指定GeoJSON点，则使用2dsphere索引。
  • 2d index if specifying a point using legacy coordinates.如果使用传统坐标指定点，则使用2d索引。

To specify a GeoJSON point, $near operator requires a 2dsphere index and has the following syntax:要指定GeoJSON点，$near运算符需要一个2dsphere索引，语法如下：

{
   <location field>: {
     $near: {
       $geometry: {
          type: "Point" ,
          coordinates: [ <longitude> , <latitude> ]
       },
       $maxDistance: <distance in meters>,
       $minDistance: <distance in meters>
     }
   }
}

Important

If specifying latitude and longitude coordinates, list the longitude first, and then latitude.如果指定纬度和经度坐标，请先列出经度，然后再列出纬度。

  • Valid longitude values are between -180 and 180, both inclusive.有效的经度值介于-180和180之间，包括-180和180。
  • Valid latitude values are between -90 and 90, both inclusive.有效的纬度值介于-90和90之间，包括-90和90。

When specifying a GeoJSON point, you can use the optional $minDistance and $maxDistance specifications to limit the $near results by distance in meters:指定GeoJSON点时，可以使用可选的$minDistance和$maxDistance规范，以米为单位限制$near结果：

  • $minDistance limits the results to those documents that are at least the specified distance from the center point.将结果限制在距离中心点至少指定距离的文档中。
  • $maxDistance limits the results to those documents that are at most the specified distance from the center point.将结果限制在距离中心点最多指定距离的文档中。

To specify a point using legacy coordinates, $near requires a 2d index and has the following syntax:要使用传统坐标指定点，$near需要一个2d索引，语法如下：

{
  $near: [ <x>, <y> ],
  $maxDistance: <distance in radians>
}

When specifying a legacy coordinate, you can use the optional $maxDistance specification to limit the $near results by distance in radians. 指定传统坐标时，可以使用可选的$maxDistance规范，通过弧度距离限制$near结果。$maxDistance limits the results to those documents that are at most the specified distance from the center point.$maxDistance将结果限制在距离中心点最多指定距离的文档中。

Behavior行为

Special Indexes Restriction特殊指标限制

You cannot combine the $near operator, which requires a special geospatial index, with a query operator or command that requires another special index. 您不能将需要特殊地理空间索引的$near运算符与需要另一个特殊索引的查询运算符或命令组合使用。For example you cannot combine $near with the $text query.例如，您不能将$near与$text查询结合使用。

Sort Operation排序操作

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

  • 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运算符，因为它返回未排序的结果。
  • $near is a Match Execution operator and is not permitted in aggregation pipelines.是匹配执行运算符，不允许在聚合管道中使用。

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示例

Query on GeoJSON DataGeoJSON数据查询

Important

If specifying latitude and longitude coordinates, list the longitude first, and then latitude.如果指定纬度和经度坐标，请先列出经度，然后再列出纬度。

  • Valid longitude values are between -180 and 180, both inclusive.有效的经度值介于-180和180之间，包括-180和180。
  • Valid latitude values are between -90 and 90, both inclusive.有效的纬度值介于-90和90之间，包括-90和90。

Consider a collection places that has a 2dsphere index.考虑一个具有2dsphere索引的集合places。

The following example returns documents that are at least 1000 meters from and at most 5000 meters from the specified GeoJSON point, sorted from nearest to farthest:以下示例返回距离指定GeoJSON点至少1000米、最多5000米的文档，从最近到最远排序：

db.places.find(
   {
     location:
       { $near :
          {
            $geometry: { type: "Point",  coordinates: [ -73.9667, 40.78 ] },
            $minDistance: 1000,
            $maxDistance: 5000
          }
       }
   }
)

Query on Legacy Coordinates查询遗留坐标

Important

If specifying latitude and longitude coordinates, list the longitude first, and then latitude.如果指定纬度和经度坐标，请先列出经度，然后再列出纬度。

  • Valid longitude values are between -180 and 180, both inclusive.有效的经度值介于-180和180之间，包括-180和180。
  • Valid latitude values are between -90 and 90, both inclusive.有效的纬度值介于-90和90之间，包括-90和90。

Consider a collection legacy2d that has a 2d index.考虑一个具有2d索引的集合legacy2d。

The following example returns documents that are at most 0.10 radians from the specified legacy coordinate pair, sorted from nearest to farthest:以下示例返回的文档与指定的传统坐标对的距离最多为0.10弧度，从最近到最远排序：

db.legacy2d.find(
   { location : { $near : [ -73.9667, 40.78 ], $maxDistance: 0.10 } }
)