Navigation
This version of the documentation is archived and no longer supported.

Geospatial Indexes and Queries

MongoDB offers a number of indexes and query mechanisms to handle geospatial information. This section introduces MongoDB’s geospatial features. For complete examples of geospatial queries in MongoDB, see Geospatial Index Tutorials.

Surfaces

Before storing your location data and writing queries, you must decide the type of surface to use to perform calculations. The type you choose affects how you store data, what type of index to build, and the syntax of your queries.

MongoDB offers two surface types:

Spherical

To calculate geometry over an Earth-like sphere, store your location data on a spherical surface and use 2dsphere index.

Store your location data as GeoJSON objects with this coordinate-axis order: longitude, latitude. The coordinate reference system for GeoJSON uses the WGS84 datum.

Flat

To calculate distances on a Euclidean plane, store your location data as legacy coordinate pairs and use a 2d index.

Location Data

If you choose spherical surface calculations, you store location data as either:

GeoJSON Objects

Queries on GeoJSON objects always calculate on a sphere. The default coordinate reference system for GeoJSON uses the WGS84 datum.

New in version 2.4: Support for GeoJSON storage and queries is new in version 2.4. Prior to version 2.4, all geospatial data used coordinate pairs.

Changed in version 2.6: Support for additional GeoJSON types: MultiPoint, MultiLineString, MultiPolygon, GeometryCollection.

MongoDB supports the following GeoJSON objects:

  • Point
  • LineString
  • Polygon
  • MultiPoint
  • MultiLineString
  • MultiPolygon
  • GeometryCollection

Legacy Coordinate Pairs

MongoDB supports spherical surface calculations on legacy coordinate pairs using a 2dsphere index by converting the data to the GeoJSON Point type.

If you choose flat surface calculations via a 2d index, you can store data only as legacy coordinate pairs.

Query Operations

MongoDB’s geospatial query operators let you query for:

Inclusion

MongoDB can query for locations contained entirely within a specified polygon. Inclusion queries use the $geoWithin operator.

Both 2d and 2dsphere indexes can support inclusion queries. MongoDB does not require an index for inclusion queries; however, such indexes will improve query performance.

Intersection

MongoDB can query for locations that intersect with a specified geometry. These queries apply only to data on a spherical surface. These queries use the $geoIntersects operator.

Only 2dsphere indexes support intersection.

Proximity

MongoDB can query for the points nearest to another point. Proximity queries use the $near operator. The $near operator requires a 2d or 2dsphere index.

Geospatial Indexes

MongoDB provides the following geospatial index types to support the geospatial queries.

2dsphere

2dsphere indexes support:

  • Calculations on a sphere
  • GeoJSON objects and include backwards compatibility for legacy coordinate pairs
  • Compound indexes with scalar index fields (i.e. ascending or descending) as a prefix or suffix of the 2dsphere index field

New in version 2.4: 2dsphere indexes are not available before version 2.4.

2d

2d indexes support:

  • Calculations using flat geometry
  • Legacy coordinate pairs (i.e., geospatial points on a flat coordinate system)
  • Compound indexes with only one additional field, as a suffix of the 2d index field

See also

Query a 2d Index

Geospatial Indexes and Sharding

You cannot use a geospatial index as the shard key index.

You can create and maintain a geospatial index on a sharded collection if it uses fields other than the shard key fields.

For sharded collections, queries using $near and $nearSphere are not supported. You can instead use either the geoNear command or the $geoNear aggregation stage.

You can also query for geospatial data using $geoWithin.

Additional Resources

The following pages provide complete documentation for geospatial indexes and queries:

2dsphere Indexes
A 2dsphere index supports queries that calculate geometries on an earth-like sphere. The index supports data stored as both GeoJSON objects and as legacy coordinate pairs.
2d Indexes
The 2d index supports data stored as legacy coordinate pairs and is intended for use in MongoDB 2.2 and earlier.
geoHaystack Indexes
A haystack index is a special index optimized to return results over small areas. For queries that use spherical geometry, a 2dsphere index is a better option than a haystack index.
2d Index Internals
Provides a more in-depth explanation of the internals of geospatial indexes. This material is not necessary for normal operations but may be useful for troubleshooting and for further understanding.