Overview
En esta guía, puede aprender cómo buscar datos geoespaciales con el controlador Java de MongoDB y los diferentes formatos de datos geoespaciales compatibles con MongoDB.
Los datos geoespaciales son datos que representan una ubicación geográfica en la superficie terrestre. Algunos ejemplos de datos geoespaciales incluyen:
Ubicaciones de cines
Fronteras de los países
Rutas de paseos en bicicleta
Áreas de ejercicio para perros en la ciudad de Nueva York
Coordenadas en la Tierra
Para almacenar y consultar sus datos geoespaciales en MongoDB, utilice GeoJSON. GeoJSON es un formato de datos creado por el Grupo de Trabajo de Ingeniería de Internet (IETF).
Aquí está la ubicación de la sede de MongoDB en GeoJSON:
"MongoDB Headquarters" : { "type": "point", "coordinates": [-73.986805, 40.7620853] }
Para obtener información definitiva sobre GeoJSON, consulte especificación oficial del IETF.
Posiciones GeoJSON
Una posición representa un solo lugar en la Tierra y existe en el código como una matriz que contiene dos o tres valores numéricos:
Longitud en la primera posición (obligatorio)
Latitud en la segunda posición (obligatorio)
Elevación en la tercera posición (opcional)
Importante
Longitud luego latitud
GeoJSON ordena las coordenadas como longitud primero y latitud después. Esto puede resultar sorprendente, ya que las convenciones de los sistemas de coordenadas geográficas generalmente indican la latitud primero y la longitud después. Asegúrate de verificar el formato que usan otras herramientas con las que trabajas. Herramientas populares como OpenStreetMap y Google Maps indican las coordenadas como latitud primero y longitud después.
Tipos GeoJSON
El tipo de un objeto GeoJSON determina su forma geométrica. Las formas geométricas se componen de posiciones.
A continuación se muestran algunos tipos GeoJSON comunes y cómo puedes especificarlos con posiciones:
Point: una sola posición. Esto puede representar la ubicación de una escultura.LineStringUna matriz de dos o más posiciones, formando así una serie de segmentos de línea. Esto puede representar la ruta de la Gran Muralla China.Polygon: una serie de posiciones donde la primera y la última coinciden, delimitando así un espacio. Esto puede representar el territorio dentro de la Ciudad del Vaticano.
Para obtener más información sobre las formas que puede utilizar en MongoDB, consulte la entrada del manual GeoJSON.
Insertar un documento que contenga datos GeoJSON
Para insertar un documento que almacene datos GeoJSON, cree un documento que contenga un valor GeoJSON y pase el documento al método insertOne().
El siguiente ejemplo inserta un documento que incluye un campo location.geo, que contiene datos GeoJSON:
// Add your MongoCollection setup code here Point point = new Point(new Position(-74.0065, 40.7085)); Document theater = new Document("theaterId", 1203) .append("location", new Document("geo", point)); InsertOneResult result = collection.insertOne(theater);
Para obtener más información sobre cómo insertar documentos, consulte la Insertar guía de operaciones.
Index
Para consultar datos almacenados en formato GeoJSON, agregue el campo que contiene datos GeoJSON a un índice 2dsphere. El siguiente fragmento crea un índice 2dsphere en el campo location.geo mediante el constructor Indexes:
// <MongoCollection setup code here> collection.createIndex(Indexes.geo2dsphere("location.geo"));
Para obtener más información sobre el Indexes generador, consulte nuestra guía sobre el generador de índices.
Coordenadas en un plano 2D
Puede almacenar datos geoespaciales utilizando las coordenadas x y y en un plano euclidiano bidimensional. Nos referimos a las coordenadas en un plano bidimensional como "pares de coordenadas heredadas".
Los pares de coordenadas heredados tienen la siguiente estructura:
"<field name>" : [ x, y ]
Su campo debe contener una matriz de dos valores en la que el primero representa el valor del eje x y el segundo representa el valor del eje y.
Insertar un documento que contenga coordenadas heredadas
Para insertar un documento que almacene un par de coordenadas heredado, cree un documento que asigne un valor de par de coordenadas a un campo. Luego, pase el documento al método insertOne().
El siguiente ejemplo inserta un documento que incluye un campo coordinates, que contiene un par de coordenadas heredado:
// Add your MongoCollection setup code here Document theater = new Document("theaterId", 1204) .append("coordinates", Arrays.asList(-73.9862, 40.7311)); InsertOneResult result = collection.insertOne(theater);
Para obtener más información sobre cómo insertar documentos, consulte la guía Operaciones de inserción.
Index
Para consultar datos almacenados como pares de coordenadas heredados, debe agregar el campo que contiene los pares de coordenadas heredados a un índice 2d. El siguiente fragmento crea un índice 2d en el campo coordinates mediante el constructor Indexes:
// <MongoCollection setup code here> collection.createIndex(Indexes.geo2d("coordinates"));
Para obtener más información sobre el Indexes generador, consulte nuestra guía sobre el generador de índices.
Para obtener más información sobre los pares de coordenadas heredados, consulte la página del manual de MongoDB Server sobre pares de coordenadas heredados.
Tip
Operadores compatibles
Los índices esféricos () y planos2dsphere2d () admiten algunos, pero no todos, los mismos operadores de consulta. Para obtener una lista completa de operadores y su compatibilidad con índices, consulte la entrada del manual sobre consultas geoespaciales.
Query geoespacial
Las consultas geoespaciales constan de un operador de consulta y formas GeoJSON como parámetros de consulta.
Operadores del query
Para consultar sus datos geoespaciales, utilice uno de los siguientes operadores de consulta:
$near$geoWithin$nearSphere$geoIntersectsrequiere un índice 2dsphere
Puede especificar estos operadores de consulta en el controlador Java de MongoDB con los métodos de utilidad near(), geoWithin(), nearSphere() y geoIntersects() de la clase de generador Filters.
Para obtener más información sobre los operadores de consultas geoespaciales, consulte la entrada manual para consultas geoespaciales.
Para obtener más información sobre,Filters consulte nuestra guía sobre el generador de filtros.
Parámetros de consulta
Para especificar una forma para usar en una consulta geoespacial, utilice las clases Position, Point, LineString y Polygon del controlador Java de MongoDB.
Para obtener una lista completa de las formas GeoJSON disponibles en el driver de Java de MongoDB, consulta la paquete de GeoJSON Documentación de API.
Ejemplos
Los siguientes ejemplos utilizan el conjunto de datos de ejemplo de MongoDB Atlas. Puede aprender a configurar su propio clúster de Atlas gratuito y a cargar el conjunto de datos de ejemplo en nuestra guía de inicio rápido.
Los ejemplos utilizan la colección theaters de la base de datos sample_mflix del conjunto de datos de muestra. La colección theaters contiene un índice 2dsphere en el campo location.geo.
Los ejemplos requieren las siguientes importaciones:
import java.util.Arrays; import org.bson.conversions.Bson; import com.mongodb.client.model.geojson.Point; import com.mongodb.client.model.geojson.Polygon; import com.mongodb.client.model.geojson.Position; import static com.mongodb.client.model.Filters.near; import static com.mongodb.client.model.Filters.geoWithin; import static com.mongodb.client.model.Projections.fields; import static com.mongodb.client.model.Projections.include; import static com.mongodb.client.model.Projections.excludeId;
Puede encontrar el código fuente de los ejemplos en Github aquí.
Consulta por proximidad
Para buscar y devolver documentos desde el punto más cercano al más lejano, utilice el método de utilidad estática near() de la clase constructora Filters. El método near() construye una consulta con el operador de consulta $near.
El siguiente ejemplo busca teatros que se encuentren entre 10,000 y 5,000 metros del Gran Césped de Central Park.
// Add your MongoClient setup code here MongoDatabase database = mongoClient.getDatabase("sample_mflix"); MongoCollection<Document> collection = database.getCollection("theaters"); Point centralPark = new Point(new Position(-73.9667, 40.78)); // Creates a query that matches all locations between 5,000 and 10,000 meters from the specified Point Bson query = near("location.geo", centralPark, 10000.0, 5000.0); // Creates a projection to include only the "location.address.city" field in the results Bson projection = fields(include("location.address.city"), excludeId()); // Prints the projected field of the results from the geospatial query as JSON collection.find(query) .projection(projection) .forEach(doc -> System.out.println(doc.toJson()));
La salida del código anterior se parece a la siguiente:
{"location": {"address": {"city": "Bronx"}}} {"location": {"address": {"city": "New York"}}} {"location": {"address": {"city": "New York"}}} {"location": {"address": {"city": "Long Island City"}}} {"location": {"address": {"city": "New York"}}} {"location": {"address": {"city": "Secaucus"}}} {"location": {"address": {"city": "Jersey City"}}} {"location": {"address": {"city": "Elmhurst"}}} {"location": {"address": {"city": "Flushing"}}} {"location": {"address": {"city": "Flushing"}}} {"location": {"address": {"city": "Flushing"}}} {"location": {"address": {"city": "Elmhurst"}}}
Tip
Dato curioso
MongoDB usa el mismo sistema de referencias que los satélites GPS para calcular geometrías sobre la Tierra.
Para obtener más información sobre el $near operador,consulte la documentación de referencia de $near.
Para obtener más información sobre,Filters consulte nuestra guía sobre el generador de filtros.
Consulta dentro de un rango
Para buscar datos geoespaciales dentro de una forma específica, utilice el método de utilidad estática geoWithin() de la clase constructora Filters. El método geoWithin() construye una consulta con el operador de consulta $geoWithin.
The following example searches for movie theaters in a section of Long Island.
// Add your MongoCollection setup code here // Creates a set of points that defines the bounds of a geospatial shape Polygon longIslandTriangle = new Polygon(Arrays.asList(new Position(-72, 40), new Position(-74, 41), new Position(-72, 39), new Position(-72, 40))); // Creates a projection to include only the "location.address.city" field in the results Bson projection = fields(include("location.address.city"), excludeId()); // Creates a query that matches documents containing "location.geo" values within the specified bounds Bson geoWithinComparison = geoWithin("location.geo", longIslandTriangle); // Prints the projected field of the results from the geolocation query as JSON collection.find(geoWithinComparison) .projection(projection) .forEach(doc -> System.out.println(doc.toJson()));
La salida del código anterior se parece a la siguiente:
{"location": {"address": {"city": "Baldwin"}}} {"location": {"address": {"city": "Levittown"}}} {"location": {"address": {"city": "Westbury"}}} {"location": {"address": {"city": "Mount Vernon"}}} {"location": {"address": {"city": "Massapequa"}}}
La siguiente figura muestra el polígono definido por la variable longIslandTriangle y los puntos que representan las ubicaciones de las salas de cine devueltas por nuestra consulta.
Para obtener más información sobre el $geoWithin operador, consulte la documentación de referencia de $geoWithin
Para obtener más información sobre los operadores que puede utilizar en su consulta, consulte la página del manual de MongoDB Server sobre operadores de consulta geoespacial.