$geoNear (Proximidade Geográfica)
Última atualização: 2026-10-09
$geoNear (Proximidade Geográfica)
$geoNear retorna documentos ordenados por proximidade geográfica e deve ser o primeiro estágio do pipeline, exigindo um índice geoespacial na coleção. Ele suporta um campo de saída distanceField, matemática esférica ou planar, filtros de minDistance e maxDistance e uma chave key para escolher entre vários campos geográficos. Cada resultado ganha uma distância calculada.
| Categoria | Avançado e Diagnóstico |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $geoNear: { near: { type: "Point", coordinates: [ <longitude>, <latitude> ] }, distanceField: "<distanceField>", spherical: <bool>, maxDistance: <meters>, query: <filter> } }⚙️ Parâmetros
| near | O ponto de referência, um ponto GeoJSON ou matriz de coordenadas legada. |
|---|---|
| distanceField | Nome do campo que recebe a distância calculada. |
| spherical | Quando true, calcula distâncias usando geometria esférica. |
| query | Filtro de consulta adicional. |
Retorno：Fluxo de documentos ordenado por distância, com o distanceField incluído
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $geoNear: lugares num raio de 5 km
db.places.aggregate([
{ $geoNear: {
near: { type: 'Point', coordinates: [-73.98, 40.75] },
distanceField: 'dist',
spherical: true,
maxDistance: 5000
} }
])Saída：
// Ordenados por distância crescente; cada documento carrega dist📌 Notas
- Deve ser o primeiro estágio do pipeline
- A coleção precisa de um índice geoespacial (2dsphere ou 2d)
- GeoJSON near exige spherical: true
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QO que acontece sem um índice geoespacial?
AGera erro; a coleção precisa ter um índice geoespacial 2dsphere ou 2d.
QOs resultados podem ser filtrados por distância?
ASim, por meio de maxDistance e minDistance, em metros no modo esférico.
QÉ possível adicionar outros filtros de consulta?
ASim, pelo parâmetro query, por exemplo { query: { category: 'restaurant' } }.
