$geoWithin

Definition

  • $geoWithin
  • Selects documents with geospatial data that exists entirelywithin a specified shape.

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

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

  1. {
  2.    <location field>: {
  3.       $geoWithin: {
  4.          $geometry: {
  5.             type: <"Polygon" or "MultiPolygon"> ,
  6.             coordinates: [ <coordinates> ]
  7.          }
  8.       }
  9.    }
  10. }

For $geoWithin queries that specify GeoJSON geometries withareas greater than a single hemisphere, the use of the default CRSresults in queries for the complementary geometries.

New in version 3.0: To specify a single-ringed GeoJSON polygon with a custom MongoDB CRS, use the followingprototype that specifies the custom MongoDB CRS in the$geometry expression:

  1. {
  2.    <location field>: {
  3.       $geoWithin: {
  4.          $geometry: {
  5.            type: "Polygon" ,
  6.            coordinates: [ <coordinates> ],
  7.            crs: {
  8.               type: "name",
  9.               properties: { name: "urn:x-mongodb:crs:strictwinding:EPSG:4326" }
  10.            }
  11.          }
  12.       }
  13.    }
  14. }

The custom MongoDB CRS uses a counter-clockwise winding order andallows $geoWithin to support queries with a single-ringedGeoJSON polygon whose area is greater thanor equal to a single hemisphere. If the specified polygon is smallerthan a single hemisphere, the behavior of $geoWithin withthe MongoDB CRS is the same as with the default CRS. See also“Big” Polygons.

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

  1. {
  2.    <location field>: {
  3.       $geoWithin: { <shape operator>: <coordinates> }
  4.    }
  5. }

The available shape operators are:

Important

If you use longitude and latitude, specify coordinates in orderof longitude, latitude.

Behavior

Geospatial Indexes

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

Unsorted Results

The $geoWithin operator does not return sorted results. Assuch, MongoDB can return $geoWithin queries more quickly thangeospatial $near or $nearSphere queries, which sortresults.

Degenerate Geometry

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

“Big” Polygons

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

Examples

Within a Polygon

The following example selects all loc data that exist entirelywithin a GeoJSON Polygon. The area of the polygon isless than the area of a single hemisphere:

  1. db.places.find(
  2.    {
  3.      loc: {
  4.        $geoWithin: {
  5.           $geometry: {
  6.              type : "Polygon" ,
  7.              coordinates: [ [ [ 0, 0 ], [ 3, 6 ], [ 6, 1 ], [ 0, 0 ] ] ]
  8.           }
  9.        }
  10.      }
  11.    }
  12. )

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

Within a “Big” Polygon

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

  1. db.places.find(
  2.    {
  3.      loc: {
  4.        $geoWithin: {
  5.           $geometry: {
  6.              type : "Polygon" ,
  7.              coordinates: [
  8.                [
  9.                  [ -100, 60 ], [ -100, 0 ], [ -100, -60 ], [ 100, -60 ], [ 100, 60 ], [ -100, 60 ]
  10.                ]
  11.              ],
  12.              crs: {
  13.                 type: "name",
  14.                 properties: { name: "urn:x-mongodb:crs:strictwinding:EPSG:4326" }
  15.              }
  16.           }
  17.        }
  18.      }
  19.    }
  20. )
  • $within

Deprecated since version 2.4: $geoWithin replaces $within in MongoDB2.4.