$perto

Nesta página

Definição

Comportamento
Exemplos

Definição

$near

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

$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.

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.

Validação

A partir do MongoDB 8.0, $near, $nearSphere e $geoNear validam se o tipo dos pontos GeoJSON especificado é Point. Qualquer outro tipo de entrada retorna um erro.

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

Voltar

$geoWithin

$nearSphere