Aerospike Geospatial configuration and examples

Knowledge Base Operating
1

The Aerospike Knowledge Base has moved to https://support.aerospike.com. Content on https://discuss.aerospike.com is being migrated to either https://support.aerospike.com or https://docs.aerospike.com. Maintenance on articles stored in this repository ceased on December 31st 2022 and this article may be stale. If you have any questions, please do not hesitate to raise a case via https://support.aerospike.com.

Aerospike Geospatial configuration and examples

Details

Aerospike provides geospatial storage, indexing, and query to enable fast queries on points within a region, on a region containing points, and points within a radius. This feature is mainly dependent on S2 Spherical Geometry Library to map points and regions in single-dimension, 64-bit CellID representation. The S2 Geometry Library is a spherical geometry library, very useful for manipulating regions on a sphere (commonly on Earth) and indexing geographic data. This article mainly covers the use of geospatial configuration parameters and basic examples of geo queries using AQL.

Commonly used geo configuration parameters on aerospike server:

  1. max-cells

This defines the maximum number of cells used in the approximation. Increasing the maximum number of cells increases accuracy and reduces geo_region_query_falsepos. Note that increasing this value too much will result into more internal queries and will affect query performance.

Here’s an example which shows how RegionCoverer covers a specified region with max-cells = 10, max-cells = 30 and max-cells = 100. With more max-cells, the approximation becomes more accurate.

With max-cells=10,

alt text

With max-cells=30,

alt text

With max-cells=100,

alt text

  1. max-level

This defines the minimum size of the cell to be used in the approximation.

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,

alt text

With max-level=30,

alt text

  1. min-level

This defines the size of the maximum cell to be used in the approximation. The min-level should be set to default value 1 in most cases. Increasing this value too much can cause the queried region to not fit in and the query may fail.

  1. Here is a list of a few other geo configuration parameters defined on the Aerospike server:
  • earth-radius-meters, Default: 6371000
    • This is used to specify earth’s radius in meters.
  • level-mod, Default: 1
    • If specified, then only cells where (level - min-level) is a multiple of “level-mod” will be used (default 1). This effectively allows the branching factor of the S2 Cell Id hierarchy to be increased.
  • strict, Default: true
    • When strict=true, Aerospike will do an additional check on the results to validate whether the points returned by S2 falls under the user’s query region.
    • When strict=false, Aerospike does not do this additional check and sends the results as it is, which could contain the points even from outside the query region.

Examples using AQL to create Geo Secondary Index and run queries.

To define a secondary index on Geo bin,

aql> CREATE INDEX geo_index ON test.testset (geo_query_bin) GEO2DSPHERE

Example for points-within-a-region query using AQL.

Insert a point data into aerospike.

aql> INSERT INTO test.testset (PK, geo_query_bin) VALUES (2, GEOJSON('{"type": "Point", "coordinates": [1,1]}'))

Querying a region to see if it contains that point.

aql> SELECT * FROM test.testset WHERE geo_query_bin CONTAINS GeoJSON('{"type":"Polygon", "coordinates": [[[0,0], [0, 10], [10, 10], [10, 0], [0,0]]]}'))
+----------------------------------------------------+
| geo_query_bin                                      |
+----------------------------------------------------+
| GeoJSON('{"type": "Point", "coordinates": [1,1]}') |
+----------------------------------------------------+
1 row in set (0.004 secs)

Example for region-contains-points query using AQL.

Insert a region data into aerospike.

aql> INSERT INTO test.testset (PK, geo_query_bin) VALUES (1, GEOJSON('{"type": "Polygon", "coordinates": [[[0,0], [0, 10], [10, 10], [10, 0], [0,0]]]}'))

Query a point in that region.

AQL> SELECT * FROM test.testset WHERE geo_query_bin CONTAINS GeoJSON('{"type":"Point", "coordinates": [1, 1]}')
+---------------------------------------------------------------------------------------------+
| geo_query_bin                                                                               |
+---------------------------------------------------------------------------------------------+
| GeoJSON('{"type": "Polygon", "coordinates": [[[0,0], [0, 10], [10, 10], [10, 0], [0,0]]]}') |
+---------------------------------------------------------------------------------------------+
1 row in set (0.017 secs)

Keywords

GEOSPATIAL QUERY MAX-LEVEL MIN-LEVEL MAX-CELLS

Timestamp

June 17 2019