$geoNear (aggregation)¶

Definition定义¶

$geoNear¶

Outputs documents in order of nearest to farthest from a specified point.按距离指定点最近到最远的顺序输出文档。

Note

Starting in version 4.2, MongoDB removes the limit and num options for the $geoNear stage as well as the default limit of 100 documents. 从4.2版开始，MongoDB删除了$geoNear阶段的limit和num选项，以及100个文档的默认限制。To limit the results of $geoNear, use the $geoNear stage with the $limit stage.要限制$geoNear的结果，请将$geoNear阶段与$limit阶段一起使用。

The $geoNear stage has the following prototype form:$geoNear阶段的原型形式如下：

{ $geoNear: { <geoNear options> } }

The $geoNear operator accepts a document that contains the following $geoNear options. $geoNear运算符接受包含以下$geoNear选项的文档。Specify all distances in the same units as those of the processed documents’ coordinate system:以与已处理文档坐标系相同的单位指定所有距离：

Field字段	Type类型	Description描述
near	GeoJSON point or legacy coordinate pairGeoJSON点或传统坐标对	The point for which to find the closest documents.查找最近文档的点。 If using a 2dsphere index, you can specify the point as either a GeoJSON point or legacy coordinate pair.如果使用2dsphere索引，可以将该点指定为GeoJSON点或传统坐标对。 If using a 2d index, specify the point as a legacy coordinate pair.如果使用2d索引，请将该点指定为传统坐标对。
distanceField	string	The output field that contains the calculated distance. 包含计算距离的输出字段。To specify a field within an embedded document, use dot notation.要指定嵌入文档中的字段，请使用点符号。
spherical	boolean	Optional.可选。Determines how MongoDB calculates the distance between two points:确定MongoDB如何计算两点之间的距离： When true, MongoDB uses $nearSphere semantics and calculates distances using spherical geometry.如果为true，MongoDB将使用$nearSphere语义，并使用球形几何体计算距离。 When false, MongoDB uses $near semantics: spherical geometry for 2dsphere indexes and planar geometry for 2d indexes.如果为false，MongoDB将使用$near语义：球形几何体用于2dsphere索引，平面几何体用于2d索引。 Default: false.默认值：false。
maxDistance	number	Optional.可选。The maximum distance from the center point that the documents can be. 距文档可以移动的中心点的最大距离。MongoDB limits the results to those documents that fall within the specified distance from the center point.MongoDB将结果限制为与中心点之间的指定距离内的文档。 Specify the distance in meters if the specified point is GeoJSON and in radians if the specified point is legacy coordinate pairs.如果指定点是GeoJSON，则以米为单位指定距离；如果指定点是传统坐标对，则以弧度为单位指定距离。
query	document	Optional.可选。Limits the results to the documents that match the query. 将结果限制为与查询匹配的文档。The query syntax is the usual MongoDB read operation query syntax.查询语法是常见的MongoDB读取操作查询语法。 You cannot specify a $near predicate in the query field of the $geoNear stage.不能在$geoNear阶段的查询字段中指定$near谓词。
distanceMultiplier	number	Optional.可选。The factor to multiply all distances returned by the query. 将查询返回的所有距离相乘的因子。For example, use the distanceMultiplier to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth.例如，使用distanceMultiplier将球形查询返回的弧度乘以地球半径，转换为千米。
includeLocs	string	Optional.可选。This specifies the output field that identifies the location used to calculate the distance. 这将指定用于标识用于计算距离的位置的输出字段。This option is useful when a location field contains multiple locations. 当位置字段包含多个位置时，此选项很有用。To specify a field within an embedded document, use dot notation.要指定嵌入文档中的字段，请使用点符号。
uniqueDocs	boolean	Optional.可选。If this value is true, the query returns a matching document once, even if more than one of the document’s location fields match the query.如果该值为true，则查询会返回一次匹配的文档，即使文档的多个位置字段与查询匹配。 Deprecated since version 2.6:自2.6版以来已弃用：Geospatial queries no longer return duplicate results. 地理空间查询不再返回重复的结果。The $uniqueDocs operator has no impact on results.$uniqueDocs运算符对结果没有影响。
minDistance	number	Optional.可选。The minimum distance from the center point that the documents can be. 距离文档可以到达的中心点的最小距离。MongoDB limits the results to those documents that fall outside the specified distance from the center point.MongoDB将结果限制在距离中心点指定距离之外的文档。 Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs.对于GeoJSON数据，以米为单位指定距离；对于传统坐标对，以弧度为单位指定距离。 New in version 3.2.版本3.2中的新功能。
key		Optional.可选。Specify the geospatial indexed field to use when calculating the distance.指定计算距离时要使用的地理空间索引字段。 If your collection has multiple 2d and/or multiple 2dsphere indexes, you must use the key option to specify the indexed field path to use. 如果集合有多个2d和/或多个2dsphere索引，则必须使用key选项指定要使用的索引字段路径。Specify Which Geospatial Index to Use provides a full example.指定要使用的地理空间索引提供了完整的示例。 If there is more than one 2d index or more than one 2dsphere index and you do not specify a key, MongoDB will return an error.如果存在多个2d索引或多个2dsphere索引，并且未指定key，MongoDB将返回错误。 If you do not specify the key, and you have at most only one 2d index and/or only one 2dsphere index, MongoDB looks first for a 2d index to use. 如果不指定键，并且最多只有一个2d索引和/或一个2dsphere索引，MongoDB会首先查找要使用的2d索引。If a 2d index does not exists, then MongoDB looks for a 2dsphere index to use.如果2d索引不存在，则MongoDB会查找要使用的2dsphere索引。 New in version 4.0.版本4.0中的新功能。

Behavior行为¶

When using $geoNear, consider that:当使用$geoNear时，请考虑：

• You can only use $geoNear as the first stage of a pipeline.您只能将$geoNear用作管道的第一阶段。
• You must include the distanceField option. 必须包括distanceField字段选项。The distanceField option specifies the field that will contain the calculated distance.distanceField选项指定将包含计算距离的字段。
• $geoNear requires a geospatial index.需要地理空间索引。

  If you have more than one geospatial index on the collection, use the keys parameter to specify which field to use in the calculation. 如果集合上有多个地理空间索引，请使用keys参数指定要在计算中使用的字段。If you have only one geospatial index, $geoNear implicitly uses the indexed field for the calculation.如果只有一个地理空间索引，$geoNear会隐式使用索引字段进行计算。

• You cannot specify a $near predicate in the query field of the $geoNear stage.不能在$geoNear阶段的query字段中指定$near谓词。
• Views do not support geoNear operations (i.e. $geoNear pipeline stage).视图不支持geoNear操作（即$geoNear管道阶段）。
• Starting in version 4.2, $geoNear no longer has a default limit of 100 documents.从4.2版开始，$geoNear不再有100个文档的默认限制。

Example示例¶

Consider a collection places that has a 2dsphere index. 考虑具有2dsphere索引的集合places。The following aggregation uses $geoNear to find documents with a location at most 2 meters from the center [ -73.99279 , 40.719296 ] and category equal to Parks.下面的聚合使用$geoNear查找距离中心[ -73.99279 , 40.719296 ]最多2米且category等于Parks的文档。

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        distanceField: "dist.calculated",
        maxDistance: 2,
        query: { category: "Parks" },
        includeLocs: "dist.location",
        spherical: true
     }
   }
])

The aggregation returns the following:聚合返回以下内容：

{
   "_id" : 8,
   "name" : "Sara D. Roosevelt Park",
   "category" : "Parks",
   "location" : {
      "type" : "Point",
      "coordinates" : [ -73.9928, 40.7193 ]
   },
   "dist" : {
      "calculated" : 0.9539931676365992,
      "location" : {
         "type" : "Point",
         "coordinates" : [ -73.9928, 40.7193 ]
      }
   }
}

The matching document contains two new fields:匹配的文档包含两个新字段：

• dist.calculated field that contains the calculated distance, and包含计算距离的dist.calculated字段，以及
• dist.location field that contains the location used in the calculation.包含计算中使用的位置的dist.location字段。

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        distanceField: "dist.calculated",
        minDistance: 2,
        query: { category: "Parks" },
        includeLocs: "dist.location",
        spherical: true
     }
   }
])

{
   "_id" : 3,
   "name" : "Polo Grounds",
   "location": {
      "type" : "Point",
      "coordinates" : [ -73.9375, 40.8303 ]
   },
   "legacy" : [ -73.9375, 40.8303 ],
   "category" : "Stadiums"
}

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.98142 , 40.71782 ] },
        key: "location",
        distanceField: "dist.calculated",
        query: { "category": "Parks" }
     }
   },
   { $limit: 5 }
])

{
   "_id" : 8,
   "name" : "Sara D. Roosevelt Park",
   "location" : {
      "type" : "Point",
      "coordinates" : [
         -73.9928,
         40.7193
      ]
   },
   "category" : "Parks",
   "dist" : {
      "calculated" : 974.175764916902
   }
}
{
   "_id" : 1,
   "name" : "Central Park",
   "location" : {
      "type" : "Point",
      "coordinates" : [
         -73.97,
         40.77
      ]
   },
   "legacy" : [
      -73.97,
      40.77
   ],
   "category" : "Parks",
   "dist" : {
      "calculated" : 5887.92792958097
   }
}