$geoNear (estágio de agregação )

Definição

$geoNear

Produz documentos na ordem do mais próximo para o mais distante de um ponto especificado.

O estágio $geoNear tem o seguinte formato de protótipo:

{ $geoNear: { <geoNear options> } }

O operador do $geoNear aceita um documento que contém as seguintes opções do $geoNear. Especifique todas as distâncias nas mesmas unidades que as do sistema de coordenadas dos documentos processados:

Campo	Tipo	Descrição
`distanceField`	string	O campo de saída que contém a distância calculada. Para especificar um campo em um documento incorporado, use a notação de ponto.
`distanceMultiplier`	número	Opcional. O fator para multiplicar todas as distâncias retornadas pela consulta. Por exemplo, utilize o `distanceMultiplier` para converter radianos, como retornado por uma consulta esférica, para quilômetros multiplicando pelo raio da Terra.
`includeLocs`	string	Opcional. Isto especifica o campo de saída que identifica o local utilizado para calcular a distância. Esta opção é útil quando um campo de localização contém múltiplos locais. Para especificar um campo dentro de um documento incorporado, use notação de ponto.
`key`		Opcional. Especifique o campo indexado geoespacial para utilizar ao calcular a distância. Se a sua coleção tiver múltiplos índices `2d` e/ou múltiplos índices `2dsphere` , você deve utilizar a opção `key` para especificar o caminho do campo indexado para utilizar. Especifique qual índice geoespacial usar fornece um exemplo completo. Se houver mais de um índice `2d` ou mais de um índice `2dsphere` e você não especificar um `key`, MongoDB retornará um erro. Se você não especificar `key` e tiver no máximo apenas um índice `2d` e/ou apenas um índice `2dsphere`, o MongoDB procurará primeiro um índice `2d` para usar. Se um índice `2d` não existir, o MongoDB procurará um índice `2dsphere` para usar. Você deve especificar o campo `key` para `$geoNear` em uma coleção de séries temporais.
`maxDistance`	número	Opcional. A distância máxima do ponto central que os documentos podem estar. O MongoDB limita os resultados aos documentos que se enquadram dentro da distância especificada a partir do ponto central. A partir da versão 7.2, você pode especificar uma expressão constante válida que se resolve em um número. Especifique a distância em metros se o ponto especificado for GeoJSON e em radianos se o ponto especificado for pares de coordenadas legadas.
`minDistance`	número	Opcional. A distância mínima do ponto central na qual os documentos podem estar. O MongoDB limita os resultados aos documentos que estão fora da distância especificada do ponto central. A partir da versão 7.2, você pode especificar uma expressão constante válida que se resolve em um número. Especifique a distância em metros para dados GeoJSON e em radianos para pares de coordenadas legadas.
`near`	Ponto GeoJSON ou par de coordenadas legado	O ponto para o qual encontrar os documentos mais próximos. Se estiver usando um índice 2dsphere, você poderá especificar o ponto como um ponto GeoJSON ou um par de coordenadas herdadas. Se utilizar um índice 2d, especifique o ponto como um par de coordenadas legado.
`query`	documento	Opcional. Limita os resultados aos documentos que correspondem à consulta. A sintaxe de consulta é a sintaxe habitual de consulta de operação de leitura MongoDB. Você não pode especificar um predicado `$near` no campo `query` do estágio `$geoNear`. Não é possível usar o campo `query` para `$geoNear` em uma coleção de séries temporais.
`spherical`	booleano	Opcional. Determina como MongoDB calcula a distância entre dois pontos: Quando `true`, MongoDB utiliza semântica do `$nearSphere` e calcula distâncias utilizando geometria esférica. Quando `false`, MongoDB utiliza semântica `$near`: geometria esférica para índices 2dsphere e geometria planar para índices 2d. Padrão: false.

Comportamento

Cálculos de distância

$geoNear calcula a distância com base no ponto mais próximo do parâmetro do documento de entrada.

Por exemplo, se o documento de entrada for uma forma , $geoNear identifica o ponto no limite da forma que é mais próximo do ponto especificado e produzirá a distância entre o ponto especificado e o ponto mais próximo da forma .

Considerações

Ao usar $geoNear, considere que:

Você só pode usar $geoNear como o primeiro estágio de um pipeline.
Você deve incluir a opção distanceField. A opção distanceField especifica o campo que conterá a distância calculada.
$geoNear requer um índice geoespacial.

Se você tiver mais de um índice geoespacial na coleção, utilize o parâmetro keys para especificar qual campo utilizar no cálculo. Se você tiver somente um índice geoespacial, o $geoNear implicitamente utilizará o campo indexado para o cálculo.

Você não pode especificar um predicado $near no campo query do estágio $geoNear.
$geoNear não tem mais um limite-padrão de 100 documentos.
O parâmetro near tem suporte para a opção let e opção bound let.
Você pode usar o operador de pipeline $geoNear em qualquer campo em uma coleção de séries temporais. No entanto, não é possível usar o campo query para $geoNear em uma coleção de séries temporais.
Você pode criar índices parciais e 2dsphere em qualquer campo em uma coleção de séries temporais.
Começando no MongoDB 8.0, $near, $nearSphere e $geoNear, valide que o tipo dos pontos GeoJSON especificados é Point. Qualquer outro tipo de entrada retorna um erro.

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

Distância máxima

A coleção places acima tem um índice 2dsphere. A seguinte agregação utiliza $geoNear para encontrar documentos com uma localização a no máximo 2 metros do centro [ -73.99279 , 40.719296 ] e category igual a Parks.

db.places.aggregate([   {     $geoNear: {        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },        distanceField: "dist.calculated",        maxDistance: 2,        query: { category: "Parks" },        includeLocs: "dist.location",        spherical: true     }   }])

A agregação retorna o seguinte:

{   "_id" : 8,   "name" : "Sara D. Roosevelt Park",   "category" : "Parks",   "location" : {      "type" : "Point",      "coordinates" : [ -73.9928, 40.7193 ]   },   "dist" : {      "calculated" : 0.9539931676365992,      "location" : {         "type" : "Point",         "coordinates" : [ -73.9928, 40.7193 ]      }   }}

O documento correspondente contém dois novos campos:

dist.calculated campo que contém a distância calculada e
dist.location que contém o local utilizado no cálculo.

Distância mínima

O exemplo seguinte utiliza a opção minDistance para especificar a distância mínima do ponto central que os documentos podem ser. A seguinte aggregation encontra todos os documentos com um local a pelo menos 2 metros do centro [ -73.99279 , 40.719296 ] e category igual a Parks.

db.places.aggregate([   {     $geoNear: {        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },        distanceField: "dist.calculated",        minDistance: 2,        query: { category: "Parks" },        includeLocs: "dist.location",        spherical: true     }   }])

$geoNear com a opção `let`

Neste exemplo:

A opção let é utilizada para definir um valor de array de [-73.99279,40.719296] para a variável $pt.
$pt é especificado como uma opção let para o parâmetro near no estágio $geoNear .

db.places.aggregate([   {      "$geoNear":      {         "near":"$$pt",         "distanceField":"distance",         "maxDistance":2,         "query":{"category":"Parks"},         "includeLocs":"dist.location",         "spherical":true      }   }],{   "let":{ "pt": [ -73.99279, 40.719296 ] }})

A agregação retorna todos os documentos com:

Um local a no máximo 2 metros do ponto definido na variável let
Um category igual a Parks.

{   _id: ObjectId("61715cf9b0c1d171bb498fd7"),   name: 'Sara D. Roosevelt Park',   location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },   category: 'Parks',   distance: 1.4957325341976439e-7,   dist: { location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] } }},{   _id: ObjectId("61715cf9b0c1d171bb498fd6"),   name: 'Central Park',   location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },   category: 'Parks',   distance: 0.0009348548688841822,   dist: { location: { type: 'Point', coordinates: [ -73.97, 40.77 ] } }}

$geoNear com opção bound `let`

A opção let pode vincular uma variável que pode ser utilizada em uma query $geoNear.

Neste exemplo, o $lookup utiliza:

let para definir $pt.
$geoNear no pipeline.
$pt para definir near no estágio do pipeline $geoNear.

db.places.aggregate( [   {      $lookup: {         from: "places",         let: { pt: "$location" },         pipeline: [            {               $geoNear: {                  near: "$$pt",                  distanceField: "distance"               }            }         ],         as: "joinedField"      }   },   {      $match: { name: "Sara D. Roosevelt Park" }   }] );

A agregação retorna um documento com:

O documento "Sara D. Roosevelt Park" como o documento principal.
Cada documento na coleção de locais como subDocumentos usando a variável $pt para calcular a distância.

{   _id: ObjectId("61715cf9b0c1d171bb498fd7"),      name: 'Sara D. Roosevelt Park',      location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },      category: 'Parks',      joinedField: [         {         _id: ObjectId("61715cf9b0c1d171bb498fd7"),         name: 'Sara D. Roosevelt Park',         location: { type: 'Point', coordinates: [ -73.9928, 40.7193 ] },         category: 'Parks',         distance: 0         },         {         _id: ObjectId("61715cf9b0c1d171bb498fd6"),         name: 'Central Park',         location: { type: 'Point', coordinates: [ -73.97, 40.77 ] },         category: 'Parks',         distance: 5962.448255234964         },         {         _id: ObjectId("61715cfab0c1d171bb498fd8"),         name: 'Polo Grounds',         location: { type: 'Point', coordinates: [ -73.9375, 40.8303 ] },         category: 'Stadiums',         distance: 13206.535424939102         }      ]}

Especifique qual índice geoespacial usar

Considere uma coleção places que tenha um índice 2dsphere no campo location e um índice 2d no campo legacy.

Um documento na collection places se assemelha a:

{   "_id" : 3,   "name" : "Polo Grounds",   "location": {      "type" : "Point",      "coordinates" : [ -73.9375, 40.8303 ]   },   "legacy" : [ -73.9375, 40.8303 ],   "category" : "Stadiums"}

O exemplo a seguir usa a opção key para especificar que a agregação deve usar os valores de campo location para a operação $geoNear e não os valores de campo legacy. O pipeline também usa $limit para retornar no máximo 5 documentos.

db.places.aggregate([   {     $geoNear: {        near: { type: "Point", coordinates: [ -73.98142 , 40.71782 ] },        key: "location",        distanceField: "dist.calculated",        query: { "category": "Parks" }     }   },   { $limit: 5 }])

A agregação retorna o seguinte:

{   "_id" : 8,   "name" : "Sara D. Roosevelt Park",   "location" : {      "type" : "Point",      "coordinates" : [         -73.9928,         40.7193      ]   },   "category" : "Parks",   "dist" : {      "calculated" : 974.175764916902   }}{   "_id" : 1,   "name" : "Central Park",   "location" : {      "type" : "Point",      "coordinates" : [         -73.97,         40.77      ]   },   "legacy" : [      -73.97,      40.77   ],   "category" : "Parks",   "dist" : {      "calculated" : 5887.92792958097   }}

Os exemplos de C# nesta página utilizam o banco de dados sample_mflix a partir dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de exemplo, consulte Introdução na documentação do driver MongoDB .NET/C#.

As seguintes classes Theater, TheaterLocation e TheaterAddress modelam os documentos na coleção sample_mflix.theaters:

[BsonIgnoreExtraElements]public class Theater{    [BsonId]    public ObjectId Id { get; set; }
    [BsonElement("theaterId")]    public int TheaterId { get; set; }
    [BsonElement("location")]    public TheaterLocation Location { get; set; } = null!;
    [BsonElement("distance")]    public double? Distance { get; set; }}
[BsonIgnoreExtraElements]public class TheaterLocation{    [BsonElement("address")]    public TheaterAddress Address { get; set; } = null!;}
[BsonIgnoreExtraElements]public class TheaterAddress{    [BsonElement("city")]    public string? City { get; set; }
    [BsonElement("state")]    public string? State { get; set; }}

Para usar o driver MongoDB .NET/C# para adicionar um estágio $geoNear a uma agregação pipeline, chame o método UnionWith() em um objeto PipelineDefinition.

Este método está disponível apenas no MongoDB .NET/C# driver v3.4 e posterior.

Distância máxima

O exemplo a seguir cria um estágio de pipeline que retorna documentos em um raio de 8000 metros do ponto especificado, em ordem crescente de distância. O código inclui um parâmetro Query que apenas corresponde a documentos nos quais o valor do campo location.address.state é "NJ". O código também armazena a distância calculada no campo distance dos documentos de saída.

var pipeline = new EmptyPipelineDefinition<Theater>()    .GeoNear(        GeoJson.Point(GeoJson.Geographic(-74.1, 40.95)),        new GeoNearOptions<Theater, Theater>        {            DistanceField = "distance",            MaxDistance = 8000,            Key = "location.geo",            Query = Builders<Theater>.Filter.Eq(                t => t.Location.Address.State, "NJ"),        });

{ "_id" : "...", "theaterId" : 344, "location" : { "address" : { "city" : "Paramus", "state" : "NJ" } }, "distance" : "..." }{ "_id" : "...", "theaterId" : 2978, "location" : { "address" : { "city" : "Paramus", "state" : "NJ" } }, "distance" : "..." }{ "_id" : "...", "theaterId" : 1936, "location" : { "address" : { "city" : "Paramus", "state" : "NJ" } }, "distance" : "..." }{ "_id" : "...", "theaterId" : 887, "location" : { "address" : { "city" : "Paramus", "state" : "NJ" } }, "distance" : "..." }

Distância mínima

O exemplo a seguir retorna os primeiros 4 documentos correspondentes fora de um raio de 8000 metros do ponto especificado , em ordem de distância crescente. O código inclui um parâmetro Query que só corresponde a documentos nos quais o valor do campo location.address.state é "NJ". O código também armazena a distância calculada no campo distance dos documentos de saída.

var pipeline = new EmptyPipelineDefinition<Theater>()    .GeoNear(        GeoJson.Point(GeoJson.Geographic(-74.1, 40.95)),        new GeoNearOptions<Theater, Theater>        {            DistanceField = "distance",            MinDistance = 8000,            Key = "location.geo",            Query = Builders<Theater>.Filter.Eq(                t => t.Location.Address.State, "NJ"),        })    .Limit(4);

{ "_id" : "...", "theaterId" : 468, "location" : { "address" : { "city" : "Woodland Park", "state" : "NJ" } }, "distance" : "..." }{ "_id" : "...", "theaterId" : 8539, "location" : { "address" : { "city" : "Bloomfield", "state" : "NJ" } }, "distance" : "..." }{ "_id" : "...", "theaterId" : 2703, "location" : { "address" : { "city" : "Wayne", "state" : "NJ" } }, "distance" : "..." }{ "_id" : "...", "theaterId" : 2509, "location" : { "address" : { "city" : "Riverdale", "state" : "NJ" } }, "distance" : "..." }

Os exemplos do Node.js nesta página utilizam o banco de dados do sample_mflix a partir dos conjuntos de dados de amostra do Atlas. Para saber como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de exemplo, consulte Introdução na documentação do driver do MongoDB Node.js

Para usar o driver Node.js do MongoDB para adicionar um estágio $geoNear a um pipeline de agregação , use o operador $geoNear em um objeto de pipeline.

Distância máxima

O exemplo a seguir cria um estágio de pipeline que retorna documentos em um raio de 8000 metros do ponto especificado, em ordem de distância crescente. O código inclui um campo query que só corresponde a documentos em que o valor do campo location.address.state é "NJ". O código também armazena a distância calculada no campo distance dos documentos de saída. Em seguida, o exemplo executa o agregação pipeline:

const pipeline = [  {    $geoNear: {      near: {        type: "Point",        coordinates: [-74.1, 40.95]      },      distanceField: "distance",      maxDistance: 8000,      query: { "location.address.state": "NJ" },      spherical: true    }  }];
const cursor = collection.aggregate(pipeline);return cursor;

Distância mínima

O exemplo a seguir retorna os primeiros 4 documentos correspondentes fora de um raio de 8000 metros do ponto especificado , em ordem de distância crescente. O código inclui um campo query que só corresponde a documentos em que o valor do campo location.address.state é "NJ". O código também armazena a distância calculada no campo distance dos documentos de saída:

const pipeline = [  {    $geoNear: {      near: {        type: "Point",        coordinates: [-74.1, 40.95]      },      distanceField: "distance",      minDistance: 8000,      query: { "location.address.state": "NJ" },      spherical: true    },  },  { $limit: 4 }];
const cursor = collection.aggregate(pipeline);return cursor;

Saiba mais

Para saber mais sobre os estágios de pipeline relacionados, consulte o guia$limit.

Voltar

$fill

$graphLookup

$geoNear (estágio de agregação )

Definição

Comportamento

Cálculos de distância

Considerações

Exemplos

Distância máxima

Distância mínima

$geoNear com a opção let

$geoNear com opção bound let

Especifique qual índice geoespacial usar

Distância máxima

Distância mínima

Distância máxima

Distância mínima

Saiba mais

$geoNear com a opção `let`

$geoNear com opção bound `let`