/ /

Predicados de query

Geoespacial

Página inicial do Docs

Desenvolvimento

Linguagem de query

Predicados de query

Geoespacial

$nearSphere (operador de predicado da query)

Definição

$nearSphere

Especifica um ponto para o qual uma query geoespacial retorna os documentos do mais próximo para o mais distante. O MongoDB calcula distâncias para $nearSphere utilizando geometria esférica.

$nearSphere requer um índice geoespacial:

Índice 2dsphere para dados de localização definidos como pontos GeoJSON.
Índice 2d para dados de localização definidos como pares de coordenadas legados. Para utilizar um índice 2d em pontos GeoJSON, crie o índice no campo coordinates do objeto GeoJSON.

O operador $nearSphere pode especificar um ponto GeoJSON ou ponto de coordenadas legado.

Para especificar um ponto GeoJSON, utilize a seguinte sintaxe:

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

A $minDistance opcional limita os resultados para os documentos que têm pelo menos a distância especificada a partir do ponto central.
A $maxDistance opcional está disponível para ambos os índices.

Para especificar um ponto usando coordenadas legadas, use a seguinte sintaxe:

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

A $minDistance opcional está disponível somente quando a query utiliza o índice 2dsphere. $minDistance limita os resultados para os documentos que têm pelo menos a distância especificada a partir do ponto central.
A $maxDistance opcional está disponível para ambos os índices.

Se você utilizar longitude e latitude para coordenadas legadas, especifique a longitude primeiro e depois a latitude.

Comportamento

Restrição de índices especiais

Você não pode combinar o operador $nearSphere, 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 $nearSphere com a query $text.

Operação de classificação

O operador $nearSphere 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.
$nearSphere é 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 que o tipo dos pontos GeoJSON especificados é Point. Qualquer outro tipo de entrada retorna um erro.

Uso da Memória

Começando no MongoDB 9.0, o MongoDB rastreia a memória que $nearSphere usa para armazenar em buffer os resultados e remover registros duplicados. Se a query exceder o limite de memória de megabyte de 100 para o estágio, o MongoDB encerra a query e retorna um erro.

Somente as queries que correspondem a um grande número de documentos atingem o limite. Para reduzir a memória que a query exige, especifique maxDistance para restringir a área de pesquisa. Essa memória conta para o limite de memória por operação. Para saber mais, consulte Limite de memória por operação.

Exemplos

Especificar ponto central com GeoJSON

Considere uma collection places que contém documentos com um campo location e tem um índice 2dsphere.

Em seguida, o exemplo a seguir retorna location que esteja a pelo menos 1000 metros e no máximo 5000 metros do ponto especificado, ordenado do mais próximo para o mais distante:

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

Especificar ponto central utilizando coordenadas legadas

`2d` Index

Considere uma collection legacyPlaces que contém documentos com pares de coordenadas legados no campo location e tem um índice 2d.

Em seguida, o exemplo a seguir retorna os documentos cuja location está a no máximo 0.10 radianos do ponto especificado, ordenados do mais próximo para o mais distante:

db.legacyPlaces.find(
   { location : { $nearSphere : [ -73.9667, 40.78 ], $maxDistance: 0.10 } }
)

`2dsphere` Index

Se a collection tiver um índice 2dsphere, você também poderá definir a especificação opcional da $minDistance. Por exemplo, o seguinte exemplo retorna os documentos cuja location está a pelo menos 0.0004 radianos do ponto especificado, ordenados do mais próximo para o mais distante:

db.legacyPlaces.find(
   { location : { $nearSphere : [ -73.9667, 40.78 ], $minDistance: 0.0004 } }
)

Voltar

$perto

$polygon