Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Operações do MongoDB CRUD

Consultas geoespaciais

Nesta página

  • Compatibilidade
  • Dados geoespaciais
  • Índices geoespaciais
  • Consultas geoespaciais
  • Modelos geoespaciais
  • Executar Queries Geoespaciais no Atlas
  • Exemplos

O MongoDB suporta operações de consulta em dados geoespaciais. Esta seção introduz as feições geoespaciais do MongoDB.

Compatibilidade

Você pode usar queries geoespaciais em implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem

  • MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB

  • MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Para implantações hospedadas no MongoDB Atlas, você pode executar queries geoespaciais na UI usando a barra de query Filter ou o construtor de agregação. Para saber mais,consulte Executar queries geoespaciais no Atlas.

Dados geoespaciais

No MongoDB, você pode armazenar dados geoespaciais como objetos GeoJSON ou como legacy coordinate pairs.

Objetos GeoJSON

Para calcular a geometria sobre uma esfera semelhante à Terra, armazene seus dados de localização como Objetos GeoJSON.

Para especificar dados GeoJSON, utilize um documento incorporado com:

  • um campo denominado type que especifica o tipo de objeto GeoJSON e

  • um campo chamado coordinates que especifica as coordenadas do objeto.

<field>: { type: <GeoJSON type> , coordinates: <coordinates> }

Importante

Se especificar coordenadas de latitude e longitude, liste a longitude primeiro e então a latitude.

  • Os valores de longitude válidos estão entre -180 e 180, ambos inclusos.

  • Os valores de latitude válidos estão entre -90 e 90, ambos inclusos.

Por exemplo, para especificar um Ponto GeoJSON:

location: {
      type: "Point",
      coordinates: [-73.856077, 40.848447]
}

Para obter uma lista dos objetos GeoJSON compatíveis com o MongoDB, bem como exemplos, consulte Objetos GeoJSON.

Consultas geoespaciais do MongoDB em objetos GeoJSON calculam em uma esfera; o MongoDB usa o sistema de referência WGS84 para queries geoespaciais em objetos GeoJSON.

Pares de coordenadas legados

Para calcular distâncias em um plano Euclideano, armazene seus dados de localização como legacy coordinate pairs e utilize um índice 2d. O MongoDB suporta cálculos de superfície esférica em legacy coordinate pairs usando um índice 2dsphere se você converter manualmente os dados para o tipo de ponto GeoJSON.

Para especificar dados como pares de coordenadas herdados, você pode usar uma array (preferencial) ou um documento incorporado.

Especifique por uma array (Preferencial):
<field>: [ <x>, <y> ]

Se especificar as coordenadas de latitude e longitude, liste primeiro a longitude e depois a latitude; ou seja,

<field>: [<longitude>, <latitude> ]

  • Os valores de longitude válidos estão entre -180 e 180, ambos inclusos.

  • Os valores de latitude válidos estão entre -90 e 90, ambos inclusos.

Especifique por meio de um documento incorporado:
<field>: { <field1>: <x>, <field2>: <y> }

Se estiver especificando coordenadas de latitude e longitude, o primeiro campo, independentemente do nome do campo, deve conter o valor de longitude e o segundo campo, o valor de latitude; ou seja

<field>: { <field1>: <longitude>, <field2>: <latitude> }

  • Os valores de longitude válidos estão entre -180 e 180, ambos inclusos.

  • Os valores de latitude válidos estão entre -90 e 90, ambos inclusos.

Para especificar pares de coordenadas legadas, as matrizes são preferíveis a um documento incorporado , pois algumas linguagens não garantem a ordenação do mapa associativo .

Índices geoespaciais

O MongoDB fornece os seguintes tipos de índice geoespacial para suportar queries geoespaciais. Para mais informações sobre índices geoespaciais, consulte Índices geoespaciais.

2dsphere

Os índices 2dsphere aceitam queries que calculam geometrias em uma esfera semelhante à Terra.

Para criar um índice do 2dsphere, utilize o método db.collection.createIndex() e especifique a string literal "2dsphere" como o tipo de índice:

db.collection.createIndex( { <location field> : "2dsphere" } )

onde o <location field> é um campo cujo valor é um objeto GeoJSON ou um par de coordenadas legadas.

Observação

Se você tentar criar um índice em um campo que contém uma matriz de pontos dogeoJSON, a construção do índice falhará e retornará o seguinte erro:

MongoServerError: Index build failed

Para obter mais informações sobre o índice 2dsphere , consulte Índices 2dsphere.

2d

2d indexa queries de suporte que calculam geometrias em um plano bidimensional. Embora o índice possa aceitar queries $nearSphere que calculam em uma esfera, se possível, use o índice 2dsphere para queries esféricas.

Para criar um índice 2d, utilize o método db.collection.createIndex() , especificando o campo de localização como a chave e a string literal "2d" como o tipo de índice:

db.collection.createIndex( { <location field> : "2d" } )

onde o <location field> é um campo cujo valor é um par de coordenadas legado.

Para mais informações sobre o índice 2d, consulte Índices 2D.

Consultas geoespaciais

Observação

Usar um índice 2d para queries sobre dados esféricos pode retornar resultados incorretos ou um erro. Por exemplo, índices 2d não suportam queries esféricas que envolvam em torno dos pólos.

Operadores de consulta geoespacial

O MongoDB fornece os seguintes operadores de query geoespacial:

Nome
Descrição
$geoIntersects
Seleciona geometrias que interseccionam com uma geometria GeoJSON. O índice 2dsphere suporta $geoIntersects.
$geoWithin
Seleciona geometrias dentro de uma geometria GeoJSON delimitadora. Os índices 2dsphere e 2d suportam $geoWithin.
$near
Retorna objetos geoespaciais próximos a um ponto. Requer um índice geoespacial. Os índices 2dsphere e 2d suportam $near.
$nearSphere
Retorna objetos geoespaciais próximos a um ponto em uma esfera. Requer um índice geoespacial. Os índices 2dsphere e 2d suportam $nearSphere.

Para obter mais detalhes, incluindo exemplos, consulte a página de referência individual.

Estágio de aggregation geoespacial

O MongoDB fornece o seguinte estágio de pipeline de agregaçãogeoespacial:

Estágio
Descrição
$geoNear

Retorna um fluxo ordenado de documentos baseado na proximidade de um ponto geoespacial. Incorpora a funcionalidade do $match, $sort e $limit para dados geoespaciais. Os documentos de saída incluem um campo de distância adicional e podem incluir um campo de identificador de local.

$geoNear exige um índice geoespacial.

Para mais detalhes, incluindo exemplos, consulte a página de referência do $geoNear.

Modelos geoespaciais

As consultas geoespaciais do MongoDB podem interpretar a geometria em uma superfície plana ou esfera.

2dsphere índices suportam apenas consultas esféricas (ou seja, consultas que interpretar geometrias em uma superfície esférica).

2d os índices suportam queries simples (ou seja, queries que interpretam geometrias em uma superfície plana) e algumas queries esféricas. Enquanto índices do 2d suportam algumas queries esféricas, o uso de índices do 2d para estas queries esféricas pode resultar em erro. Se possível, use índices 2dsphere para queries esféricas.

A tabela seguinte lista os operadores de consulta geoespacial, consulta suportada, utilizados por cada operação geoespacial:

(operação)
Query esférica/plana
Notas
$near (ponto central GeoJSON nesta linha e na linha seguinte, índice 2dsphere)
Esférica
Consulte também o operador $nearSphere, que fornece a mesma funcionalidade quando usado com GeoJSON e um índice 2dsphere.
$near (coordenadas legadas, índice 2d)
Plana
$nearSphere (ponto GeoJSON , índice dsphere2 )
Esférica

Fornece a mesma funcionalidade que $near operação que usa o ponto GeoJSON e um índice 2dsphere.

Para queries esféricas, pode ser preferível utilizar o $nearSphere que especifica explicitamente as queries esféricas no nome ao invés do operador $near.

$nearSphere (coordenadas legadas, índice 2d)
Esférica
Use apontar GeoJSON .
$geoWithin : { $geometry: ... }
Esférica
$geoWithin : { $box: ... }
Plana
$geoWithin : { $polygon: ... }
Plana
$geoWithin : { $center: ... }
Plana
$geoWithin : { $centerSphere: ... }
Esférica
$geoIntersects
Esférica
O $geoNear estágio de agregação (índice 2dsphere)
Esférica
$geoNear estágio de agregação (índice 2d)
Plana

Executar Queries Geoespaciais no Atlas

Exemplos

Crie uma collection places com os seguintes documentos:

db.places.insertMany( [
   {
      name: "Central Park",
      location: { type: "Point", coordinates: [ -73.97, 40.77 ] },
      category: "Parks"
   },
   {
      name: "Sara D. Roosevelt Park",
      location: { type: "Point", coordinates: [ -73.9928, 40.7193 ] },
      category: "Parks"
   },
   {
      name: "Polo Grounds",
      location: { type: "Point", coordinates: [ -73.9375, 40.8303 ] },
      category: "Stadiums"
   }
] )

A seguinte operação cria um índice 2dsphere no campo location:

db.places.createIndex( { location: "2dsphere" } )

A coleta places acima tem um índice 2dsphere. A query a seguir usa o operador $near para retornar documentos que estejam a pelo menos 1000 metros e no máximo 5000 metros do ponto GeoJSON especificado, classificados na ordem do mais próximo ao mais distante:

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

A operação a seguir usa a operação de aggregation $geoNear para retornar documentos que correspondem ao filtro de query { category: "Parks" }, classificados na ordem do mais próximo ao mais distante do ponto GeoJSON especificado:

db.places.aggregate( [
   {
      $geoNear: {
         near: { type: "Point", coordinates: [ -73.9667, 40.78 ] },
         spherical: true,
         query: { category: "Parks" },
         distanceField: "calcDistance"
      }
   }
] )
← Idiomas de pesquisa de texto
Encontre restaurantes com queries geoespaciais →

Nesta página