Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

$geoNear (agregação)

Nesta página

Definição

Comportamento
Exemplos

Definição

$geoNear

Produz documentos na ordem do mais próximo para o mais distante de um ponto especificado.

Observação

A partir da versão 4.2, o MongoDB remove as opções limit e num do estágio $geoNear , bem como o limite padrão de documentos 100 . Para limitar os resultados de $geoNear, use o estágio $geoNear com o estágio $limit .

O estágio $geoNear tem o seguinte formato de protótipo:

{ $geoNear: { <geoNear options> } }

O operador do $geoNear aceita um documento que contém as seguintes opções do $geoNear . Especifique todas as distâncias nas mesmas unidades que as do sistema de coordenadas dos documentos processados:

Campo	Tipo	Descrição
`distanceField`	string	O campo de saída que contém a distância calculada. Para especificar um campo em um documento incorporado, use a notação de ponto.
`distanceMultiplier`	número	Opcional. O fator para multiplicar todas as distâncias retornadas pela consulta. Por exemplo, utilize o `distanceMultiplier` para converter radianos, como retornado por uma consulta esférica, para quilômetros multiplicando pelo raio da Terra.
`includeLocs`	string	Opcional. Isto especifica o campo de saída que identifica o local utilizado para calcular a distância. Esta opção é útil quando um campo de localização contém múltiplos locais. Para especificar um campo dentro de um documento incorporado, use notação de ponto.
`key`		Opcional. Especifique o campo indexado geoespacial para utilizar ao calcular a distância. Se a sua coleção tiver múltiplos índices `2d` e/ou múltiplos índices `2dsphere` , você deve utilizar a opção `key` para especificar o caminho do campo indexado para utilizar. Especificar qual índice geoespacial usar fornece um exemplo completo. Se houver mais de um índice `2d` ou mais de um índice `2dsphere` e você não especificar um `key`, MongoDB retornará um erro. Se você não especificar `key` e tiver no máximo apenas um índice `2d` e/ou apenas um índice `2dsphere`, o MongoDB procurará primeiro um índice `2d` para usar. Se um índice `2d` não existir, o MongoDB procurará um índice `2dsphere` para usar.
`maxDistance`	número	Opcional. A distância máxima do ponto central na qual os documentos podem estar. O MongoDB limita os resultados aos documentos que se enquadram dentro da distância especificada a partir do ponto central. Especifique a distância em metros se o ponto especificado for GeoJSON e em radianos se o ponto especificado for pares de coordenadas legadas.
`minDistance`	número	Opcional. A distância mínima do ponto central na qual os documentos podem estar. O MongoDB limita os resultados aos documentos que estão fora da distância especificada do ponto central. Especifique a distância em metros para dados GeoJSON e em radianos para pares de coordenadas legadas.
`near`	Ponto GeoJSON ou par de coordenadas legado	O ponto para o qual encontrar os documentos mais próximos. Se estiver usando um índice 2dsphere, você poderá especificar o ponto como um ponto GeoJSON ou um par de coordenadas herdadas. Se utilizar um índice 2d, especifique o ponto como um par de coordenadas legado.
`query`	documento	Opcional. Limita os resultados aos documentos que correspondem à consulta. A sintaxe de consulta é a sintaxe habitual de consulta de operação de leitura MongoDB. Você não pode especificar um predicado `$near` no campo `query` do estágio `$geoNear` .
`spherical`	boleano	Opcional. Determina como MongoDB calcula a distância entre dois pontos: Quando `true`, MongoDB utiliza semântica do `$nearSphere` e calcula distâncias utilizando geometria esférica. Quando `false`, MongoDB utiliza semântica `$near`: geometria esférica para índices 2dsphere e geometria planar para índices 2d. Padrão: false.

Comportamento

Ao usar $geoNear, considere que:

Você só pode usar $geoNear como o primeiro estágio de um pipeline.
Você deve incluir a opção distanceField. A opção distanceField especifica o campo que conterá a distância calculada.
$geoNear exige um índice geoespacial.
Se você tiver mais de um índice geoespacial na coleção, utilize o parâmetro keys para especificar qual campo utilizar no cálculo. Se você tiver somente um índice geoespacial, o $geoNear implicitamente utilizará o campo indexado para o cálculo.

Você não pode especificar um predicado $near no campo query do estágio $geoNear .
A partir da versão 4.2, $geoNear não tem mais um limite-padrão de 100 documentos.
A partir do MongoDB 5.1, o parâmetro near suporta a opção let e opção bound let.
A partir do MongoDB 5.3, você pode usar o operador de pipeline $geoNear em qualquer campo em uma coleção de séries temporais.
A partir do MongoDB 6.0, você pode criar índices parciais e de 2dsphere em qualquer campo de uma coleção de séries temporais.

Exemplos

Crie uma collection places com os seguintes documentos:

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

A seguinte operação cria um índice 2dsphere no campo location:

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

Distância máxima

Observação

A coleção places acima tem um índice 2dsphere . A agregação a seguir usa $geoNear para encontrar documentos com uma localização de no máximo 2 metros do centro [ -73.99279 , 40.719296 ] e category igual a 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
     }
   }
])

A agregação retorna o seguinte:

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

O documento correspondente contém dois novos campos:

dist.calculated campo que contém a distância calculada e
dist.location que contém o local utilizado no cálculo.

Distância mínima

Observação

O exemplo seguinte utiliza a opção minDistance para especificar a distância mínima do ponto central que os documentos podem ser. A seguinte aggregation encontra todos os documentos com um local a pelo menos 2 metros do centro [ -73.99279 , 40.719296 ] e category igual a 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
     }
   }
])

$geoNear com a opção `let`

Neste exemplo:

A opção let é utilizada para definir um valor de array de [-73.99279,40.719296] para a variável $pt.
$pt é especificado como uma opção let para o parâmetro near no estágio $geoNear .

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

A agregação retorna todos os documentos com:

Um local a no máximo 2 metros do ponto definido na variável let
Um category igual a 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 ] } }
}

$geoNear com opção bound `let`

A opção let pode vincular uma variável que pode ser utilizada em uma query $geoNear.

Neste exemplo, o $lookup utiliza:

let para definir $pt.
$geoNear no pipeline.
$pt para definir near no estágio de pipeline $geoNear .

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

A agregação retorna um documento com:

O documento "Sara D. Roosevelt Park" como o documento principal.
Cada documento na coleção de locais como subDocumentos usando a variável $pt para calcular a distância.

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

Especifique qual índice geoespacial usar

Considere uma coleção places que tenha um índice 2dsphere no campo location e um índice 2d no campo legacy.

Um documento na collection places se assemelha a:

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

O exemplo a seguir usa a opção key para especificar que a agregação deve usar os valores de campo location para a operação $geoNear e não os valores de campo legacy . O pipeline também usa $limit para retornar no máximo 5 documentos.

Observação

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

A agregação retorna o seguinte:

{
   "_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 (agregação)

$graphLookup (agregação) →

$geoNear (agregação).css-134mg1q{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.css-6vrlzm{border-radius:0!important;display:initial!important;margin:initial!important;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Definição

Observação

Comportamento

Exemplos

Distância máxima

Observação

Distância mínima

Observação

$geoNear com a opção let

$geoNear com opção bound let

Especifique qual índice geoespacial usar

Observação

$geoNear (agregação)

$geoNear com a opção `let`

$geoNear com opção bound `let`