Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

$geoWithin

On this page

  • Definition
  • Behavior
  • Examples
$geoWithin

Selects documents with geospatial data that exists entirely within a specified shape.

The specified shape can be either a GeoJSON Polygon (either single-ringed or multi-ringed), a GeoJSON MultiPolygon, or a shape defined by legacy coordinate pairs. The $geoWithin operator uses the $geometry operator to specify the GeoJSON object.

To specify a GeoJSON polygons or multipolygons using the default coordinate reference system (CRS), use the following syntax:

{
<location field>: {
$geoWithin: {
$geometry: {
type: <"Polygon" or "MultiPolygon"> ,
coordinates: [ <coordinates> ]
}
}
}
}

For $geoWithin queries that specify GeoJSON geometries with areas greater than a single hemisphere, the use of the default CRS results in queries for the complementary geometries.

To specify a single-ringed GeoJSON polygon with a custom MongoDB CRS, use the following prototype that specifies the custom MongoDB CRS in the $geometry expression:

{
<location field>: {
$geoWithin: {
$geometry: {
type: "Polygon" ,
coordinates: [ <coordinates> ],
crs: {
type: "name",
properties: { name: "urn:x-mongodb:crs:strictwinding:EPSG:4326" }
}
}
}
}
}

The custom MongoDB CRS uses a counter-clockwise winding order and allows $geoWithin to support queries with a single-ringed GeoJSON polygon whose area is greater than or equal to a single hemisphere. If the specified polygon is smaller than a single hemisphere, the behavior of $geoWithin with the MongoDB CRS is the same as with the default CRS. See also "Big" Polygons.

If querying for inclusion in a shape defined by legacy coordinate pairs on a plane, use the following syntax:

{
<location field>: {
$geoWithin: { <shape operator>: <coordinates> }
}
}

The available shape operators are:

Important

If you use longitude and latitude, specify coordinates in order of longitude, latitude.

$geoWithin does not require a geospatial index. However, a geospatial index will improve query performance. Both 2dsphere and 2d geospatial indexes support $geoWithin.

The $geoWithin operator does not return sorted results. As such, MongoDB can return $geoWithin queries more quickly than geospatial $near or $nearSphere queries, which sort results.

$geoWithin does not guarantee that it will consider a piece of geometry to contain its component geometry, or another polygon sharing its component geometry.

For $geoWithin, if you specify a single-ringed polygon that has an area greater than a single hemisphere, include the custom MongoDB coordinate reference system in the $geometry expression; otherwise, $geoWithin queries for the complementary geometry. For all other GeoJSON polygons with areas greater than a hemisphere, $geoWithin queries for the complementary geometry.

The following example selects all loc data that exist entirely within a GeoJSON Polygon. The area of the polygon is less than the area of a single hemisphere:

db.places.find(
{
loc: {
$geoWithin: {
$geometry: {
type : "Polygon" ,
coordinates: [ [ [ 0, 0 ], [ 3, 6 ], [ 6, 1 ], [ 0, 0 ] ] ]
}
}
}
}
)

For single-ringed polygons with areas greater than a single hemisphere, see Within a "Big" Polygon.

To query with a single-ringed GeoJSON polygon whose area is greater than a single hemisphere, the $geometry expression must specify the custom MongoDB coordinate reference system. For example:

db.places.find(
{
loc: {
$geoWithin: {
$geometry: {
type : "Polygon" ,
coordinates: [
[
[ -100, 60 ], [ -100, 0 ], [ -100, -60 ], [ 100, -60 ], [ 100, 60 ], [ -100, 60 ]
]
],
crs: {
type: "name",
properties: { name: "urn:x-mongodb:crs:strictwinding:EPSG:4326" }
}
}
}
}
}
)
$within

Deprecated since version 2.4: $geoWithin replaces $within in MongoDB 2.4.

←  $geoIntersects$near →