- Indexes >
- Geospatial Queries with
2d
Indexes
Geospatial Queries with 2d
Indexes¶
On this page
MongoDB provides support for querying location-based data using
special geospatial indexes. For an introduction to these 2d
indexes, see 2d Geospatial Indexes.
MongoDB supports the following geospatial query types:
- Proximity queries, which select documents based on distance to a given point. See Proximity Queries.
- Bounded queries, which select documents that have coordinates within a specified area. See Bounded Queries.
- Exact queries, which select documents with an exact coordinate pair, which has limited applicability. See Query for Exact Matches.
Considerations¶
With the geoNear
command, a collection can have only one
2d
index. With geospatial query operators such as $near
operator, a collection
can have multiple geospatial indexes.
Proximity Queries¶
Proximity queries select the documents closest to the point specified
in the query. To perform proximity queries you use either the
find()
method with the
$near
operator or you use the geoNear
command.
The find()
method with the
$near
operator returns 100 documents by default and sorts
the results by distance. The $near
operator uses the
following form:
Example
The following query
returns output similar to the following:
The geoNear
command returns more information than does the
$near
operator. The geoNear
command can only
return a single 16-megabyte result set. The
geoNear
command also offers additional operators, such as
operators to query for maximum or
spherical distance. For a list of
operators, see geoNear
.
Without additional operators, the geoNear
command uses the
following form:
Example
The following command returns the same results as the
$near
in the previous example but with more information:
This operation will return the following output:
Distance Queries¶
You can limit a proximity query to those documents that fall within a maximum distance of a point. You specify the maximum distance using the units specified by the coordinate system. For example, if the coordinate system uses meters, you specify maximum distance in meters.
To specify distance using the find()
method, use $maxDistance
operator. Use the following form:
To specify distance with the geoNear
command, use the
maxDistance
option. Use the following form:
Limit the Number of Results¶
By default, geospatial queries using find()
method return 100 documents, sorted by distance. To limit the result
when using the find()
method, use the
limit()
method, as in the following prototype:
To limit the result set when using the geoNear
command, use
the num
option. Use the following form:
To limit geospatial search results by distance, see Distance Queries.
Bounded Queries¶
Bounded queries return documents within a shape defined using the
$within
operator. MongoDB’s bounded queries support the
following shapes:
Bounded queries do not return sorted results. As a result MongoDB can return bounded queries more quickly than proximity queries. Bounded queries have the following form:
The following sections describe each of the shapes supported by bounded queries:
Circles¶
To query for documents with coordinates inside the bounds of a circle,
specify the center and the radius of the circle using the
$within
operator and $center
option. Consider
the following prototype query:
The following example query returns all documents that have coordinates
that exist within the circle centered on [-74, 40.74]
and with a
radius of 10
, using a geospatial index on the loc
field:
The $within
operator using $center
is similar
to using $maxDistance
, but $center
has
different performance characteristics. MongoDB does not sort queries
that use the $within
operator are not sorted, unlike
queries using the $near
operator.
Rectangles¶
To query for documents with coordinates inside the bounds of a
rectangle, specify the lower-left and upper-right corners of the
rectangle using the $within
operator and $box
option. Consider the following prototype query:
The following query returns all documents that have coordinates
that exist within the rectangle where the lower-left corner is at
[ 0, 0 ]
and the upper-right corner is at [ 3, 3 ]
, using a
geospatial index on the loc
field:
Polygons¶
New in version 1.9: Support for polygon queries.
To query for documents with coordinates inside of a polygon, specify the points
of the polygon in an array, using the $within
operator
with the $polygon
option. MongoDB automatically connects the
last point in the array to the first point. Consider the following
prototype query:
The following query returns all documents that have coordinates
that exist within the polygon defined by [ [0,0], [3,3], [6,0] ]
:
Query for Exact Matches¶
You can use the db.collection.find()
method to query for an
exact match on a location. These queries have the following form:
This query will return any documents with the value of [ x, y ]
.
Exact geospatial queries only applicability for a limited selection of cases, the proximity and bounded queries provide more useful results for more applications.
Calculate Distances Using Spherical Geometry¶
When you query using the 2d
index, MongoDB calculates distances
using flat geometry by default, which models points on a flat surface.
Optionally, you may instruct MongoDB to calculate distances using spherical geometry, which models points on a spherical surface. Spherical geometry is useful for modeling coordinates on the surface of Earth.
To calculate distances using spherical geometry, use MongoDB’s spherical query operators and options:
find()
method with the$nearSphere
operator.find()
method with the$centerSphere
.geoNear
command with the{ spherical: true }
option.
See also
For more information on differences between flat and spherical distance calculation, see Distance Calculation.
Distance Multiplier¶
The distanceMultiplier
option geoNear
returns
distances only after multiplying the results by command by an assigned
value. This allows MongoDB to return converted values, and removes the
requirement to convert units in application logic.
Note
Because distanceMultiplier
is an option to
geoNear
, the multiplication operation occurs on the
mongod
process. The operation adds a slight overhead to
the operation of geoNear
.
Using distanceMultiplier
in spherical queries allows one to use
results from the geoNear
command without radian to
distance conversion. The following example uses distanceMultiplier
in the geoNear
command with a spherical example:
The output of the above operation would resemble the following:
See also
The Distance operator.
Querying Haystack Indexes¶
Haystack indexes are a special 2d
geospatial index that optimized
to return results over small areas. To create geospatial indexes see
Haystack Indexes.
To query the haystack index, use the geoSearch
command. You must specify both the coordinate and other field to
geoSearch
, which take the following form:
For example, to return all documents with the value restaurants
in
the type
field near the example point, the command would resemble:
Note
Haystack indexes are not suited to returning a full list of the
closest documents to a particular location, as the closest
documents could be far away compared to the bucketSize
.
Note
Spherical query operations are not currently supported by haystack indexes.
The find()
method and
geoNear
command cannot access the haystack index.