GeoWave adds spatial and temporal indexes to key-value stores that have none

What it does: an index layer between geospatial data and NoSQL stores

GeoWave is described as an open source set of software with three capabilities, and the way the README frames them explains the whole project.

The first is that it adds multi-dimensional indexing capability to key/value stores, currently Apache Accumulo, Apache HBase, Apache Cassandra, Amazon DynamoDB, Redis and RocksDB, as well as direct FileSystem support. The second is that it adds support for geographic objects and geospatial operators to these stores. The third is that it provides MapReduce input and output formats for distributed processing and analysis of geospatial data.

The summary sentence at the end of that list is the one to keep: GeoWave is working to bridge geospatial software with modern key/value stores and distributed compute systems.

So the problem is not that geospatial data is hard to store. It is that the stores people actually use for scale do not have spatial indexes, and the geospatial tools people actually use expect a spatial index. GeoWave supplies the missing index without asking you to move your data into a different database.

The fourth item on the list is the geospatial software plugins, and there is one that matters: a GeoServer plugin to allow geospatial data in various key/value stores to be shared and visualized via OGC standard services. That is the piece that turns an indexed blob store into something a GIS client can consume.

The repository metadata names the stores in the same list and adds the topic spatiotemporal, which points at the second dimension. The index is not just spatial. A store that indexes only latitude and longitude cannot answer which events happened in a place last Tuesday, and a system that has to answer that question has either built a second index or accepted that it cannot.

The primary language is Java and the default branch is master, and the repository carries a pom.xml, a .mvn/ directory and an mvnw wrapper, so it is a Maven multi-module project.

The command line is the shortest path to a working store

The README's command-line example is the clearest statement of the intended workflow, and it is four commands against a local RocksDB store.

# Add a new RocksDB data store called myStore in the current directory
geowave store add -t rocksdb myStore

# Add a spatial index called spatialIdx to myStore
geowave index add -t spatial myStore spatialIdx

Then the data goes in and the queries come out:

# Ingest a shapefile with states into myStore in the spatialIdx index
geowave ingest localToGW -f geotools-vector states.shp myStore spatialIdx

# Query all the data in the states type from myStore
geowave query myStore "SELECT * FROM states"

The four steps are the model: create a store, create an index against it, ingest data into the index, then query it with SQL. That last point is worth pausing on, because it is the reason the project is useful in a mixed environment. A store that has no query language of its own gains one, and a team that already knows SQL does not have to learn a new access model.

The store and index are named separately and both are addressed by name in every subsequent command. That is not incidental. A single store can hold multiple indexes over the same underlying data, one spatial and one temporal for instance, and a query names the type it wants. The data is written once and served through whichever index answers the question.

The ingest command takes an adapter name, localToGW, and a format, geotools-vector. The format is not a filename extension, it is a converter, and GeoWave ships a set of them for reading vector and raster data in various formats. The shapefile is the example in the README because it is the format geospatial people already have.

The choice of RocksDB for the example is also a hint about the intended deployment profile. It needs no server, it runs in the current directory, and it is a key-value store with no spatial features whatsoever, which makes it the clearest demonstration of what GeoWave adds.

The Java API is the same four steps without the shell

The programmatic access path is documented in parallel, and the README points at the api package for the underlying libraries.

DataStore store = DataStoreFactory.createDataStore(<data store options>);
store.addType(<my data type>, <my index>);
try(Writer writer = store.createWriter()){
  //write data
  writer.write(<data>);
}
 
//this just queries everything
try(CloseableIterator it = store.query(QueryBuilder.newBuilder().build())){
  while(it.hasNext()){
    //retrieve results matching query criteria and do something
    it.next();
  }
}

The correspondence with the command line is one to one. DataStoreFactory.createDataStore takes the store options, which the README says might be AccumuloRequiredOptions or HBaseRequiredOptions. store.addType registers a type and an index, which is the equivalent of the index add command. The Writer is the ingest, and QueryBuilder.newBuilder().build() with no criteria is the equivalent of the select-all query.

The Writer and the CloseableIterator are both try-with-resources blocks, which is the modern Java idiom and also the right one here, since the writer holds resources against the store and the iterator holds an open cursor.

The README notes that simple examples of creating the data type and index can be found in SimpleIngest within the examples directory, and the repository layout confirms an examples/ directory with a java-api/ subdirectory, a data/ directory and its own README.

The Maven coordinates for the programmatic route are given as a pom snippet. The datastore artifact is named with the store as a variable, geowave-datastore-${keyvalue-datastore}, with the version also as a variable, and the vector and raster adapters are separate artifacts, geowave-adapter-vector and geowave-adapter-raster, so a consumer pulls only the adapters they need.

The version situation is the first practical problem

The README's Software section is where the practical constraints live, and it is unusually direct about them.

Released Maven artifacts are on Maven Central, and the latest release there is 2.0.1, from the Java 8 line. Version 3.0 is not published yet, pending the Eclipse Foundation's approval of the org.locationtech namespace on the Sonatype Central Portal.

That is a dependency-resolution problem, not a technical one, but it determines what you can install today. Anyone pulling org.locationtech.geowave from Maven Central gets 2.0.1 and the Java 8 line that goes with it.

From 3.0 on, release binaries such as the command-line tools and the GeoServer plugin will be attached to GitHub Releases instead. Until then, the README says to build from source. The master branch requires JDK 21, and for Java 8 the 2.x-jdk8 branch is the one to use.

So there are two supported configurations with different costs. The 2.0.1 artifacts are on Maven Central and work with Java 8, but they are from May 2022 and the CLI and plugin binaries for that line are not on GitHub Releases either. The master branch is where the work is, it needs JDK 21, and you build it yourself.

The documentation has the same split. The published documentation site was last generated in 2022 for the 2.0.x line, and until publishing resumes the documentation for the current master, described as 3.0 and Java 21, lives in the repository under docs/content. So the online docs describe the older release and the current docs are in the source tree.

That combination, an unreleased master and stale published docs, is the single biggest practical consideration when evaluating GeoWave today. It is a large, capable project that is being maintained, with the last push on 2026-10-05 and the repository not archived, but the packaging is behind the code.

The release history shows the same shape. The tags are v2.0.1 from 2022, v2.0.0 from 2021 and v1.2.0 from 2020. The project did not stop, the commits continued on master, but the artefacts stopped moving.

The community and governance signals are LocationTech, not personal

The project sits under the LocationTech namespace, and that has concrete consequences for how it is run and how you get support.

Community support is available through GitHub Issues and on a mailing list, [email protected]. The mailing list address is the Eclipse one, which reflects that the project is being moved toward the Eclipse Foundation, and that matches the note about the org.locationtech namespace pending the Foundation's approval on the Sonatype Central Portal.

The repository carries a CODE_OF_CONDUCT.md, a CONTRIBUTING.md and a SECURITY.md, which is the standard governance set for a project in this position. The README also links the underlying principles to academic publications, with the background theory in Advances in Spatial and Temporal Databases 2017 and a derivative, more applied paper in the FOSS4G 2017 Conference Proceedings. That is a useful pointer for anyone evaluating the design, because the indexing approach is described there in more depth than the README manages.

The repository layout also shows the breadth of the project. There is core/, extensions/, services/, deploy/, analytics/, migration/, python/, docs/, examples/ and test/ directories, plus a DEPENDENCIES file, a NOTICE file and a spotbugs-exclude.xml. The analytics/ and python/ directories suggest that GeoWave is not only a storage layer but carries some analysis and a Python component, and migration/ suggests attention to moving between versions.

The build tooling is also more considered than a single-module project would need. There is a .mvn/ directory, a Maven wrapper with both mvnw and mvnw.cmd, and a dev-resources/ directory. The CI badges in the README header show a test workflow and an ip-check workflow, the latter being a licence and dependency check, which is what a project with this many downstream store adapters would need to catch an accidentally copied licence header.

The Maven Central badge points specifically at the geowave-core-store artefact rather than at the project as a whole, which is a small hint about the module structure: the core store is the piece other projects depend on directly.

Where GeoWave is the wrong choice

The first limit is the obvious one. If your store already has native geospatial support, GeoWave is solving a problem you do not have. PostgreSQL with PostGIS, MySQL with its spatial types, MongoDB with its 2dsphere indexes, Elasticsearch with its geo queries, and the geo stores that ship with Accumulo and HBase all have spatial indexing of some kind. Adding a second indexing layer on top of a store that already indexes spatially buys you the GeoWave query model and the GeoServer plugin, and costs you a write path that now goes through two systems.

The second limit is the write path. GeoWave indexes data into the store, which means the data lives in your key-value store in a form that GeoWave understands, and the ingest is a conversion rather than a plain insert. If your application also writes to that store directly, you now have two writers of the same logical data with no documented reconciliation, and the spatial index goes stale. That is a serious operational constraint and it is the reason the project is positioned around batch ingest of shapefiles and similar sources rather than around live application writes.

The third limit is the release gap, already described. Building from source on JDK 21 to get the current behaviour is a commitment, and it means the deployment is not using a published artefact with a published set of dependencies.

The alternative to weigh is the store's own geospatial support, and the difference in approach is directness. PostGIS gives you spatial types, spatial indexes, a query language and a spatial join in one system, with no second data model. Elasticsearch and MongoDB give you a geo query inside a store you may already run, again with no second index. The difference in approach in GeoWave's favour is that it works across stores and gives you a uniform query model plus the GeoServer integration, so if you are on Cassandra or DynamoDB, which have no spatial features at all, GeoWave is the only one of the three that is available to you. And in GeoWave's disfavour is that its own cost is the second index, the conversion on write, and a Java 21 build from source.

There is a fourth practical point that follows from the store list. Redis and DynamoDB behave very differently from Accumulo and HBase, and the README describes the same GeoWave abstractions over all of them. A project that has been developed against one store's semantics is not automatically portable to another, and the adapter set in the repository, one per store, is where that difference lives.

Editorial conclusion

Adopt GeoWave if you need range queries over spatial data in a store that has no native geospatial support and you want the GeoServer integration that comes with it, since the whole project is built around that gap. Do not adopt it if you need a released 3.0 artifact today, because the current Maven Central release is 2.0.1 from the Java 8 line and 3.0 is pending namespace approval. Verify first which of the seven stores your data already lives in and that store's own geospatial support, since a store with native spatial types may not need an external index, and that you can build from source with JDK 21 if you want the 3.0 line.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. locationtech/geowave on GitHub
4. README
5. Releases