MongoDB has had geospatial query support since MongoDB 1.4. In subsequent versions we have added a range of new features, such as GeoJSON in MongoDB 2.4. In this post I will cover a new feature in MongoDB 3.0 for searching polygons that are larger than a hemisphere.

Finding objects in a specific area (polygon) can be done with the $geoWithin operator as illustrated below:

<?php
$c = (new MongoClient())->demo->points;

$c->find( [
    'loc' => [
        '$geoWithin' => [
            '$geometry' => [
                'type' => 'Polygon',
                'coordinates' => [ [
                    [ -0.91, 51.74 ],
                    [ -0.91, 51.27 ],
                    [  0.67, 51.27 ],
                    [  0.67, 51.74 ],
                    [ -0.91, 51.74 ]
                ] ]
            ]
        ]
    ]
] );
?>

The GeoJSON format, which we use in this query as argument to the $geoWithin operator, defines a polygon as an array of linear rings, which themselves are a list of coordinate pairs beginning and ending with the same point to form a closed ring. The first linear ring is required and defines the exterior boundary of the polygon. Subsequent rings, if specified, would define interior boundaries (i.e. holes) within the polygon.

As an image, the geometry in this query looks like:

The GeoJSON format specification does not give any meaning about the direction or winding of points. The application is left to determine which side of the geometry is the search area. Both of the following images are possible interpretations when just taking the GeoJSON specification into account:

The interpretation of which part forms the search area would of course provide very different results! Because GeoJSON does not address winding, sometimes applications make wrong decisions.

MongoDB deterministically chooses the area that is the "smallest of the two". For our query, it would consider the polygon that is shown first of the two interpretations shown above.

This logic works for most applications, but it falls apart when you want to find objects within a polygon that spans more than a hemisphere.

In the small example of London, you would certainly expect the smallest area, the one that covers London to be the search area. But when we consider this much larger polygon (a circle centred around 25°N, 90°E with a diameter of 115°), then it is not so obvious:

When the polygon is larger than a hemisphere, i.e. larger than half of the Earth's surface, the "smallest of the two" is actually the area we intended to exclude. From MongoDB 3.0 a custom coordinate reference system (CRS) is supported, which forces geospatial queries with a polygon search area to consider the direction of coordinates in deciding which side is the search area. Consistent with KML, and WKT/WKB, the search area is determined to be the area that is on the left hand side of the direction of points. MongoDB calls this "strict winding". With strict winding enabled through our custom CRS, the following two possibilities can be considered:

MongoDB's implementation of GeoJSON allows us to specify a custom coordinate reference system on any geometry object via a crs property. Currently MongoDB only supports our custom CRS, urn:x-mongodb:crs:strictwinding:EPSG:4326, to specify strict winding. In the future, MongoDB could also support others, such as UTM, the US National Grid, or the UK's Ordnance Survey National Grid. The addition of support for this crs property is called "Big Polygon support" in MongoDB.

In a query, our custom CRS would appear as an extra argument within the $geoWithin or $geoIntersects criteria, on the same level as type and coordinates:

<?php
$c = (new MongoClient())->demo->points;

$c->find( [
    'loc' => [
        '$geoWithin' => [
            '$geometry' => [
                'type' => 'Polygon',
                'coordinates' => [ [
                    [ -0.91, 51.74 ],
                    [ -0.91, 51.27 ],
                    [  0.67, 51.27 ],
                    [  0.67, 51.74 ],
                    [ -0.91, 51.74 ]
                ] ],
                'crs' => [
                    'type' => 'name',
                    'properties' => [
                        'name' => 'urn:x-mongodb:crs:strictwinding:EPSG:4326'
                    ]
                ]
            ]
        ]
    ]
] );
?>

The use of the custom CRS is only relevant when searching an area that is larger than a hemisphere. In most cases, the default "smallest of the two" behaviour will be sufficient and you will not need to specify a custom CRS.