# 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, Parent: [MongoDB Expert Knowledge](https://llms-explorer.com/tree/mongodb-expert-knowledge/) · 15 facets · 49 facts · page: https://llms-explorer.com/tree/mongodb-geospatial/ ## 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#description) ## 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#1-geojson-object-types) - Insert a document with a GeoJSON Point field: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#1-geojson-object-types) ## 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#2-2dsphere-indexes) - Handles wraparound at the anti-meridian (180° longitude) correctly. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#2-2dsphere-indexes) - Required by $geoNear, $near, $nearSphere, $geoWithin with $centerSphere. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#2-2dsphere-indexes) - 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#2-2dsphere-indexes) ## 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#3-2d-indexes) - Limitations vs. 2dsphere: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#3-2d-indexes) - No polygon-edge wraparound. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#3-2d-indexes) - Distance unit is degrees, not metres. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#3-2d-indexes) - Does not support GeoJSON input documents. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#3-2d-indexes) - Cannot use $geoNear aggregation with spherical: true. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#3-2d-indexes) ## 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#4-geonear-aggregation-stage) - distanceMultiplier converts metres to another unit: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#4-geonear-aggregation-stage) - includeLocs records the matched location field alongside distance: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#4-geonear-aggregation-stage) ## 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#5-geowithin) ## 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#6-geointersects) ## 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#7-near-and-nearsphere) - $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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#7-near-and-nearsphere) ## 8. Radius Queries - Converting a real-world radius to the unit each operator expects: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#8-radius-queries) ## 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#9-geospatial-lookup-patterns) - Performance considerations for geospatial $lookup: — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#9-geospatial-lookup-patterns) - $geoIntersects / $geoWithin inside a $lookup pipeline runs once per driving document; ensure a 2dsphere index on the joined collection's geometry field. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#9-geospatial-lookup-patterns) - Add a $match with a bounding-box $geoWithin before $lookup to narrow candidates when the joined collection is large. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#9-geospatial-lookup-patterns) - Denormalizing the zone or region ID at write time (Recommended pattern above) eliminates the per-row geo scan entirely and scales best. — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#9-geospatial-lookup-patterns) - 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](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#9-geospatial-lookup-patterns) ## References - MongoDB Geospatial Queries overview: https://www.mongodb.com/docs/manual/geospatial-queries/ — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#references) - Geospatial query operator reference: https://www.mongodb.com/docs/manual/reference/operator/query-geospatial/ — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#references) - 2dsphere index documentation: https://www.mongodb.com/docs/manual/core/2dsphere/ — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#references) - $geoNear aggregation stage: https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/ — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#references) - GeoJSON objects reference: https://www.mongodb.com/docs/manual/reference/geojson/ — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#references) - Geospatial tutorial (find restaurants): https://www.mongodb.com/docs/manual/tutorial/geospatial-tutorial/ — [source](https://llms-explorer.com/sources/mdb-context-hub/mongodb-geospatial/#references) ## Where this helps - Storing and querying location data for a delivery, ride-share, store-locator, or asset-tracking application where MongoDB is already the primary datastore. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Building proximity search ("nearest N points") or containment checks ("is this point inside this zone") without standing up a separate GIS-specific database. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Joining geospatial data across collections — for example, matching a delivery address to a service zone via a $lookup pipeline with a geo filter. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Debugging a geospatial query that returns unexpected results, often traceable to longitude/latitude ordering or a missing or wrong index type. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Project ideas - Build a "find nearby" endpoint using $geoNear as the first aggregation stage to return sorted results with the computed distance attached, then convert units with distanceMultiplier. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Build a delivery-zone lookup service that denormalizes a zone or region ID onto each document at write time, rather than computing $geoWithin per query, to eliminate the per-row geo scan at read time. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Implement route or region overlap detection with $geoIntersects backed by a 2dsphere index, useful for checking whether a delivery route crosses a restricted zone. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Build a hot-path proximity search on Atlas Search using a geoWithin or geoShape filter instead of the aggregation pipeline, for workloads where dedicated search-index performance matters more than pipeline flexibility. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Antipatterns - Storing coordinates as [lat, lng] instead of GeoJSON's required [lng, lat] order — a swap that silently produces wrong results rather than an error. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Using a legacy 2d index for real-world geographic data, when 2d assumes flat-earth planar geometry and doesn't handle anti-meridian wraparound or spherical distance correctly. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Running $geoIntersects or $geoWithin inside a $lookup pipeline against a large joined collection without a 2dsphere index on the joined field, turning the join into an unindexed per-row geo scan. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Nesting multiple $near or $nearSphere expressions inside $or or $and — both operators require being the sole query predicate and will reject that combination. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Known issues - 2dsphere indexes are always effectively sparse — a document with a missing, null, or empty-array geo field is silently excluded from the index, even if the sparse option itself isn't set. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - $geoWithin does not sort results and doesn't strictly require a geospatial index, but performance degrades badly on large collections without one, which can mask itself as a "correct but slow" query rather than an obvious missing-index error. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - $geoNear must be the first stage of its aggregation pipeline, which constrains how it can be combined with earlier filtering — any pre-filtering has to happen through the stage's own query option, not an earlier $match. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* - Geospatial query operators like $geoIntersects, $geoWithin, and $near cannot be used inside $expr, since they are query operators, not aggregation expression operators — a common point of confusion when building $lookup pipelines. — [source](https://llms-explorer.com/tree/mongodb-geospatial/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Context files - [MongoDB Geospatial](https://llms-explorer.com/downloads/sources/mdb-context-hub/mongodb-geospatial.md)