Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Referência
/
Operadores
/
Operadores de consulta e projeção
/
Operadores de consulta geoespacial

$nearSphere

Nesta página

  • Definição
  • Comportamento
  • Exemplos

Definição

$nearSphere

Especifica um ponto para o qual uma querygeoespacial do 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.

Coleções fragmentadas

Antes do MongoDB 4.0, as queries de $nearSphere não eram compatíveis com coleções fragmentadas. Em vez disso, você pode usar o estágio de agregação $geoNear ou o comando geoNear.

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.

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 Índice

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 Índice

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 } }
)
← $perto
$box →

Nesta página