OPTIONS

2dsphere Indexes

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.

2dsphere Version 2

Changed in version 2.6.

MongoDB 2.6 introduces a version 2 of 2dsphere indexes. Version 2 is the default version of 2dsphere indexes created in MongoDB 2.6. To create a 2dsphere index as a version 1, include the option { "2dsphereIndexVersion": 1 } when creating the index.

Version 2 adds support for additional GeoJSON object: MultiPoint, MultiLineString, MultiLineString, MultiPolygon, and GeometryCollection.

Version 2 2dsphere indexes are sparse by default and ignores the sparse: true option. If a document lacks a 2dsphere index field (or the field is a null or an empty array), MongoDB does not add an entry for the document to the 2dsphere index. For inserts, MongoDB inserts the document but does not add to the 2dsphere index.

Version 1 2dsphere indexes are not sparse by default and will reject documents with null location fields.

Considerations

MongoDB allows only one geospatial index per collection. You can create either a 2dsphere or a 2d per collection.

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

MongoDB supports the following GeoJSON objects:

The MultiPoint, MultiLineString, MultiLineString, MultiPolygon, and GeometryCollection require 2dsphere index version 2.

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 in longitude, latitude order.

Use the following syntax:

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

Point

New in version 2.4.

The following example stores a GeoJSON Point:

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

LineString

New in version 2.4.

The following example stores a GeoJSON LineString:

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

Polygon

New in version 2.4.

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:

{ 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:

{ 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.

Diagram of a Polygon with internal ring.

MultiPoint

New in version 2.6: Requires 2dsphere index version 2.

The following example stores coordinates of GeoJSON type MultiPoint:

{ loc: { "type": "MultiPoint",
         "coordinates": [ [ -73.9580, 40.8003 ],
                          [ -73.9498, 40.7968 ],
                          [ -73.9737, 40.7648 ],
                          [ -73.9814, 40.7681 ] ] } }

MultiLineString

New in version 2.6: Requires 2dsphere index version 2.

The following example stores coordinates of GeoJSON type MultiLineString:

{ loc: { "type": "MultiLineString",
         "coordinates": [ [ [ -73.96943, 40.78519 ], [ -73.96082, 40.78095 ] ],
                          [ [ -73.96415, 40.79229 ], [ -73.95544, 40.78854 ] ],
                          [ [ -73.97162, 40.78205 ], [ -73.96374, 40.77715 ] ],
                          [ [ -73.97880, 40.77247 ], [ -73.97036, 40.76811 ] ] ] } }

MultiPolygon

New in version 2.6: Requires 2dsphere index version 2.

The following example stores coordinates of GeoJSON type MultiPolygon:

{ loc: { "type": "MultiPolygon",
         "coordinates": [ [ [ [  -73.958, 40.8003 ], [ -73.9498, 40.7968 ], [ -73.9737, 40.7648 ], [ -73.9814, 40.7681 ], [  -73.958, 40.8003 ] ] ],
                          [ [ [  -73.958, 40.8003 ], [ -73.9498, 40.7968 ], [ -73.9737, 40.7648 ], [  -73.958, 40.8003 ] ] ] ] } }

GeometryCollection

New in version 2.6: Requires 2dsphere index version 2.

The following example stores coordinates of GeoJSON type GeometryCollection:

{ loc: { "type": "GeometryCollection",
         "geometries": [ { "type": "MultiPoint",
                                   "coordinates": [ [ -73.9580, 40.8003 ],
                                                    [ -73.9498, 40.7968 ],
                                                    [ -73.9737, 40.7648 ],
                                                    [ -73.9814, 40.7681 ] ] },
                         { "type": "MultiLineString",
                                   "coordinates": [ [ [ -73.96943, 40.78519 ], [ -73.96082, 40.78095 ] ],
                                                    [ [ -73.96415, 40.79229 ], [ -73.95544, 40.78854 ] ],
                                                    [ [ -73.97162, 40.78205 ], [ -73.96374, 40.77715 ] ],
                                                    [ [ -73.97880, 40.77247 ], [ -73.97036, 40.76811 ] ] ] } ] } }