Geospatial Queries

On this page

• Geospatial Data
• Geospatial Indexes
• Geospatial Queries
• Geospatial Models
• Example

MongoDB supports query operations on geospatial data. This section introduces MongoDB’s geospatial features.

Geospatial Data

In MongoDB, you can store geospatial data asGeoJSONobjects or aslegacy coordinate pairs.

GeoJSON Objects

To calculate geometry over an Earth-like sphere, store your location data asGeoJSON objects.

To specify GeoJSON data, use an embedded document with:

• a field namedtypethat specifies theGeoJSON object typeand

• a field namedcoordinatesthat specifies the object’s coordinates.

  If specifying latitude and longitude coordinates, list thelongitudefirst and thenlatitude:

  • Valid longitude values are between -180 and 180 , both inclusive.
  • Valid latitude values are between -90 and 90 (both inclusive).

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

For example, to specify aGeoJSON Point:

location
:
{
type
:
"Point"
,
coordinates
:
[
-
73.856077
,
40.848447
]
}

For a list of the GeoJSON objects supported in MongoDB as well as examples, seeGeoJSON objects.

MongoDB geospatial queries on GeoJSON objects calculate on a sphere; MongoDB uses theWGS84reference system for geospatial queries on GeoJSON objects.

Legacy Coordinate Pairs

To calculate distances on a Euclidean plane, store your location data as legacy coordinate pairs and use a2dindex. MongoDB supports spherical surface calculations on legacy coordinate pairs via a2dsphereindex by converting the data to the GeoJSON Point type.

To specify data as legacy coordinate pairs, you can use either an array (preferred) or an embedded document.

Specify via an array (

Preferred

):

<
field
>
:
[
<
x
>
,
<
y
>
]

If specifying latitude and longitude coordinates, list thelongitudefirst and thenlatitude; i.e.

<
field
>
:
[
<
longitude
>
,
<
latitude
>
]

If specifying latitude and longitude coordinates, list thelongitudefirst and thenlatitude:

• Valid longitude values are between -180 and 180 , both inclusive.
• Valid latitude values are between -90 and 90 (both inclusive).

Specify via an embedded document:

<
field
>
:
{
<
field1
>
:
<
x
>
,
<
field2
>
:
<
y
>
}

If specifying latitude and longitude coordinates, the first field, regardless of the field name, must contains thelongitudevalue and the second field, thelatitudevalue ; i.e.

<
field
>
:
{
<
field1
>
:
<
longitude
>
,
<
field2
>
:
<
latitude
>
}

• Valid longitude values are between -180 and 180 , both inclusive.
• Valid latitude values are between -90 and 90 (both inclusive).

To specify legacy coordinate pairs, arrays are preferred over an embedded document as some languages do not guarantee associative map ordering.

Geospatial Indexes

MongoDB provides the following geospatial index types to support the geospatial queries.

2dsphere

2dsphereindexes support queries that calculategeometries on an earth-like sphere.

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

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

where the<locationfield>is a field whose value is either aGeoJSON objector alegacy coordinates pair.

For more information on the2dsphereindex, see2dsphere Indexes.

2d

2dindexes support queries that calculategeometries on a two-dimensional plane. Although the index can support$nearSpherequeries that calculate on a sphere, if possible, use the2dsphereindex for spherical queries.

To create a2dindex, use thedb.collection.createIndex()method, specifying the location field as the key and the string literal"2d"as the index type:

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

where the<locationfield>is a field whose value is alegacy coordinates pair.

For more information on the2dindex, see2d Indexes.

Geospatial Indexes and Sharded Collections

You cannot use a geospatial index as ashard keywhen sharding a collection. However, you can create a geospatial index on a sharded collection by using a different field as the shard key.

For sharded collections, queries using$nearand$nearSphereare not supported. You can instead use either thegeoNearcommand or the$geoNearaggregation stage.

You can also query for geospatial data for a sharded cluster using$geoWithinand$geoIntersect.

Covered Queries

Ageospatial indexescannotcover a query.

Geospatial Queries

NOTE

For spherical queries, use the2dsphereindex result.

The use of2dindex for spherical queries may lead to incorrect results, such as the use of the2dindex for spherical queries that wrap around the poles.

Geospatial Query Operators

MongoDB provides the following geospatial query operators:

For more details, including examples, see the individual reference page.

Geospatial Command

MongoDB provides the following geospatial command:

For more details, including examples, seegeoNearreference page.

Geospatial Aggregation Stage

MongoDB provides the following geospatialaggregation pipeline stage:

For more details, including examples, see$geoNearreference page.

Geospatial Models

MongoDB geospatial queries can interpret geometry on a flat surface or a sphere.

2dsphereindexes support only spherical queries (i.e. queries that interpret geometries on a spherical surface).

2dindexes support flat queries (i.e. queries that interpret geometries on a flat surface) and some spherical queries. While2dindexes support some spherical queries, the use of2dindexes for these spherical queries can result in error. If possible, use2dsphereindexes for spherical queries.

The following table lists the geospatial query operators, supported query, used by each geospatial operations:

Example

Create a collectionplaceswith the following documents:

db
.
places
.
insert
(
{
name
:
"Central Park"
,
location
:
{
type
:
"Point"
,
coordinates
:
[
-
73.97
,
40.77
]
},
category
:
"Parks"
}
);
db
.
places
.
insert
(
{
name
:
"Sara D. Roosevelt Park"
,
location
:
{
type
:
"Point"
,
coordinates
:
[
-
73.9928
,
40.7193
]
},
category
:
"Parks"
}
);
db
.
places
.
insert
(
{
name
:
"Polo Grounds"
,
location
:
{
type
:
"Point"
,
coordinates
:
[
-
73.9375
,
40.8303
]
},
category
:
"Stadiums"
}
);

The following operation creates a2dsphereindex on thelocationfield:

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

The following query uses the$nearoperator to return documents that are at least 1000 meters from and at most 5000 meters from the specified GeoJSON point, sorted in order from nearest to farthest:

db
.
places
.
find
(
{
location
:
{
$near
:
{
$geometry
:
{
type
:
"Point"
,
coordinates
:
[
-
73.9667
,
40.78
]
},
$minDistance
:
1000
,
$maxDistance
:
5000
}
}
}
)

The following operation uses thegeoNearcommand to return documents that match the query filter{category:"Parks"}, sorted in order of nearest to farthest to the specified GeoJSON point:

db
.
runCommand
(
{
geoNear
:
"places"
,
near
:
{
type
:
"Point"
,
coordinates
:
[
-
73.9667
,
40.78
]
},
spherical
:
true
,
query
:
{
category
:
"Parks"
}
}
)