MongoDB Geospatial

Parent: MongoDB Expert Knowledge · researched 2026-05-28T15:31:25.623Z· 6 sources · 10 concepts · skill mongodb-geospatial

Use when designing or troubleshooting MongoDB geospatial queries, indexes, or data models. Covers GeoJSON storage, 2dsphere and 2d index types, proximity and containment operators ($near, $geoWithin,

Description

Use when designing or troubleshooting MongoDB geospatial queries, indexes, or data models. Covers GeoJSON storage, 2dsphere and 2d index types, proximity and containment operators ($near, $geoWithin, $geoNear, $geoIntersects), radius calculations, $lookup pipeline joins across spatial collections, and common anti-patterns. Apply this skill whenever a schema includes location fields, a query filters by distance or bounding region, or a $geoNear aggregation stage needs tuning. [source]

1. GeoJSON Object Types

MongoDB natively stores and queries the GeoJSON spec. Every GeoJSON field is an embedded document with a type string and a coordinates array. Longitude always comes before latitude - the opposite of most mapping UIs. [source]
Insert a document with a GeoJSON Point field: [source]

2. 2dsphere Indexes

A 2dsphere index supports queries on GeoJSON geometry computed over a sphere modelled on WGS84 (the same datum used by GPS). Version 3 has been the default since MongoDB 3.2; MongoDB 8.3+ defaults to version 4. It handles Points, LineStrings, and Polygons stored as GeoJSON and supports all geospatial query operators. [source]
Handles wraparound at the anti-meridian (180° longitude) correctly. [source]
Required by $geoNear, $near, $nearSphere, $geoWithin with $centerSphere. [source]
2dsphere indexes are always sparse (MongoDB ignores the sparse option). A document missing the geo field - or where it is null or an empty array - is not indexed, whether the index is standalone or compound. In a compound 2dsphere index, only the geo field determines whether a document is indexed. [source]

3. 2d Indexes

A 2d index uses planar (flat-earth) geometry. It is a legacy index type intended for coordinate pairs stored as [lng, lat] arrays (not GeoJSON documents). Use it only when the coordinate space is genuinely flat (e.g., game maps, CAD drawings, grid systems) and spherical correction is not needed. [source]
Limitations vs. 2dsphere: [source]
No polygon-edge wraparound. [source]
Distance unit is degrees, not metres. [source]
Does not support GeoJSON input documents. [source]
Cannot use $geoNear aggregation with spherical: true. [source]

4. $geoNear Aggregation Stage

$geoNear must be the first stage of an aggregation pipeline. It returns documents sorted by computed distance from a reference point and appends the distance value to each document under distanceField. A geospatial index is required; if multiple exist, specify key. [source]
distanceMultiplier converts metres to another unit: [source]
includeLocs records the matched location field alongside distance: [source]

5. $geoWithin

$geoWithin finds documents whose geometry is entirely contained within a specified shape. It does not sort results and does not require a geospatial index (though an index improves performance significantly on large collections). [source]

6. $geoIntersects

$geoIntersects finds documents whose GeoJSON geometry intersects - shares any point with - the query geometry. Useful for routes, delivery zones, and region overlap checks. Requires a 2dsphere index for good performance. [source]

7. $near and $nearSphere

$near and $nearSphere are query operators (not aggregation stages). Both sort results by distance and require a geospatial index. They cannot be used inside $or or $and alongside other $near/$nearSphere expressions. [source]
$near vs. $geoNear: Use $near for a simple .find() that returns sorted documents. Use $geoNear when you need the distance value in the result, further pipeline stages, or more control (distanceMultiplier, query pre-filter, key selection). [source]

8. Radius Queries

Converting a real-world radius to the unit each operator expects: [source]

9. Geospatial $lookup Patterns

Geospatial query operators ($geoIntersects, $geoWithin, $near) are query operators, not aggregation expression operators - they cannot be used inside $expr. Inside a $lookup pipeline stage, place them directly inside $match against a field in the joined collection. The outer document's location must be supplied via $geoNear output or by denormalizing the coordinate. [source]
Performance considerations for geospatial $lookup: [source]
$geoIntersects / $geoWithin inside a $lookup pipeline runs once per driving document; ensure a 2dsphere index on the joined collection's geometry field. [source]
Add a $match with a bounding-box $geoWithin before $lookup to narrow candidates when the joined collection is large. [source]
Denormalizing the zone or region ID at write time (Recommended pattern above) eliminates the per-row geo scan entirely and scales best. [source]
For hot-path proximity queries at scale, consider Atlas Search $search with a geoWithin or geoShape filter, which uses a dedicated search index and avoids aggregation pipeline overhead. [source]

References

MongoDB Geospatial Queries overview: https://www.mongodb.com/docs/manual/geospatial-queries/ [source]
Geospatial query operator reference: https://www.mongodb.com/docs/manual/reference/operator/query-geospatial/ [source]
2dsphere index documentation: https://www.mongodb.com/docs/manual/core/2dsphere/ [source]
$geoNear aggregation stage: https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/ [source]
GeoJSON objects reference: https://www.mongodb.com/docs/manual/reference/geojson/ [source]
Geospatial tutorial (find restaurants): https://www.mongodb.com/docs/manual/tutorial/geospatial-tutorial/ [source]

Children

GeoJSON Object Types (frontier)
2dsphere Indexes (frontier)
2d Indexes (frontier)
$geoNear Aggregation Stage (frontier)
$geoWithin and $centerSphere (frontier)
$geoIntersects (frontier)
$near and $nearSphere (frontier)
Radius Unit Conversions (frontier)
Geospatial $lookup Patterns (frontier)
Geospatial Anti-Patterns (frontier)

Frontier under this node: $geoIntersects, $geoNear Aggregation Stage, $geoWithin and $centerSphere, $near and $nearSphere, 2d Indexes, 2dsphere Indexes, GeoJSON Object Types, Geospatial $lookup Patterns, Geospatial Anti-Patterns, Radius Unit Conversions

← the whole tree · 3D view· how to read this page