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 do 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: Para obter mais detalhes, incluindo exemplos, consulte as respectivas páginas de referência.

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

Observação

As coleções de séries temporais suportam apenas o estágio de agregação$geoNearpara classificar dados geoespaciais de consultas em relação a índices2dsphere. Você não pode usar os operadores $near e $nearSphere em coleções de séries temporais

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` requer 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 centralGeoJSON nesta linha e 2na seguinte linha, índice dsphere)	Esférica	Consulte também o `$nearSphere` operador, que fornece a mesma funcionalidade quando usado com GeoJSON e um índice 2 dsphere.
`$near` (coordenadaslegado, índice2 d)	Plana
`$nearSphere` ( ponto2 GeoJSON, índice dsphere)	Esférica	Fornece a mesma funcionalidade que operação `$near` que usa o ponto GeoJSON e 2um índice dsphere. 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` (coordenadaslegado, índice2 d)	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
`$geoNear` estágio de2agregação (índice dsphere)	Esférica
`$geoNear` estágio de agregação (2 índice d)	Plana

Executar Queries Geoespaciais no Atlas

Você pode utilizar a UI do Atlas MongoDB para executar consultas geoespaciais no Atlas.

Crie um índice

Se a sua coleta geoespacial ainda não tiver um índice geoespacial, você deverá criar um.

Selecione o banco de dados para a collection.
O painel principal e Namespaces no lado esquerdo listam as collections na base de dados.
Selecione a collection.
Selecione a collection que contém seus dados geoespaciais no lado esquerdo ou no painel principal. O painel principal exibe as visualizações Find, Indexes e Aggregation.
Selecione a visualização Índice.
Quando você abre a visualização Index, o Atlas exibe todos os índices existentes na collection.
Defina o índice para o tipo geoespacial
Pressione o botão Create Index.
Defina um índice de tipo geoespacial. Consulte Como indexar objetos GeoJSON.

Execute uma query dos dados geoespaciais

Selecione a visualização Localizar.
Na collection que contém seus dados geoespaciais, selecione a aba Find para visualizar sua collection geoespacial.

Insira uma query.

Insira uma query na caixa de texto Filter. Utilize qualquer um dos operadores de query geoespacial para executar a query relevante em seus dados geoespaciais. Uma query geoespacial pode se parecer com:

{
  "coordinates": {
    $geoWithin: {
      $geometry: {
        type: "Polygon",
        coordinates: [
          [
            [-80.0, 10.00], [ -80.0, 9.00], [ -79.0, 9.0], [ -79.0, 10.00 ], [ -80.0, 10.0 ]
          ]
        ]
      }
    }
  }
}

Pressione o botão Aplicar.
Pressione o botão Apply para aplicar sua query. O Atlas filtra os dados geoespaciais para mostrar somente documentos que correspondem à sua query geoespacial.

Você pode criar e executar pipelines de agregação para realizar consultas geoespaciais na IU do MongoDB Atlas.

Acessar o Construtor de Pipeline de Agregação

Selecione o banco de dados para a collection.
O painel principal e Namespaces no lado esquerdo listam as collections na base de dados.
Selecione a collection.
Selecione a collection que contém seus dados geoespaciais no lado esquerdo ou no painel principal. O painel principal exibe as visualizações Find, Indexes e Aggregation.
Selecione a visualização Agregação.
Quando abre pela primeira vez a vista Aggregation , Atlas exibe um pipeline de agregação vazio.

Crie seu pipeline de agregação de queries geoespaciais

Selecione um estágio de agregação.
Selecione um estágio de agregação no menu suspenso Select no painel inferior esquerdo.
O botão à direita do menu suspenso determina se o o estágio está ativado.
Use o estágio $geoNear para realizar consultas geoespaciais em seu pipeline de agregação.
Preencha seu estágio de agregação.
Preencha seu estágio com os valores apropriados. Se o Modo de Comentário estiver habilitado, o construtor de pipeline fornecerá diretrizes sintáticas para o estágio selecionado.
Conforme você modifica seu estágio, o Atlas atualiza os documentos de visualização à direita com base nos resultados do estágio atual.
Seu estágio $geoNear pode ser semelhante a:
```
{
  near: { type: "Point", coordinates: [ -73.9667, 40.78 ] },
  spherical: true,
  query: { category: "Parks" },
  distanceField: "calcDistance"
}
```
Execute outras etapas do pipeline conforme necessário.
Adicione fases conforme necessário para concluir o pipeline de agregação. Você pode adicionar $out ou $merge para gravar os resultados em uma exibição ou na coleção atual.

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"
      }
   }
] )

Voltar

Pesquisa de texto

Encontre restaurantes