/ /

Operadores

Etapas de la pipeline de agregación

Docs Home

Manual de base de datos

Referencia

Operadores

Etapas de la pipeline de agregación

$geoNear (operador de expresión)

Esta versión de la documentación se archivó y ya no se admite. Para actualizar tu implementación de 6.0, consulta el Procedimientos de actualización de MongoDB 7.0 .

Definición

$geoNear

Emite documentos en orden de más cercano a más lejano desde un punto especificado.

Nota

MongoDB remueve las opciones limit y num para la etapa $geoNear además del límite por defecto de 100 documentos. Para limitar los resultados de $geoNear, utiliza la etapa $geoNear con el $limit etapa.

La etapa $geoNear tiene la siguiente forma de prototipo:

{ $geoNear: { <geoNear options> } }

El operador $geoNear acepta un documento que contiene las siguientes opciones $geoNear. Especifique todas las distancias en las mismas unidades que las del sistema de coordenadas de los documentos procesados:

Campo	Tipo	Descripción
`distanceField`	string	El campo de salida que contiene la distancia calculada. Para especificar un campo dentro de un documento incrustado, utiliza notación de puntos.
`distanceMultiplier`	Número	Opcional. Factor para multiplicar todas las distancias devueltas por la query. Por ejemplo, usar el `distanceMultiplier` para convertir radianes, tal como los devuelve una query esférica, a kilómetros multiplicando por el radio de la Tierra.
`includeLocs`	string	opcional. Esto especifica el campo de salida que identifica la ubicación utilizada para calcular la distancia. Esta opción es útil cuando un campo de ubicación contiene varias ubicaciones. Para especificar un campo dentro de un documento incrustado, usa la notación de puntos.
`key`		Opcional. Especificar el campo geoespacial indexado que se utilizará al calcular la distancia. Si tu colección tiene varios índices de `2d` y/o varios de `2dsphere`, debes usar la opción `key` para especificar la ruta de campo indexado que se utilizará. Especificar Qué Índice Geoespacial Usar proporciona un ejemplo completo. Si hay más de un índice `2d` o más de un índice `2dsphere` y no se especifica un `key`, MongoDB devolverá un error. Si no especificas el `key`, y tienes como máximo solo un índice `2d` y/o solo un índice `2dsphere`, MongoDB primero buscará un índice `2d` para usar. Si un índice `2d` no existe, MongoDB busca un índice `2dsphere` para usar.
`maxDistance`	Número	opcional. La distancia máxima desde el punto central a la que los documentos pueden estar. MongoDB limita los resultados a aquellos documentos que se encuentren dentro de la distancia especificada desde el punto central. Especifica la distancia en metros si el punto especificado es GeoJSON y en radianes si el punto especificado es legacy coordinate pairs.
`minDistance`	Número	opcional. La distancia mínima desde el punto central que los documentos pueden estar. MongoDB limita los resultados a aquellos documentos que se encuentran fuera de la distancia especificada desde el punto central. Especifica la distancia en metros para los datos GeoJSON y en radianes para los legacy coordinate pairs.
`near`	Punto GeoJSON o par de coordenadas antiguo	El punto para el que encontrar los documentos más cercanos. Si se utiliza un índice 2dsphere, se puede especificar el punto como un punto GeoJSON o como un par de coordenadas heredado. Si utiliza un índice 2d, especifique el punto como un par de coordenadas legacies.
`query`	Documento	opcional. Limita los resultados a los documentos que coinciden con la query. La sintaxis de queries es la sintaxis habitual de query para operaciones de lectura en MongoDB. No puedes especificar un predicado de `$near` en el campo `query` de la etapa `$geoNear`.
`spherical`	booleano	Opcional. Determina cómo MongoDB calcula la distancia entre dos puntos: Cuando `true`, MongoDB utiliza la semántica `$nearSphere` y calcula las distancias utilizando geometría esférica. Al `false`, MongoDB utiliza la `$near` semántica: geometría esférica para los índices 2dsphere e índices planares para los índices 2d. Por defecto: falso.

Comportamiento

Cálculos de distancia

$geoNear calcula la distancia basándose en el punto más cercano del perímetro del documento de entrada.

Por ejemplo, si el documento de entrada es una forma, $geoNear identifica el punto del perímetro de la forma que está más cerca del punto especificado y proporciona la distancia entre el punto especificado y el punto más cercano de la forma.

Considerations

Al usar $geoNear, considere lo siguiente:

Solo puedes usar $geoNear como la primera etapa de una pipeline.
Debe incluir la opción distanceField. La opción distanceField especifica el campo que contendrá la distancia calculada.
$geoNear requiere un índice geoespacial.
Si tienes más de un índice geoespacial en la colección, utiliza el parámetro keys para especificar qué campo deseas usar en el cálculo. Si solo tienes un índice geoespacial, $geoNear usará implícitamente el campo indexado para el cálculo.

No puedes especificar un predicado $near en el campo query de la etapa $geoNear.
$geoNear ya no tiene un límite por defecto de 100 documentos.
A partir de MongoDB 5.1, el parámetro near admite la opción let y la opción let vinculada.
A partir de MongoDB 5.3, puedes usar el operador de pipeline $geoNear en cualquier campo de una colección de series de tiempo.
A partir de MongoDB 6.0, puedes crear índices parciales e índices 2dsphere en cualquier campo de una colección de series de tiempo.

Ejemplos

Cree una colección places con los siguientes 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"
   }
] )

La siguiente operación crea un índice 2dsphere en el campo location:

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

Distancia máxima

Nota

MongoDB remueve las opciones limit y num para la etapa $geoNear, así como el límite por defecto de 100 documentos. Para limitar los resultados de $geoNear, use la etapa $geoNear con la etapa $limit.

La colección places anterior tiene un índice 2dsphere. La siguiente agregación utiliza $geoNear para encontrar documentos con una ubicación a lo sumo a 2 metros del centro [ -73.99279 , 40.719296 ] y 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
     }
   }
])

La agregación devuelve lo siguiente:

{
   "_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 ]
      }
   }
}

El documento coincidente contiene dos nuevos campos:

dist.calculated campo que contiene la distancia calculada, y
dist.location campo que contiene la ubicación utilizada en el cálculo

Distancia mínima

Nota

El siguiente ejemplo utiliza la opción minDistance para especificar la distancia mínima desde el punto central a la que pueden estar los documentos. La siguiente agregación encuentra todos los documentos con una ubicación al menos a 2 metros del centro [ -73.99279 , 40.719296 ] y 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 con la opción `let`

En este ejemplo:

La opción let se utiliza para establecer un valor de arreglo de [-73.99279,40.719296] a la variable $pt.
$pt se especifica como una opción let para el parámetro near en la etapa $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 ] }
}
)

La agregación retorna todos los documentos con:

Una ubicación a no más de 2 metros del punto definido en la variable let
Un 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 con opción Bound `let`

La opción let puede vincular una variable que se puede utilizar en una query $geoNear.

En este ejemplo, $lookup utiliza:

let para definir $pt.
$geoNear en el pipeline.
$pt para definir near en la etapa de la 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" }
   }
] );

La agregación devuelve un documento con:

El documento de 'Sara D. Roosevelt Park' como el documento principal.
Cada documento en la colección de lugares como subdocumentos que utilizan la variable $pt para calcular la distancia.

{
   _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 qué índice geoespacial utilizar

Considerar una colección places que tiene un índice 2dsphere en el campo location y un índice 2D en el campo legacy.

Un documento en la colección places es similar a lo siguiente:

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

El siguiente ejemplo utiliza la opción key para especificar que la agregación debe utilizar los valores del campo location para la operación $geoNear en lugar de los valores del campo legacy. La pipeline también utiliza $limit para devolver como máximo 5 documentos.

Nota

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

La agregación devuelve lo siguiente:

{
   "_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
   }
}

Los ejemplos de C# en esta página utilizan la colección sample_mflix.theaters de los conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulta Empezar en la documentación del driver de MongoDB .NET/C# .

Las siguientes clases Theater, Location, y Address modelan los documentos de la colección sample_mflix.theaters:

public class Theater
{
  public ObjectId Id { get; set; }
  [BsonElement("theaterId")]
  public int TheaterId { get; set; }
  [BsonElement("location")]
  public Location Location { get; set; }
  [BsonElement("distance")]
  public double? Distance { get; set; }
}
public class Location
{
  [BsonElement("address")]
  public Address Address { get; set; }
  [BsonElement("geo")]
  public GeoJsonPoint<GeoJson2DGeographicCoordinates> Geo { get; set; }
}
[BsonIgnoreExtraElements]
public class Address
{
  [BsonElement("city")]
  public string City { get; set; }
  [BsonElement("state")]
  public string State { get; set; }
}

Para usar el driver de MongoDB .NET/C# para añadir una etapa $geoNear a un pipeline de agregación, llamar a la GeoNear() método en un objeto PipelineDefinition.

Este método está disponible solo en MongoDB .NET/controlador de C# v3.4 y versiones posteriores.

Distancia máxima

El siguiente ejemplo crea una etapa de pipeline que devuelve documentos en un radio de 8000 metros del punto especificado, en orden de distancia ascendente. El código incluye un parámetro Query que solo coincide con documentos en los que el valor del campo location.address.state es "NJ". El código también almacena la distancia calculada en el campo distance de los documentos de salida.

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

Distancia mínima

El siguiente ejemplo devuelve los primeros 4 documentos coincidentes fuera de un radio de 8000 metros del punto especificado, en orden ascendente de distancia. El código incluye un parámetro Query que solo coincide con documentos en los que el valor del campo location.address.state es "NJ". El código también almacena la distancia calculada en el campo distance de los documentos de salida.

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);

Los ejemplos de Node.js en esta página utilizan la base de datos sample_mflix de los conjuntos de datos de muestra de Atlas. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulte Primeros pasos en la documentación del controlador de MongoDB Node.js.

Para utilizar el controlador de MongoDB Node.js para agregar una etapa de $geoNear a una canalización de agregación, utilice el Operador $geoNear en un objeto de canalización.

Distancia máxima

El siguiente ejemplo crea una etapa de pipeline que devuelve documentos en un radio de 8000 metros del punto especificado, en orden de distancia ascendente. El código incluye un campo query que solo coincide con los documentos donde el valor del campo location.address.state es "NJ". El código también almacena la distancia calculada en el campo distance de los documentos de salida. El ejemplo ejecuta entonces el pipeline de agregación:

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;

Distancia mínima

El siguiente ejemplo devuelve los primeros 4 documentos coincidentes fuera de un radio de 8000 metros del punto especificado, en orden de distancia ascendente. El código incluye un campo query que solo coincide con los documentos donde el valor del campo location.address.state es "NJ". El código también almacena la distancia calculada en el campo distance de los documentos de salida:

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;

Obtén más información

Para aprender más sobre las etapas relacionadas del pipeline, consulta la guía $limit.

Volver

$fill

$graphLookup

Definición

Nota

Comportamiento

Cálculos de distancia

Considerations

Ejemplos

Distancia máxima

Nota

Distancia mínima

Nota

$geoNear con la opción let

$geoNear con opción Bound let

Especifique qué índice geoespacial utilizar

Nota

Distancia máxima

Distancia mínima

Distancia máxima

Distancia mínima

Obtén más información

$geoNear con la opción `let`

$geoNear con opción Bound `let`