Neo4j Spatial is a library facilitating the import, storage and querying of spatial data in the Neo4j open source graph database.
This projects manual is deployed as part of the local build as the Neo4j Spatial Manual
Some key features include:
- Utilities for importing from ESRI Shapefile as well as Open Street Map files
- Support for all the common geometry types
- An RTree index for fast searches on geometries
- Support for topology operations during the search (contains, within, intersects, covers, disjoint, etc.)
- The possibility to enable spatial operations on any graph of data, regardless of the way the spatial data is stored, as long as an adapter is provided to map from the graph to the geometries.
- Ability to split a single layer or dataset into multiple sub-layers or views with pre-configured filters
The current index is an RTree index, but it has been developed in an extensible way allowing for other indices to be added if necessary. The spatial queries implemented are:
- Contain
- Cover
- Covered By
- Cross
- Disjoint
- Intersect
- Intersect Window
- Overlap
- Touch
- Within
- Within Distance
The simplest way to build Neo4j Spatial is by using maven. Just clone the git repository and run
mvn install
This will download all dependencies, compiled the library, run the tests and install the artifact in your local repository.
The primary type that defines a collection of geometries is the Layer. A layer contains an index for querying. In addition a Layer can be an EditableLayer if it is possible to add and modify geometries in the layer. The next most important interface is the GeometryEncoder.
The DefaultLayer is the standard layer, making use of the WKBGeometryEncoder for storing all geometry types as byte[] properties of one node per geometry instance.
The OSMLayer is a special layer supporting Open Street Map and storing the OSM model as a single fully connected graph. The set of Geometries provided by this layer includes Points, LineStrings and Polygons, and as such cannot be exported to Shapefile format, since that format only allows a single Geometry per layer. However, OMSLayer extends DynamicLayer, which allow it to provide any number of sub-layers, each with a specific geometry type and in addition based on a OSM tag filter. For example you can have a layer providing all cycle paths as LineStrings, or a layer providing all lakes as Polygons. Underneath these are all still backed by the same fully connected graph, but exposed dynamically as apparently separate geometry layers.
Spatial data is divided in Layers and indexed by a RTree.
GraphDatabaseService database = new GraphDatabaseFactory().newEmbeddedDatabase(storeDir);
try {
ShapefileImporter importer = new ShapefileImporter(database);
importer.importFile("roads.shp", "layer_roads");
} finally {
database.shutdown();
}
This is more complex because the current OSMImporter class runs in two phases, the first requiring a batch-inserter on the database. There is ongoing work to allow for a non-batch-inserter on the entire process, and possibly when you have read this that will already be available. Refer to the unit tests in classes TestDynamicLayers and TestOSMImport for the latest code for importing OSM data. At the time of writing the following worked:
OSMImporter importer = new OSMImporter("sweden");
Map<String, String> config = new HashMap<String, String>();
config.put("neostore.nodestore.db.mapped_memory", "90M" );
config.put("dump_configuration", "true");
config.put("use_memory_mapped_buffers", "true");
BatchInserter batchInserter = new BatchInserterImpl(dir, config);
importer.importFile(batchInserter, "sweden.osm", false);
batchInserter.shutdown();
GraphDatabaseService db = new GraphDatabaseFactory().newEmbeddedDatabase(dir);
importer.reIndex(db, 10000);
db.shutdown();
GraphDatabaseService database = new GraphDatabaseFactory().newEmbeddedDatabase(storeDir);
try {
SpatialDatabaseService spatialService = new SpatialDatabaseService(database);
Layer layer = spatialService.getLayer("layer_roads");
SpatialIndexReader spatialIndex = layer.getIndex();
Search searchQuery = new SearchIntersectWindow(new Envelope(xmin, xmax, ymin, ymax));
spatialIndex.executeSearch(searchQuery);
List<SpatialDatabaseRecord> results = searchQuery.getResults();
} finally {
database.shutdown();
}
Refer to the test code in the LayerTest and the SpatialTest classes for more examples of query code. Also review the classes in the org.neo4j.gis.spatial.query package for the full range or search queries currently implemented.
IMPORTANT Tested with: GeoServer 2.1.1
mvn clean install
Add your Github credentials in your ~/.m2/settings.xml
<settings>
<servers>
<server>
<id>github</id>
<username>[email protected]</username>
<password>secret</password>
</server>
</servers>
</settings>
now do
mvn clean install site -Pneo-docs-build -
-
unzip the
target/xxxx-server-plugin.zip
and the Neo4j libraries from your Neo4j download under$NEO4J_HOME/lib
into$GEOSERVER_HOME/webapps/geoserver/WEB-INF/lib
-
restart geoserver
-
configure a new workspace
-
configure a new datasource neo4j in your workspace. Point the "The directory path of the Neo4j database:" parameter to the relative (form the GeoServer working dir) or aboslute path to a Neo4j Spatial database with layers (see Neo4j Spatial
-
in Layers, do "Add new resource" and choose your Neo4j datastore to see the exisitng Neo4j Spatial layers and add them.
- check out the geoserver source
svn co https://svn.codehaus.org/geoserver/trunk geoserver-trunk
- build the source
cd geoserver-trunk
mvn clean install
- check that you can run the web app as of The GeoServer Maven build guide
cd src/web/app
mvn jetty:run
- in
$GEOSERVER_SOURCE/src/web/app/pom.xml
https://svn.codehaus.org/geoserver/trunk/src/web/app/pom.xml, add the following lines under the profiles section:
<profile>
<id>neo4j</id>
<dependencies>
<dependency>
<groupId>org.neo4j</groupId>
<artifactId>neo4j-spatial</artifactId>
<version>0.9-SNAPSHOT</version>
</dependency>
</dependencies>
</profile>
- start the GeoServer webapp again with the added neo4j profile
cd $GEOSERVER_SRC/src/web/app
mvn jetty:run -Pneo4j
- find Neo4j installed as a datasource under http://localhost:8080
For more info head over to Neo4j Wiki on uDig
Neo4j Spatial is also packaged as a ZIP file that can be unzipped into the Neo4j Server /plugin directory. After restarting the server, you should be able to do things liek the following REST calls (here illustrated using curl
)
Precompiled versions of that ZIP file ready for download and use:
#install the plugin
cp $NEO4J_SPATIAL_HOME/target/neo4j-spatial-XXXX-server-plugin.zip $NEO4J_HOME/plugins
cd unzip neo4j-spatial-XXXX-server-plugin.zip -d $NEO4J_HOME/plugins
#start the server
$NEO4J_HOME/bin/neo4j start
curl http://localhost:7474/db/data/
For the REST API, see Neo4j Spatial Manual REST part
git clone https://github.com/neo4j/spatial.git
cd spatial
mvn clean package
git clone https://github.com/neo4j/spatial.git
cd spatial
mvn clean install site -Pneo-docs-build
Add the following repositories and dependency to your project's pom.xml:
<repositories>
<repository>
<id>neo4j-contrib-releases</id>
<url>https://raw.github.com/neo4j-contrib/m2/master/releases</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>neo4j-contrib-snapshots</id>
<url>https://raw.github.com/neo4j-contrib/m2/master/snapshots</url>
<releases>
<enabled>false</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
</repositories>
[...]
<dependency>
<groupId>org.neo4j</groupId>
<artifactId>neo4j-spatial</artifactId>
<version>0.12-neo4j-2.0.2</version>
</dependency>
Some of the classes in Neoj4-Spatial include main() methods and can be run on the command-line. For example there are command-line options for importing SHP and OSM data. See the main methods in the OSMImporter and ShapefileImporter classes. Here we will describe how to setup the dependencies for running the command-line, using the OSMImporter and the sample OSM file two-street.osm. We will show two ways to run this on the command line, one with the java command itself, and the other using the 'exec:java' target in maven. In both cases we use maven to setup the dependencies.
git clone git://github.com/neo4j/spatial.git
cd spatial
mvn clean compile
mvn dependency:copy-dependencies
java -cp target/classes:target/dependency/* org.neo4j.gis.spatial.osm.OSMImporter osm-db two-street.osm
The first command above only needs to be run once, to get a copy of all required JAR files into the directory target/dependency. Once this is done, all further java commands with the -cp specifying that directory will load all dependencies. It is likely that the specific command being run does not require all dependencies copied, since it will only be using parts of the Neo4j-Spatial library, but working out exactly which dependencies are required can take a little time, so the above approach is most certainly the easiest way to do this.
mvn exec:java -Dexec.mainClass=org.neo4j.gis.spatial.osm.OSMImporter -Dexec.args="osm-db two-street.osm"
Note that the OSMImporter cannot re-import the same data multiple times, so you need to delete the database between runs if you are planning to do that.