2dsphere Indexes

Overview

A 2dsphere index supports queries that calculate geometries on anearth-like sphere. 2dsphere index supports all MongoDB geospatialqueries: queries for inclusion, intersection and proximity.For more information on geospatial queries, seeGeospatial Queries.

The 2dsphere index supports data stored as GeoJSON objectsandlegacy coordinate pairs (See also 2dsphere Indexed Field Restrictions).For legacy coordinate pairs, the index converts the data to GeoJSONPoint.

Versions

To override the default version and specify a different version,include the option { "2dsphereIndexVersion": <version> } whencreating the index.

sparse Property

Version 2 and later 2dsphere indexes are always sparse and ignore the sparse option. If a document lacks a 2dsphere indexfield (or the field is null or an empty array), MongoDB does notadd an entry for the document to the index. For inserts, MongoDBinserts the document but does not add to the 2dsphere index.

For a compound index that includes a 2dsphere index key along withkeys of other types, only the 2dsphere index field determineswhether the index references a document.

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

Additional GeoJSON Objects

Version 2 and later 2dsphere indexes includes support for additional GeoJSONobject: MultiPoint, MultiLineString,MultiPolygon, and GeometryCollection. Fordetails on all supported GeoJSON objects, see GeoJSON Objects.

Considerations

geoNear and $geoNear Restrictions

Starting in MongoDB 4.0, you can specify a key option to the$geoNear pipeline stage to indicate the indexed field pathto use. This allows the $geoNear stage to be used on acollection that has multiple 2dsphere index and/or multiple2d index:

• If your collection has multiple 2dsphere index and/or multiple2d index, you must use the key option to specify theindexed field path to use.
• If you do not specify the key, you cannot have multiple2dsphere index and/or multiple 2d index since withoutthe key, index selection among multiple 2d indexes or2dsphere indexes is ambiguous.

Note

If you do not specify the key, and you have at most only one2dsphere index index and/or only one 2dsphere index index,MongoDB looks first for a 2d index to use. If a 2d indexdoes not exists, then MongoDB looks for a 2dsphere index to use.

Shard Key Restrictions

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

2dsphere Indexed Field Restrictions

Fields with 2dsphere indexes must hold geometrydata in the form of coordinate pairsor GeoJSON data. If you attempt to insert a document withnon-geometry data in a 2dsphere indexed field, or build a2dsphere index on a collection where the indexed field hasnon-geometry data, the operation will fail.

Create a 2dsphere Index

To create a 2dsphere index, use thedb.collection.createIndex() method and specify the stringliteral "2dsphere" as the index type:

db.collection.createIndex( { <location field> : "2dsphere" } )

where the <location field> is a field whose value is either aGeoJSON object or a legacycoordinates pair.

Unlike a compound 2d index which can reference onelocation field and one other field, a compound 2dsphere index can reference multiplelocation and non-location fields.

For the following examples, consider a collection places withdocuments 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 2dsphereindex on the location field loc:

db.places.createIndex( { loc : "2dsphere" } )

Create a Compound Index with 2dsphere Index Key

A compound index can include a2dsphere index key in combination with non-geospatial index keys.For example, the following operation creates a compound index wherethe first key loc is a 2dsphere index key, and the remainingkeys category and names are non-geospatial index keys,specifically descending (-1) and ascending (1) keysrespectively.

db.places.createIndex( { loc : "2dsphere" , category : -1, name: 1 } )

Unlike the 2d index, a compound 2dsphere indexdoes not require the location field to be the first field indexed. Forexample:

db.places.createIndex( { category : 1 , loc : "2dsphere" } )