/ /

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

Specifies a point for which a geospatial query returns the documents from nearest to farthest. MongoDB calculates distances for $nearSphere using spherical geometry.

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

The $nearSphere operator can specify either a GeoJSON point or legacy coordinate point.

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

You cannot combine the $nearSphere operator, which requires a special geospatial index, with a query operator or command that requires another special index. For example you cannot combine $nearSphere with the $text query.

Operação de classificação

The $nearSphere operator sorts documents by distance.

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

Starting in MongoDB 8.0, $near, $nearSphere, and $geoNear validate that the type of the specified GeoJSON points is Point. Any other input type returns an error.

Uso da Memória

Starting in MongoDB 9.0, MongoDB tracks the memory that $nearSphere uses to buffer results and to remove duplicate records. If the query exceeds the 100 megabyte memory limit for the stage, MongoDB ends the query and returns an error.

Apenas queries que correspondem a um grande número de documentos atingem o limite. Para reduzir a memória que a query requer, especifique maxDistance para restringir a área de pesquisa. Esta memória conta para o limite de memória por operação. Para aprender 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