- Indexes >
- Index Concepts >
- Index Types >
- Geospatial Indexes and Queries >
2dsphere
Indexes
2dsphere
Indexes¶
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. See the
Geospatial Query Operators for the query operators
that support geospatial queries.
The 2dsphere
index supports data stored as GeoJSON objects and as legacy coordinate pairs (See also
2dsphere Indexed Field Restrictions). For legacy coordinate pairs, the
index converts the data to GeoJSON Point. For details on
the supported GeoJSON objects, see GeoJSON Objects.
The default datum for an earth-like sphere is WGS84. Coordinate-axis order is longitude, latitude.
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
and later series. To override the default version 2 and create a
version 1 index, include the option { "2dsphereIndexVersion": 1 }
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 and maintain 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.ensureIndex()
method, specifying the location
field as the key and specify the string literal "2dsphere"
as the
index type:
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 more information on creating 2dspshere
indexes, see
Create a 2dsphere Index.