Skip to content

Geospatial index and query

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Use Aerospike geospatial storage and indexing to enable fast queries on points within a region, on a region containing points, and points within a radius.

Underlying technologies

The Aerospike geospatial feature relies on these technologies:

Use cases

  • Vehicle tracking systems that require high-throughput updates of vehicle location and frequently query vehicles within a region.
  • A mapping application could find different amenities within a certain distance of a given location.
  • Location-targeted bidding transactions to discover persons or devices within the location with an active ad campaign.

See these Aerospike examples.

Geospatial data

Aerospike supports the GeoJSON geospatial data type. All geospatial functionality (indexing and querying) only execute on GeoJSON data types.

GeoJSON data incurs this additional processing on data reads:

  • GeoJSON text is parsed for validity and support (see GeoJSON Parsing).
  • GeoJSON text is converted into S2 CellID coverings.
  • Aerospike saves both the covering CellIDs and the original GeoJSON in the database.
  • Only GeoJSON data is accessible to the application through the client APIs and the UDF subsystem.

Store GeoJSON data

Store GeoJSON Point and Polygon objects in bins using each client’s GeoJSON data type.

Key key = DataSet.of("test", "geo").id("loc1");
String point = "{\"type\": \"Point\", \"coordinates\": [-122.0862, 37.4220]}";
session.upsert(key)
    .bin("name").setTo("Googleplex")
    .bin("loc_bin").setToGeoJson(point)
    .execute();

Geospatial index

In addition to integer and string indexes, Aerospike supports GEO2DSPHERE secondary indexes. With this index type, Aerospike can efficiently parse, index, and query GeoJSON Point, Polygon, MultiPolygon, and AeroCircle objects. Aerospike maps these shapes onto Google’s S2 spherical geometry library internally, providing the ultra-low latency required for high-throughput proximity searches and real-time location tracking.

Use asadm to create and manage secondary indexes in an Aerospike cluster. For instructions, see Secondary Index (SI) Query.

The following command creates a secondary index called geo-index using geo2dsphere data on the namespace test using the set name geo-set and the bin geo-bin.

Terminal window
Admin+> manage sindex create geo2dsphere geo-index ns test set geo-set bin geo-bin

Indexes can also be created programmatically:

session.createIndex(DataSet.of("test", "geo"), "geo-loc-idx", "loc_bin",
        IndexType.GEO2DSPHERE, IndexCollectionType.DEFAULT)
    .waitTillComplete();

Geospatial query

Aerospike supports two Geospatial queries:

  • Points exist within a region (including circle)
  • Region contains point

The following examples use these sample records, each containing a GeoJSON Point in loc_bin and a string in amenity:

{ "name": "Googleplex",      "loc_bin": {"type": "Point", "coordinates": [-122.0862, 37.4220]}, "amenity": "campus" }
{ "name": "Ferry Building",  "loc_bin": {"type": "Point", "coordinates": [-122.3936, 37.7956]}, "amenity": "cafe" }
{ "name": "UC Berkeley",     "loc_bin": {"type": "Point", "coordinates": [-122.2727, 37.8716]}, "amenity": "cafe" }
{ "name": "NYC Times Sq",    "loc_bin": {"type": "Point", "coordinates": [-73.9857,  40.7580]}, "amenity": "cafe" }

Points-within-region query

Find all points that fall within a given polygon. With the geo-loc-idx index on loc_bin, querying a Bay Area polygon returns the three California points but not New York.

String region = "{\"type\": \"Polygon\", \"coordinates\": [[" +
    "[-122.500, 37.000], [-121.000, 37.000], " +
    "[-121.000, 38.080], [-122.500, 38.080], " +
    "[-122.500, 37.000]]]}";
try (RecordStream rs = session.query(DataSet.of("test", "geo"))
        .where("geoCompare($.loc_bin, geoJson('" + region + "'))")
        .execute()) {
    rs.forEach(result -> System.out.println(result.recordOrThrow().getString("name")));
}

Points-within-radius query (circle)

Find all points within a given radius (in meters) of a longitude/latitude. The client constructs an AeroCircle GeoJSON internally. This example finds points within 50 km of the Googleplex. It returns the Googleplex and the Ferry Building.

// AEL takes the circle as an AeroCircle GeoJSON object: a center and a radius in meters
String circle = "{\"type\": \"AeroCircle\", \"coordinates\": [[-122.0862, 37.4220], 50000]}";
try (RecordStream rs = session.query(DataSet.of("test", "geo"))
        .where("geoCompare($.loc_bin, geoJson('" + circle + "'))")
        .execute()) {
    rs.forEach(result -> System.out.println(result.recordOrThrow().getString("name")));
}

Region-contains-point query

Find all stored regions that contain a given point. This requires a geo index on the bin storing the Polygon data. Create one on rgn_bin as in Geospatial index.

Given these region records stored in rgn_bin:

{ "name": "SF Bay Area", "rgn_bin": {"type": "Polygon", "coordinates": [[[-122.500,37.000],[-121.000,37.000],[-121.000,38.080],[-122.500,38.080],[-122.500,37.000]]]} }
{ "name": "Downtown SF", "rgn_bin": {"type": "Polygon", "coordinates": [[[-122.420,37.770],[-122.390,37.770],[-122.390,37.800],[-122.420,37.800],[-122.420,37.770]]]} }

Query for regions containing a point in Downtown San Francisco. Both regions are returned because the point falls inside the smaller Downtown SF polygon, which is itself inside the larger Bay Area polygon.

String point = "{\"type\": \"Point\", \"coordinates\": [-122.4000, 37.7900]}";
try (RecordStream rs = session.query(DataSet.of("test", "geo"))
        .where("geoCompare($.rgn_bin, geoJson('" + point + "'))")
        .execute()) {
    rs.forEach(result -> System.out.println(result.recordOrThrow().getString("name")));
}

Query filters

To extend the capabilities of geospatial queries, apply a filter expression to narrow down results. This example finds points within a 50 km radius that also have an amenity bin equal to "cafe". It returns the Ferry Building.

String circle = "{\"type\": \"AeroCircle\", \"coordinates\": [[-122.0862, 37.4220], 50000]}";
// The index serves the geoCompare, and the rest of the where filters its records
try (RecordStream rs = session.query(DataSet.of("test", "geo"))
        .where("geoCompare($.loc_bin, geoJson('" + circle + "'))"
            + " and $.amenity == 'cafe'")
        .execute()) {
    rs.forEach(result -> System.out.println(result.recordOrThrow().getString("name")));
}

Index on list/map

You can index and query GeoJSON elements stored inside list or map bins.

This example creates a geo index on list elements and queries for routes with stops inside a region. A route can be returned once for each of its stops inside the region (see Known limitations).

from aerospike_async import CollectionIndexType, Filter


(
    session.index("test", "geo")
    .on_bin("stops")
    .named("geo-points-idx")
    .geo2dsphere()
    .collection(CollectionIndexType.LIST)
    .create()
    .wait_till_complete_blocking()
)


region = (
    '{"type": "Polygon", "coordinates": [['
    '[-122.500, 37.000], [-121.000, 37.000], '
    '[-121.000, 38.080], [-122.500, 38.080], '
    '[-122.500, 37.000]]]}'
)


# An AEL where can't reach an index on List elements, so name the bin and collection type in
# an index filter
stream = (
    session.query(DataSet.of("test", "geo"))
    .filter(Filter.within_region("stops", region, CollectionIndexType.LIST))
    .execute()
)
for row in stream:
    print(row.record_or_raise().bins["name"])
stream.close()

Aerospike GeoJSON extension

Use the Aerospike AeroCircle geometry object to store circles along with regular polygons.

This example specifies a circle with a radius of 300 meters at longitude/latitude -122.250629, 37.871022.

{"type": "AeroCircle", "coordinates": [[-122.250629, 37.871022], 300]}

GeoJSON parsing

On data insert/update, Aerospike only recognizes Point, Polygon, MultiPolygon, and AeroCircle GeoJSON geometry objects, which are indexable objects. Unsupported GeoJSON objects return an AEROSPIKE_ERR_GEO_INVALID_GEOJSON result code 160 (for example, LineString or MultiLineString fail on insert). Holes can be Polygon objects, per the GeoJSON Format Specification.

Aerospike supports the Feature operator, which allows groups of geometry objects and user-specified properties; however, Feature Collection is not supported.

Invalid GeoJSON objects are caught on insert/update. For example, an object defined as point instead of Point fails.

Per the GeoJSON IETF recommendation, the Coordinate System is WGS84. Explicit specification of a coordinate reference system (CRS) is ignored.

Configuration parameters

ParameterDatatypeDefaultDescription
max-cellsInteger12Defines the maximum number of cells used in the approximation. Increasing this value improves accuracy but may affect query performance.
max-levelInteger20Defines the minimum size of the cell to be used in the approximation. Tuning this can make query results more accurate.
min-levelInteger1Defines the size of the maximum cell to be used in the approximation. Should generally be set to 1; increasing too much may cause queries to fail.
earth-radius-metersInteger6371000Specifies Earth’s radius in meters. Used for geographical calculations.
level-modInteger1Specifies the multiple for levels to be used, effectively increasing the branching factor of the S2 Cell Id hierarchy.
strictBooleantrueWhen true, performs additional validation on results to ensure they fall within the query region. When false, returns results as-is, which may include points outside the query region.

max-cells visualization

Here’s an example that shows how RegionCoverer covers a specified region with max-cells set to different values. With a higher value of max-cells, the approximation becomes more accurate.

With max-cells = 10:

max-cells = 10

With max-cells = 30:

max-cells = 30

With max-cells = 100:

max-cells = 100

max-level visualization

Here’s an example to see RegionCoverer covering a specified region and how tuning max-level can make query results more accurate. For this example, min-level is set to 1, and max-cells is set to 10.

With max-level = 12,

max-level = 12

With max-level = 30,

max-level = 30

Create a geospatial application

To develop a geospatial application:

  1. Install and configure the Aerospike server.
  2. Create a Geo2DSphere index on a namespace-set-bin combination.
  3. Construct and insert GeoJSON Point data.
  4. Construct a Points-within-Region predicate (where clause), make a query request, and process the records returned.
  5. (alternate) Construct and insert GeoJSON Polygon/MultiPolygon data.
  6. (alternate) Construct a Region-contains-Point predicate, make a query request, and process the records returned.

Known limitations

  • Using UDFs to insert or update GeoJSON data types is not supported.
  • Duplicate records can be returned.
  • For namespaces with data-in-memory true, GeoJSON particles allocate up to 2KB more than the reported particle size, which can lead to high memory consumption in some cases. This problem was corrected in Aerospike Database versions 4.9.0 and later.