$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 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. Novo na versão 3.2.
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.

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

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