Search Geospatially
On this page
Overview
In this guide, you can learn how to search geospatial data by using the Rust driver. Geospatial data represents a geographic location on the surface of the Earth or on a Euclidean plane.
Examples of geospatial data include:
Locations of movie theaters
Borders of countries
Routes of bicycle rides
Dog exercise areas in New York City
Points on a graph
This guide includes the following sections:
Store Geospatial Data describes the data formats you can use to represent geospatial data
Geospatial Indexes describes how to create an index on fields storing geospatial data
Geospatial Queries describes how to query geospatial data stored in indexed fields
Additional Information provides links to resources and API documentation for types and methods mentioned in this guide
Store Geospatial Data
All geospatial data in MongoDB is stored in one of the following formats:
GeoJSON, a format that represents geospatial data on an Earth-like sphere
Legacy Coordinate Pair, a format that represents geospatial data on a Euclidean plane
GeoJSON
Use GeoJSON to store data that represents geospatial information on an Earth-like sphere. GeoJSON is composed of one or more positions and a type.
Positions
A position represents a single place on Earth and exists in code as an array containing the following values:
Longitude in the first position
Latitude in the second position
The following code represents the position of the MongoDB Headquarters in New York City, NY:
let coords = vec! [-73.986805, 40.7620853];
Important
Longitude then Latitude
GeoJSON orders coordinates as longitude first and latitude second. This conflicts with geographic coordinate system conventions, which generally list latitude first and longitude second. Ensure that you reformat your coordinates to align with GeoJSON standards.
Types
Your GeoJSON object's type determines the geometric shape it represents. Geometric shapes are made up of positions.
The following list describes common GeoJSON types and how to specify them with positions:
Point
: a single position. For example, the followingPoint
represents the location of the MongoDB Headquarters:let point = doc! {"name": "MongoDB HQ", "location": doc! { "type": "Point", "coordinates": vec! [-73.986805, 40.7620853], } }; LineString
: an array of two or more positions that forms a series of line segments. ALineString
can represent a path, route, border, or any other linear geospatial data. For example, the followingLineString
represents a segment of the Great Wall of China:let line = doc! {"name": "Great Wall of China", "location": doc! { "type": "LineString", "coordinates": vec! [ vec! [116.572, 40.430], vec! [116.570, 40.434], vec! [116.567, 40.436], vec! [116.566, 40.441] ], } }; Polygon
: an array of positions in which the first and last position are the same and enclose some space. For example, the followingPolygon
represents the land within Vatican City:let polygon = doc! {"name": "Vatican City", "location": doc! { "type": "Polygon", "coordinates": vec![ vec! [ vec! [12.458, 41.906], vec! [12.458, 41.901], vec! [12.450, 41.901], vec! [12.450, 41.906], vec! [12.458, 41.906], ] ], } };
To learn more about the GeoJSON types that you can use in MongoDB, see the GeoJSON page in the Server manual.
Legacy Coordinate Pairs
Use legacy coordinate pairs to represent geospatial data on a two-dimensional Euclidean plane.
The following code specifies a legacy coordinate pair that represents the location of Washington, D.C.:
let capital = vec! [-77.0369, 38.9072];
To learn more about legacy coordinate pairs, see Legacy Coordinate Pairs in the Server manual.
Geospatial Indexes
Before querying geospatial data, you must create an index that corresponds to the data format. The following index types enable geospatial queries:
2dsphere
for GeoJSON data2d
for legacy coordinate pairs
The following sections on 2dsphere
and 2d
indexes include code examples
that use the theaters
collection in the sample_mflix
database from the
Atlas sample data.
Tip
To learn more about creating an index, see the Indexes guide.
For instructions on importing the Atlas sample data, see the Load Sample Data page.
2dsphere
To query data stored in the GeoJSON format, add the field containing
both the type
and coordinates
fields to a 2dsphere
index. The
following example creates a 2dsphere
index on the location.geo
field:
let index = IndexModel::builder() .keys(doc! { "location.geo": "2dsphere" }) .build(); let idx = my_coll.create_index(index).await?; println!("Created index:\n{}", idx.index_name);
2d
To query data stored as legacy coordinate pairs, add the field containing
legacy coordinate pairs to a 2d
index. The following example creates a
2d
index on the location.geo.coordinates
field:
let index = IndexModel::builder() .keys(doc! { "location.geo.coordinates": "2d" }) .build(); let idx = my_coll.create_index(index).await?; println!("Created index:\n{}", idx.index_name);
Geospatial Queries
After creating a 2dsphere
or 2d
index on fields containing geospatial data, you
can perform geospatial queries that access those fields.
To query geospatial data, create a query filter with a field name and a geospatial query operator. You can specify options for certain geospatial query operators to limit the documents returned.
The following sections on geospatial queries include code examples that use the theaters
collection in the sample_mflix
database from the Atlas sample data. Assume that
the theaters
collection has a 2dsphere
index on the location.geo
field.
Tip
To learn more about querying data, see the Specify a Query guide.
For instructions on importing the Atlas sample data, see the Load Sample Data page.
Query Operators
To query your geospatial data, use one of the following query operators:
$near
$geoWithin
$nearSphere
$geoIntersects
(requires a 2dsphere index)
When using the $near
operator, you can specify the following distance operators:
$minDistance
$maxDistance
When using the $geoWithin
operator, you can specify the following shape operators:
$box
$polygon
$center
$centerSphere
Tip
To learn more about geospatial query operators, see Geospatial Query Operators in the Server manual.
Query by Proximity Example
The following example queries for documents in which the location.geo
field
stores a location within 1000 meters of the MongoDB Headquarters in New York City, NY.
The code returns documents in ascending order of their distance from the MongoDB Headquarters.
let mongodb = vec! [-73.986805, 40.7620853]; let query = doc! {"location.geo": doc! { "$near": { "$geometry": { "type": "Point", "coordinates": mongodb, }, "$maxDistance": 1000, } } }; let mut cursor = my_coll.find(query).await?; while let Some(doc) = cursor.try_next().await? { println!("{}", doc); }
Query Within a Range Example
The following example queries for documents in which the location.geo
field
stores a location within the Chicago area. The example creates a vector called chicago
that stores four coordinates representing the bounds of the geographic search area.
let chicago = doc! { "type": "Polygon", "coordinates": vec![ vec![ vec![-87.851, 41.976], vec![-87.851, 41.653], vec![-87.651, 41.653], vec![-87.651, 41.976], vec![-87.851, 41.976], ] ] }; let query = doc! {"location.geo": doc! { "$geoWithin": { "$geometry": chicago }} }; let mut cursor = my_coll.find(query).await?; while let Some(doc) = cursor.try_next().await? { println!("{}", doc); }
Additional Information
To learn more about find operations, see the Retrieve Data guide.
To learn more about working with geospatial data, see the following Server manual pages:
API Documentation
To learn more about the methods and types mentioned in this guide, see the following API documentation: