$nearSphere (Perto, Esférico)
Última atualização: 2026-10-09
$nearSphere (Perto, Esférico)
$nearSphere retorna documentos geoespaciais ordenados por distância esférica (círculo máximo). `{ loc: { $nearSphere: { $geometry: { type: 'Point', coordinates: [lng, lat] }, $maxDistance: 5000 } } }`. Diferente de $near, ele sempre calcula a distância esférica em metros (a distância planar é usada apenas por $near em um índice 2d). Exige um índice 2dsphere.
| Categoria | Geoespacial |
|---|---|
| Versão do MongoDB | 2.4+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ <campo de localização>: { $nearSphere: { $geometry: <Point>, $maxDistance: <metros> } } }⚙️ Parâmetros
| campo de posição | O campo que armazena a localização. |
|---|---|
| geometria Point | Um GeoJSON Point com [longitude, latitude]. |
| maxDistance | Opcional; distância esférica máxima em metros. |
Retorno：Cursor dos documentos correspondentes (crescente por distância esférica)
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $nearSphere: lojas a até 5 km (esférico)
// Coordenadas são [longitude, latitude]
db.stores.find({
loc: { $nearSphere: {
$geometry: { type: 'Point', coordinates: [-73.97, 40.75] },
$maxDistance: 5000
} }
})Saída：
// Retorna lojas a até 5 km, ordenadas por distância esférica📌 Notas
- Sempre distância esférica — correto para consultas de proximidade no mundo inteiro
- Coordenadas são [longitude, latitude]; invertê-las aponta para o lugar errado
- Use $near ou $nearSphere, nunca ambos
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre $nearSphere e $near?
A$nearSphere sempre usa distância esférica em metros; $near usa distância planar em um índice 2d.
QQual é a ordem das coordenadas?
AGeoJSON é [longitude, latitude]; invertê-las cai longe do lugar certo.
QPosso usar $near e $nearSphere juntos?
ANão, apenas um deles pode aparecer em uma consulta.
