Docs 菜单
Docs 主页
/
MongoDB Manual
/
聚合操作
/
参考
/
阶段(Stages)

$geoNear（聚合）

在此页面上

  • 定义
  • 行为
  • 示例

定义

$geoNear

按距离指定点最近到最远的顺序输出文档。

注意

MongoDB 删除了 $geoNear 阶段的 limit 和 num 选项以及 100 个文档的默认限制。要限制 $geoNear 的结果，可以使用 $geoNear 阶段和 $limit 阶段。

$geoNear 阶段具有以下原型形式：

{ $geoNear: { <geoNear options> } }

$geoNear 运算符接受包含以下 $geoNear 选项的文档。使用与已处理文档坐标系相同的单位指定所有距离：

字段
类型
说明
distanceField
字符串
包含计算出的距离的输出字段。要在嵌入式文档中指定字段，请使用点符号。
distanceMultiplier
数字
可选。用于与查询返回的所有距离相乘的系数。例如，使用 distanceMultiplier 乘以地球半径，将球形查询返回的弧度转换为公里。
includeLocs
字符串
可选。这指定了一个输出字段，用于标识用来计算距离的位置。该选项适合位置字段包含多个位置的情况。要在嵌入式文档中指定字段，请使用点符号。
key

可选。指定计算距离时使用的地理空间索引字段。

如果您的集合有多个 2d 和/或多个 2dsphere 索引，则必须使用 key 选项来指定要使用的带索引字段路径。“指定要使用的地理空间索引”中提供了一个完整示例。

如果存在多个 2d 索引或多个 2dsphere 索引，并且您未指定 key，MongoDB 将返回错误。

如果未指定 key，并且您最多只有一个 2d 索引和/或只有一个 2dsphere 索引，MongoDB 首先会查找要使用的 2d 索引。如果 2d 索引不存在，则 MongoDB 会查找要使用的 2dsphere 索引。

maxDistance
数字

可选。 文档可与中心点相距的最大距离。 MongoDB 将结果限制为与中心点相距指定距离内的文档。 从版本 7.2 开始，您可以指定解析为数字的有效常量表达式。

如果指定点为 GeoJSON，则以米为单位指定距离；如果指定点是传统坐标对，则以弧度为单位指定距离。

minDistance
数字

可选。 文档与中心点的最小距离。 MongoDB 将结果限制为与中心点相距指定距离之外的文档。 从版本 7.2 开始，您可以指定解析为数字的有效常量表达式。

对于 GeoJSON 数据，以米为单位指定距离；对于传统坐标对，以弧度为单位指定距离。

near
GeoJSON 点或传统坐标对

查找最新文档的点。

如果使用 2dsphere 索引，则可以将该点指定为 GeoJSON 点或传统坐标对。

如果使用 2d 索引，请将该点指定为传统坐标对。

query
文档

可选。将结果限制为与查询匹配的文档。查询语法是通常的 MongoDB 读取操作查询语法。

不能在 $geoNear 阶段的 query 字段中指定 $near 谓词。

spherical
布尔

可选。确定 MongoDB 如何计算两点之间的距离：

  • 当 true 时，MongoDB 使用 $nearSphere 语义，并使用球面几何计算距离。

  • 当 false 时，MongoDB 使用 $near 语义：2dsphere 索引用于球面，2d 索引用于平面。

默认值：false。

行为

距离计算

$geoNear 根据输入文档周边的最近点计算距离。

示例，如果输入文档是一个形状，$geoNear 则会标识形状周长上距离指定点最近的点，并输出指定点与形状最近点之间的距离。

Considerations

在使用 $geoNear 时，请考虑：

  • 只能使用 $geoNear 作为管道的第一阶段。

  • 必须包含 distanceField 选项。distanceField 选项指定包含计算出的距离的字段。

  • $geoNear 需要地理空间索引。

    如果集合上有多个地理空间索引，请使用 keys 参数指定要在计算中使用的字段。如果你只有一个地理空间索引，$geoNear 会隐式使用索引字段进行计算。

示例

使用以下文档创建集合 places：

db.places.insertMany( [
   {
      name: "Central Park",
      location: { type: "Point", coordinates: [ -73.97, 40.77 ] },
      category: "Parks"
   },
   {
      name: "Sara D. Roosevelt Park",
      location: { type: "Point", coordinates: [ -73.9928, 40.7193 ] },
      category: "Parks"
   },
   {
      name: "Polo Grounds",
      location: { type: "Point", coordinates: [ -73.9375, 40.8303 ] },
      category: "Stadiums"
   }
] )

下面的操作将在 location 字段上创建一个 2dsphere 索引：

db.places.createIndex( { location: "2dsphere" } )

最大距离

注意

MongoDB 移除了 $geoNear 阶段的 limit 和 num 选项以及 100 个文档的默认限制。要限制 $geoNear 的结果，可以使用 $geoNear 阶段和 $limit 阶段。

上面的 places 集合有一个 2dsphere 索引。以下聚合使用 $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
     }
   }
])

该聚合返回以下内容：

{
   "_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 ]
      }
   }
}

匹配文档包含两个新字段：

  • dist.calculated 字段，其包含计算出的距离，以及

  • dist.location 字段，包含计算中使用的位置。

最小距离

注意

MongoDB 移除了 $geoNear 阶段的 limit 和 num 选项以及 100 个文档的默认限制。要限制 $geoNear 的结果，可以使用 $geoNear 阶段和 $limit 阶段。

以下示例使用选项 minDistance 来指定文档可与中心点相距的最小距离。以下聚合查找距离中心 [ -73.99279 , 40.719296 ] 至少 2 米且 category 等于 Parks 的文档。

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
     }
   }
])

带有 选项的 $geoNearlet

在本例中：

  • let 选项用于将 [-73.99279,40.719296] 数组值设置为变量 $pt。

  • $pt 在$geoNear阶段指定为near参数的let选项。

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

该聚合返回包含以下内容的所有文档：

  • 距离 let 变量中定义的点最多 2 米的位置

  • category 等于 Parks。

{
   _id: ObjectId("61715cf9b0c1d171bb498fd7"),
   name: 'Sara D. Roosevelt Park',
   location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
   category: 'Parks',
   distance: 1.4957325341976439e-7,
   dist: { location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] } }
},
{
   _id: ObjectId("61715cf9b0c1d171bb498fd6"),
   name: 'Central Park',
   location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },
   category: 'Parks',
   distance: 0.0009348548688841822,
   dist: { location: { type: 'Point', coordinates: [ -73.97, 40.77 ] } }
}

带有绑定 选项的 $geoNearlet

let 选项可以绑定用于 $geoNear 查询的变量。

在此示例中，$lookup 使用：

  • let 来定义 $pt。

  • pipeline 中的 $geoNear。

  • $pt 在 $geoNear 管道阶段定义 near。

db.places.aggregate( [
   {
      $lookup: {
         from: "places",
         let: { pt: "$location" },
         pipeline: [
            {
               $geoNear: {
                  near: "$$pt",
                  distanceField: "distance"
               }
            }
         ],
         as: "joinedField"
      }
   },
   {
      $match: { name: "Sara D. Roosevelt Park" }
   }
] );

该聚合返回一个包含以下内容的文档：

  • “Sara D. Roosevelt Park”文档作为主要文档。

  • 使用 $pt 变量将地点集合中的每个文档作为子文档来计算距离。

{
   _id: ObjectId("61715cf9b0c1d171bb498fd7"),
      name: 'Sara D. Roosevelt Park',
      location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
      category: 'Parks',
      joinedField: [
         {
         _id: ObjectId("61715cf9b0c1d171bb498fd7"),
         name: 'Sara D. Roosevelt Park',
         location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },
         category: 'Parks',
         distance: 0
         },
         {
         _id: ObjectId("61715cf9b0c1d171bb498fd6"),
         name: 'Central Park',
         location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },
         category: 'Parks',
         distance: 5962.448255234964
         },
         {
         _id: ObjectId("61715cfab0c1d171bb498fd8"),
         name: 'Polo Grounds',
         location: { type: 'Point', coordinates: [ -73.9375, 40.8303 ] },
         category: 'Stadiums',
         distance: 13206.535424939102
         }
      ]
}

指定要使用的地理空间索引

考虑 places 集合，它在 location 字段上有 2dsphere 索引，在 legacy 字段上有 2d 索引。

places 集合中的文档类似于以下内容：

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

以下示例使用了 key 选项，具体指定聚合应使用 location 字段值来执行 $geoNear 操作，而不是使用 legacy 字段值。该管道还使用了 $limit，最多返回 5 个文档。

注意

MongoDB 移除了 $geoNear 阶段的 limit 和 num 选项以及 100 个文档的默认限制。要限制 $geoNear 的结果，可以使用 $geoNear 阶段和 $limit 阶段。

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
   }
}

后退

$fill

来年

$graphLookup

在此页面上