Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs
Página inicial do Docs
/ /
Leia
Página inicial do Docs
/
Desenvolvimento
/
Operações CRUD
/
Leia
Página inicial do Docs
/
Desenvolvimento
/
Operações CRUD
/
Leia

Consultas geoespaciais

O MongoDB suporta operações de query em dados geoespaciais. Esta seção introduz os recursos geoespaciais do MongoDB.

Dados geoespaciais

No MongoDB, você pode armazenar dados geoespaciais como objetos GeoJSON ou como pares de coordenadas legadas.

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

Use legacy coordinate pairs para cálculos planos (euclideanos) com um 2d Indexes índice. Para executar cálculos esféricos, converta pares legado em um GeoJSON Point e use um índice 2dsphere Índices.

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

array:
<field>: [ <x>, <y> ]

Quando você usar longitude e latitude, liste primeiro a longitude e depois a latitude:

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

documento incorporado:
<field>: { <field1>: <x>, <field2>: <y> }

Se você utilizar longitude e latitude, o primeiro campo deverá ser longitude e o segundo deverá ser latitude:

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

Use arrays para legacy coordinate pairs porque alguns idiomas não preservam a ordem dos campo de objeto.

Índices geoespaciais

Os índices geoespaciais apoiam queries em dados armazenados como objetos GeoJSON ou legacy coordinate pairs. Você pode utilizar índices geoespaciais para melhorar o desempenho para queries em dados geoespaciais ou para executar determinadas queries geoespaciais.

O MongoDB fornece dois tipos de índices geoespaciais:

  • Índices de esferas, que suportam queries que interpretam a geometria em uma esfera.

  • Índices 2D, que suportam queries que interpretam a geometria em uma superfície plana.

Para mais informações sobre índices geoespaciais, consulte Índices geoespaciais.

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.

Se um documento indexado contiver campos de coordenadas legado e um objeto GeoJSON no mesmo subdocumento do location, o MongoDB selecionará a representação indexada baseado na versão do servidor :

  • O MongoDB anterior a 8.2 indexa a primeira representação suportada de acordo com a ordem dos campo . Se os dois primeiros campos forem numéricos, o MongoDB os interpretará como um par [longitude, latitude] legado e ignorará todos os campos GeoJSON que aparecerem depois.

  • O MongoDB 8.2 e posterior sempre indexam a representação GeoJSON quando o subdocumento contém qualquer objeto GeoJSON , independentemente da ordem dos campo .

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

Seleciona geometrias que interseccionam com uma geometria GeoJSON. O índice 2dsphere suporta $geoIntersects.

Seleciona geometrias dentro de uma geometria GeoJSON delimitadora. Os índices 2dsphere e 2d suportam $geoWithin.

Retorna objetos geoespaciais próximos a um ponto. Requer um índice geoespacial. Os índices 2dsphere e 2d suportam $near.

Retorna objetos geoespaciais próximos a um ponto em uma esfera. Requer um índice geoespacial. Os índices 2dsphere e 2d suportam $nearSphere.

Observação

A coleção de séries temporais suporta apenas o estágio de agregação $geoNear para classificar dados geoespaciais de queries em consultas contra índices 2dsphere. 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

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 interpretam geometrias em uma superfície esférica).

2d índices suportam queries planas (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

Esférica

Plana

$nearSphere ( pontoGeoJSON, 2índice dsphere)

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.

Esférica

Use apontar GeoJSON .

Esférica

$geoWithin : { $box: ... }

Plana

$geoWithin : { $polygon: ... }

Plana

$geoWithin : { $center: ... }

Plana

Esférica

Esférica

Esférica

Plana

Executar Queries Geoespaciais no Atlas

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

1

Crie um índice

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

  1. Selecione o banco de dados para a collection.

    O painel principal e Namespaces no lado esquerdo listam as collections na base de dados.

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

  3. Selecione a visualização Índice.

    Quando você abre a visualização Index, o Atlas exibe todos os índices existentes na collection.

  4. Defina o índice para o tipo geoespacial

    Pressione o botão Create Index.

    Defina um índice de tipo geoespacial. Consulte Como indexar objetos GeoJSON.

2

Execute uma query dos dados geoespaciais

  1. Selecione a visualização Localizar.

    Na collection que contém seus dados geoespaciais, selecione a aba Find para visualizar sua collection geoespacial.

  2. 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 ]
              ]
            ]
          }
        }
      }
    }

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

Exemplos

Os exemplos nesta página usam dados do conjunto de dados sample_mflix. Para obter detalhes sobre como carregar esse conjunto de dados em sua implantação autogerenciada do MongoDB , consulte Carregar o conjunto de dados de amostra. Se você fez modificações nos bancos de dados de amostra, talvez seja necessário descartar e recriar os bancos de dados para executar os exemplos nesta página.

A coleção sample_mflix.theaters tem um índice 2dsphere. A query a seguir usa o operador $near para retornar documentos classificados do mais próximo para o mais distante. A query retorna documentos a pelo menos 1000 metros e no máximo 100000 metros do ponto GeoJSON especificado:

db.theaters.find(
   {
      "location.geo": {
         $near: {
            $geometry: {
               type: "Point",
               coordinates: [ -73.9667, 40.78 ]
            },
            $minDistance: 1000,
            $maxDistance: 100000
         }
      }
   }
).limit(3)
[
  {
    _id: ObjectId('59a47287cfa9a3a73e51eae8'),
    theaterId: 374,
    location: {
      address: {
        street1: '2478 Central Park Ave',
        city: 'Yonkers',
        state: 'NY',
        zipcode: '10710'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.826805, 40.983246 ]
      }
    }
  },
  {
    _id: ObjectId('59a47287cfa9a3a73e51ead6'),
    theaterId: 345,
    location: {
      address: {
        street1: '148 Walt Whitman Rd',
        city: 'Huntington Station',
        state: 'NY',
        zipcode: '11746'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.410637, 40.825775 ]
      }
    }
  },
  {
    _id: ObjectId('59a47287cfa9a3a73e51e92f'),
    theaterId: 200,
    location: {
      address: {
        street1: '3124 Jericho Tpke',
        city: 'East Northport',
        state: 'NY',
        zipcode: '11731'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.319092, 40.838463 ]
      }
    }
  }
]

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

db.theaters.aggregate( [
   {
      $geoNear: {
         near: { type: "Point", coordinates: [ -73.9667, 40.78 ] },
         spherical: true,
         query: { "location.address.state": "NY" },
         distanceField: "calcDistance"
      }
   },
   { $limit: 3 }
] )
[
  {
    _id: ObjectId('59a47287cfa9a3a73e51eae8'),
    theaterId: 374,
    location: {
      address: {
        street1: '2478 Central Park Ave',
        city: 'Yonkers',
        state: 'NY',
        zipcode: '10710'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.826805, 40.983246 ]
      }
    },
    calcDistance: 27000
  },
  {
    _id: ObjectId('59a47287cfa9a3a73e51ead6'),
    theaterId: 345,
    location: {
      address: {
        street1: '148 Walt Whitman Rd',
        city: 'Huntington Station',
        state: 'NY',
        zipcode: '11746'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.410637, 40.825775 ]
      }
    },
    calcDistance: 55000
  },
  {
    _id: ObjectId('59a47287cfa9a3a73e51e92f'),
    theaterId: 200,
    location: {
      address: {
        street1: '3124 Jericho Tpke',
        city: 'East Northport',
        state: 'NY',
        zipcode: '11731'
      },
      geo: {
        type: 'Point',
        coordinates: [ -73.319092, 40.838463 ]
      }
    },
    calcDistance: 72000
  }
]
Voltar
Text Indexes
Próximo
Objetos GeoJSON
Avalie esta página

Nesta página