- Indexes >
2dsphereIndexes
2dsphere Indexes¶
On this page
New in version 2.4.
Overview¶
A 2dsphere index supports queries that calculate geometries on an
earth-like sphere. 2dsphere index supports all MongoDB geospatial
queries: queries for inclusion, intersection and proximity.
For more information on geospatial queries, see
Geospatial Queries.
The 2dsphere index supports data stored as GeoJSON objects and legacy coordinate pairs (See also 2dsphere Indexed Field Restrictions).
For legacy coordinate pairs, the index converts the data to GeoJSON
Point.
Versions¶
Changed in version 3.2: MongoDB 3.2 introduces a version 3 of 2dsphere indexes. Version
3 is the default version of 2dsphere indexes created in MongoDB
3.2 and later.
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 and 3.0 series.
To override the default version and specify a different version,
include the option { "2dsphereIndexVersion": <version> } when
creating the index.
sparse Property¶
Changed in version 2.6.
2dsphere (Version 2) 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 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 2dsphere (Version 1)
indexes. 2dsphere (Version 1) indexes are not sparse by default
and will reject documents with null location fields.
Additional GeoJSON Objects¶
2dsphere (Version 2) includes support for additional GeoJSON
object: MultiPoint, MultiLineString,
MultiPolygon, and GeometryCollection. For
details on all supported GeoJSON objects, see GeoJSON Objects.
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
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.
Shard Key Restrictions¶
You cannot use a 2dsphere index as a shard key when sharding a
collection. However, you can create a geospatial index
on a sharded collection by using a different field as the shard key.
2dsphere Indexed Field Restrictions¶
Fields with 2dsphere indexes must hold geometry
data in the form of coordinate pairs
or GeoJSON data. If you attempt to insert a document with
non-geometry data in a 2dsphere indexed field, or build a
2dsphere index on a collection where the indexed field has
non-geometry data, the operation will fail.
Create a 2dsphere Index¶
To create a 2dsphere index, use the
db.collection.createIndex() method and specify the string
literal "2dsphere" as the index type:
db.collection.createIndex( { <location field> : "2dsphere" } )
where the <location field> is a field whose value is either a
GeoJSON object or a legacy
coordinates pair.
Unlike a compound 2d index which can reference one
location field and one other field, a compound 2dsphere index can reference multiple
location and non-location fields.
For the following examples, consider a collection places with
documents that store location data as GeoJSON Point in a field named loc:
db.places.insert(
{
loc : { type: "Point", coordinates: [ -73.97, 40.77 ] },
name: "Central Park",
category : "Parks"
}
)
db.places.insert(
{
loc : { type: "Point", coordinates: [ -73.88, 40.78 ] },
name: "La Guardia Airport",
category : "Airport"
}
)
Create a 2dsphere Index¶
The following operation creates a 2dsphere
index on the location field loc:
db.places.createIndex( { loc : "2dsphere" } )
Create a Compound Index with 2dsphere Index Key¶
A compound index can include a
2dsphere index key in combination with non-geospatial index keys.
For example, the following operation creates a compound index where
the first key loc is a 2dsphere index key, and the remaining
keys category and names are non-geospatial index keys,
specifically descending (-1) and ascending (1) keys
respectively.
db.places.createIndex( { loc : "2dsphere" , category : -1, name: 1 } )
Unlike the 2d index, a compound 2dsphere index
does not require the location field to be the first field indexed. For
example:
db.places.createIndex( { category : 1 , loc : "2dsphere" } )