Docs Menu
Docs Home
/ / /
Rust Driver
/

Search Geospatially

On this page

  • Overview
  • Store Geospatial Data
  • GeoJSON
  • Legacy Coordinate Pairs
  • Geospatial Indexes
  • 2dsphere
  • 2d
  • Geospatial Queries
  • Query Operators
  • Query by Proximity Example
  • Query Within a Range Example
  • Additional Information
  • API Documentation

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

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

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.

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.

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 following Point 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. A LineString can represent a path, route, border, or any other linear geospatial data. For example, the following LineString 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 following Polygon 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.

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.

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 data

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

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, None).await?;
println!("Created index:\n{}", idx.index_name);

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, None).await?;
println!("Created index:\n{}", idx.index_name);

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.

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.

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, None).await?;
while let Some(doc) = cursor.try_next().await? {
println!("{}", doc);
}

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, None).await?;
while let Some(doc) = cursor.try_next().await? {
println!("{}", doc);
}

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:

To learn more about the methods and types mentioned in this guide, see the following API documentation:

← Collations
GridFS →