$geoNear (agregação)

Definição

$geoNear

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

Observação

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

O estágio $geoNear tem a seguinte forma 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. Especifique 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 que os documentos podem estar. O MongoDB limita os resultados aos documentos que se enquadram dentro da distância especificada a partir do ponto central. A partir da versão 7.2, você pode especificar uma expressão constante válida que se resolve em um número. 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. A partir da versão 7.2, você pode especificar uma expressão constante válida que se resolve em um número. 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	booleano	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

Se utilizar o $geoNear, considere que:

• Você só pode utilizar $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 requer um índice geoespacial.

  Se você tiver mais de um índice geoespacial na coleção, use o parâmetro keys para especificar qual campo usar no cálculo. Se você tiver somente um índice geoespacial, $geoNear implicitamente usará o campo indexado no cálculo.

• Você não pode especificar um predicado $near no campo query do estágio $geoNear.

• $geoNear não tem mais um limite-padrão de 100 documentos.

• A partir do MongoDB 5.1, o parâmetro near é compatível com 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.

• Começando no MongoDB 8.0, $near, $nearSphere e $geoNear, valide que o tipo dos pontos GeoJSON especificados é Point. Qualquer outro tipo de entrada retorna um erro.

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

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

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

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

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

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

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

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