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

2dsphere Indexes

On this page

New in version 2.4.

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. The index supports legacy coordinate pairs by converting the data to the GeoJSON Point type.

The 2dsphere index supports all MongoDB geospatial queries: queries for inclusion, intersection and proximity.

A compound 2dsphere index can reference multiple location and non-location fields within a collection’s documents. You can arrange the fields in any order.

The default datum for an earth-like sphere in MongoDB 2.4 is WGS84. Coordinate-axis order is longitude, latitude.

See the Geospatial Query Operators for the query operators that support geospatial queries.

Considerations

The geoNear command and the $geoNear pipeline stage require that a collection have at most only one 2dsphere index and/or only one 2d index whereas geospatial query operators (e.g. $near and $geoWithin) permit collections to have multiple geospatial indexes.

The geospatial index restriction for the geoNear command and the $geoNear pipeline stage exists because neither the geoNear command nor the $geoNear pipeline stage syntax includes the location field. As such, index selection among multiple 2d indexes or 2dsphere indexes is ambiguous.

No such restriction applies for geospatial query operators since these operators take a location field, eliminating the ambiguity.

You cannot use a 2dsphere index as a shard key when sharding a collection. However, you can create and maintain a geospatial index on a sharded collection by using a different field as the shard key.

GeoJSON Objects

New in version 2.4.

MongoDB supports the following GeoJSON objects:

In order to index GeoJSON data, you must store the data in a location field that you name. The location field contains a subdocument with a type field specifying the GeoJSON object type and a coordinates field specifying the object’s coordinates. Always store coordinates longitude, latitude order.

Use the following syntax:

copy 
{ <location field> : { type : "<GeoJSON type>" ,
                       coordinates : <coordinates>
} }

The following example stores a GeoJSON Point:

copy 
{ loc : { type : "Point" ,
          coordinates : [ 40, 5 ]
} }

The following example stores a GeoJSON LineString:

copy 
{ loc : { type : "LineString" ,
          coordinates : [ [ 40 , 5 ] , [ 41 , 6 ] ]
} }

Polygons consist of an array of GeoJSON LinearRing coordinate arrays. These LinearRings are closed LineStrings. Closed LineStrings have at least four coordinate pairs and specify the same position as the first and last coordinates.

The following example stores a GeoJSON Polygon with an exterior ring and no interior rings (or holes). Note the first and last coordinate pair with the [ 0 , 0 ] coordinate:

copy 
{ loc :
   { type : "Polygon" ,
     coordinates : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ]
} }

For Polygons with multiple rings:

  • The first described ring must be the exterior ring.
  • The exterior ring cannot self-intersect.
  • Any interior ring must be entirely contained by the outer ring.
  • Interior rings cannot intersect or overlap each other. Interior rings can share an edge.

The following document represents a polygon with an interior ring as GeoJSON:

copy 
{ loc :
   { type : "Polygon" ,
     coordinates : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ],
                     [ [ 2 , 2 ] , [ 3 , 3 ] , [ 4 , 2 ] , [ 2 , 2 ] ] ]
} }
Diagram of a Polygon with internal ring.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.