Menu Docs

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

$perto

Nesta página

  • Definição
  • Comportamento
  • Exemplos

Definição

$near

Especifica um ponto para o qual uma query geoespacial retorna os documentos do mais próximo para o mais distante. O operador $near pode especificar um ponto GeoJSON ou um ponto de coordenadas antigo.

$near requer um índice geoespacial:

  • índice 2dsphere se especificar um ponto GeoJSON ,

  • Índice 2d se especificar um ponto utilizando coordenadas legadas.

Para especificar um ponto GeoJSON , o operador $near exige um índice 2dsphere e tem a seguinte sintaxe:

{
   <location field>: {
     $near: {
       $geometry: {
          type: "Point" ,
          coordinates: [ <longitude> , <latitude> ]
       },
       $maxDistance: <distance in meters>,
       $minDistance: <distance in meters>
     }
   }
}

Importante

Se especificar coordenadas de latitude e longitude, liste a longitude primeiro e então a latitude.

  • Os valores de longitude válidos estão entre -180 e 180, ambos inclusos.

  • Os valores de latitude válidos estão entre -90 e 90, ambos inclusos.

Ao especificar um ponto GeoJSON , você pode utilizar as especificações opcionais $minDistance e $maxDistance para limitar os resultados $near por distância em metros:

  • $minDistance limita os resultados aos documentos que estão pelo menos à distância especificada do ponto central.

  • $maxDistance limita os resultados aos documentos que estão, no máximo, à distância especificada do ponto central.

Para especificar um ponto utilizando coordenadas legadas, $near exige um índice 2d e tem a seguinte sintaxe:

{
  $near: [ <x>, <y> ],
  $maxDistance: <distance in radians>
}

Ao especificar uma coordenada legada, você pode utilizar a especificação opcional $maxDistance para limitar os resultados $near por distância em radianos. $maxDistance limita os resultados aos documentos que estão , no máximo, à distância especificada do ponto central.

Comportamento

Restrição de índices especiais

Você não pode combinar o operador $near , que exige um índice geoespacial especial, com um operador de query ou comando que exige outro índice especial. Por exemplo, você não pode combinar $near com a query $text .

Coleções partilhadas

A partir do MongoDB 4. As queries 0, $near são suportadas para coleções fragmentadas.

Nas versões anteriores do MongoDB, as queries do $near não são suportadas para coleções fragmentadas; em vez disso, para clusters fragmentados, você deve usar o estágio de agregação $geoNear ou o comando geoNear (disponível no MongoDB 4.0 e anteriores).

Operação de classificação

O operador $near classifica documentos por distância.

  • Se você utilizar o método sort() em sua query, o MongoDB executará uma segunda operação de classificação, reordenando os documentos correspondentes. Ao queryr grandes coleções, isso pode afetar negativamente o desempenho da query.

  • Se a ordem dos documentos não for importante para você, considere usar o operador $geoWithin, pois ele retorna resultados não classificados.

  • $near é um operador Match Execution e não é permitido em pipelines de agregação.

Exemplos

Query sobre dados GeoJSON

Importante

Se especificar coordenadas de latitude e longitude, liste a longitude primeiro e então a latitude.

  • Os valores de longitude válidos estão entre -180 e 180, ambos inclusos.

  • Os valores de latitude válidos estão entre -90 e 90, ambos inclusos.

Considere uma collection places que tenha um índice 2dsphere.

O exemplo a seguir retorna documentos que estão a pelo menos 1000 metros e no máximo a 5000 metros do ponto GeoJSON especificado, classificados do mais próximo para o mais distante:

db.places.find(
   {
     location:
       { $near :
          {
            $geometry: { type: "Point",  coordinates: [ -73.9667, 40.78 ] },
            $minDistance: 1000,
            $maxDistance: 5000
          }
       }
   }
)

Query sobre coordenadas legadas

Importante

Se especificar coordenadas de latitude e longitude, liste a longitude primeiro e então a latitude.

  • Os valores de longitude válidos estão entre -180 e 180, ambos inclusos.

  • Os valores de latitude válidos estão entre -90 e 90, ambos inclusos.

Considere uma collection legacy2d que tenha um índice 2d.

O exemplo a seguir retorna documentos que estão a, no máximo, 0.10 radianos do par de coordenadas legado especificado, ordenados do mais próximo ao mais distante:

db.legacy2d.find(
   { location : { $near : [ -73.9667, 40.78 ], $maxDistance: 0.10 } }
)
← $geoWithin
$nearSphere →

Nesta página