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 default datum for an earth-like sphere in MongoDB 2.4 is WGS84. Coordinate-axis order is longitude, latitude.

The 2dsphere index supports all MongoDB geospatial queries: queries for inclusion, intersection and proximity. See the Geospatial Query Operators for the query operators that support geospatial queries.

To create a 2dsphere index, use the db.collection.ensureIndex method. A compound 2dsphere index can reference multiple location and non-location fields within a collection’s documents. See Create a 2dsphere Index for more information.

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.

Additional GeoJSON Objects

Changed in version 2.6.

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

sparse Property

Changed in version 2.6.

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

For a compound index that includes a 2dsphere index key along with keys of other types, only the 2dsphere index field determines whether the index references a document.

Earlier versions of MongoDB only support Version 1 2dsphere indexes. Version 1 2dsphere indexes are not sparse by default and will reject documents with null location fields.

Considerations

geoNear and $geoNear Restrictions

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

Shard Key Restrictions

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, 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 line that joins two points on a curved surface may or may not contain the same set of co-ordinates that joins those two points on a flat surface. The line that joins two points on a curved surface will be a geodesic. Carefully check points to avoid errors with shared edges, as well as overlaps and other types of intersections.

Polygons with a Single Ring

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 a single ring, the ring cannot self-intersect.

Polygons with Multiple Rings

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 cannot 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 ] ]
            ]
         }
      ]
    }
}