Introducing Geospatial query capabilities for Amazon DocumentDB (with MongoDB compatibility)
Amazon DocumentDB (with MongoDB compatibility) is a database service that is purpose-built for JSON data management at scale, fully managed and integrated with AWS, and enterprise-ready with high durability.
This post introduces you to the new geospatial query capabilities in Amazon DocumentDB, specifically the $nearSphere query operator and the $geoNear aggregation pipeline stage. For more information regarding geospatial query capabilities, see the Developer Guide.
With the added support for geospatial query capability in Amazon DocumentDB, you can answer questions like “Which three restaurants are nearest to my current location?” or “How many state capitals are within 100 kilometers of Boston, Massachusetts?”
To perform geospatial queries, your documents must contain location information represented by GeoJSON type objects. In this first release of geospatial functionality, Amazon DocumentDB supports the GeoJSON Point type.
GeoJSON coordinates capture both longitude and latitude, representing positions on an earth-like sphere. The coordinates are presented in the format [longitude, latitude].
For example, you can create a collection of US state capitals named
capitals, noting where each capital is located, using the following schema:
After you have GeoJSON data in your documents, you need an index to support geospatial queries.
Building on the state capital example, you can create a geospatial index on the capitals collection as follows:
Create example data
The following commands create a geospatial index and insert state capitals for New England:
Now we can run some sample queries.
Query 1: List the state capitals sorted by distance from Boston, Massachusetts
The aggregation pipeline stage
$geoNear calculates the distance in meters from a GeoJSON point, adding
distanceMultiplier to the query returns the distance in kilometers.
The following query returns the state capitals and distance from Boston. The
near attribute contains the GeoJSON point used for calculating the distance to the other state capitals, and the
spherical attribute setting of
true instructs the distance calculation to be done using spherical geometry (i.e. calculate distance assuming points are on the surface of an Earth-like sphere) :
The query returns the following output:
Query 2: List the state capitals within 100 kilometers of Boston
The find operator
$nearSphere returns documents within a minimum
$minDistance and maximum
$maxDistance number of meters from a GeoJSON point.
For example, the following query returns the state capitals within 1 meter and 100 kilometers of Boston:
We get the following response:
This post introduced geospatial query support in Amazon DocumentDB. For more information about geospatial query support in Amazon DocumentDB, see the Developer Guide.
If you have any questions or comments about this post, please use the comments section. If you have any features requests for Amazon DocumentDB, email us at email@example.com.
About the Author
Tim Callaghan is a Principal DocumentDB Specialist Solutions Architect at AWS. He enjoys working with customers looking to modernize existing data-driven applications and build new ones. Prior to joining AWS he has been both a consumer of Relational and NoSQL databases for over 30 years