You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -6,8 +6,107 @@ Neo4j Spatial is a library facilitating the import, storage and querying of spat
6
6
7
7
This projects manual is deployed as part of the local build as the [Neo4j Spatial Manual](http://neo4j-contrib.github.io/spatial).
8
8
9
-
![Open Street Map](https://raw.github.com/neo4j-contrib/spatial/master/src/docs/images/one-street.png"Open Street Map")
10
-
9
+
![Open Street Map](http://neo4j-contrib.github.io/spatial/0.24-neo4j-3.1/images/one-street.png"Open Street Map")
10
+
11
+
## History
12
+
13
+
This library began as a collaborative vision between Neo-Technology and [Craig Taverner](https://github.com/craigtaverner) in early 2010.
14
+
The bulk of the initial work was done by [Davide Savazzi](https://github.com/svzdvd) as part of his 2010 Google Summer of Code (GSoC) project
15
+
with Craig as mentor, as a project within the OSGeo GSoC program.
16
+
In 2011 and 2012 two further GSoC projects contributed, the last of which saw Davide return as mentor.
17
+
18
+
The original vision for the library was a comprehensive suite of GIS capabilities somewhat inspired by PostGIS,
19
+
while remaining aligned with the graph-nature of the underlying Neo4j database.
20
+
To achieve this lofty goal the JTS and GeoTools libraries were used, giving a large suite of capabilities very early on.
21
+
22
+
However, back in 2010 Neo4j was an embedded database with deployments that saw a low level of concurrent operation.
23
+
However, for many years now, Neo4j has been primarily deployed in high concurrent server environments.
24
+
Over the years there have been various efforts to make the library more appropriate for use in these environments:
25
+
26
+
* REST API (early Neo4j 1.x servers had no Cypher)
27
+
* IndexProvider mechanism (used during Neo4j 1.x and 2.x server, and removed for Neo4j 3.0)
28
+
* 0.23: Addition of Cypher procedures for Neo4j 3.0
29
+
* 0.24: Addition of a high performance bulk importer to the in-graph RTree index
30
+
* 0.25: Addition of GeoHash indexes for point layers
31
+
* 0.26: Support for native Neo4j point types
32
+
* 0.27: Major port to Neo4j 4.x which deprecated many of the Neo4j API's the library depended on
33
+
34
+
However, despite all these improvements, the core of the library only exposes the rich capabilities of JTS and GeoTools
35
+
if used in an embedded environment.
36
+
The large effort required to port the library to Neo4j 4.0 resulted in many backwards incompatibilities and
37
+
highlighted the need for a new approach to spatial libraries for Neo4j.
38
+
39
+
## Neo4j 4.x Support
40
+
41
+
This library was originally written in 2010 when Neo4j was still releasing early 1.x versions.
42
+
This means it made use of internal Java API's that were deprecated over the years, some as early as Neo4j 2.x.
43
+
When Neo4j 4.0 was released, many deprecated API's were entirely removed.
44
+
And the transaction API was changed in a fundamental way.
45
+
This has meant that the spatial library needed a major refactoring to work with Neo4j 4.x:
46
+
47
+
* The library previously depended on nested transactions. This allowed code that was called
48
+
within a transaction (like procedures) to be the same as code that was not (Java API).
49
+
The removal of this support required that all internal API's needed to include parameters
50
+
for the current transaction, and only the specific surface designed for embedded use not have that.
51
+
* The library made use of Lucene based explicit indexes in many places.
52
+
The removal of support for explicit indexes required completely new solutions in sevaral places:
53
+
* The `OSMImporter` will instead now use normal Neo4j schema indexes (introduced in 2.0).
54
+
However, these can only be created in separate index transactions.
55
+
Due to the new transaction model this requires stopping the import transaction,
56
+
starting an index transaction, and then restarting the import transaction.
57
+
All of this is incompatible with procedures, which already have an incoming, non-stoppable transaction.
58
+
The solution to this second problem was to run the actual import in another thread.
59
+
This has the additional benefit of retaining the original batch-processing capabilities.
60
+
The negative consequence of this it that it requires modifying the security model of the procedure context.
61
+
* The `ExplicitIndexBackedPointIndex` has been modified to instead use a schema index.
62
+
This required similar tricks to those employed in the `OSMImporter` described above.
63
+
* Neo4j 4.0 runs only in Java 11, and until recently GeoTools did not support newer Java versions.
64
+
It was therefor necessary to upgrade the GeoTools libraries to version 24.2.
65
+
This in turn required a re-write of the Neo4jDataStore interface since the older API had
66
+
long been deprecated, and was entirely unavailable in newer versions.
67
+
68
+
Consequences of this port:
69
+
70
+
* The large number of changes mean that the 0.27.0 version should be considered very alpha.
71
+
* Many API's have changed and client code might need to be adapted to take the changes into account.
72
+
* The new DataStore API is entirely untested in GeoServer, besides the existing unit and integration tests.
73
+
* The need to manage threads and create schema indexes results in the procedures requiring
74
+
unrestricted access to internal API's of Neo4j.
75
+
76
+
This last point means that you need to set the following in your `neo4j.conf` file:
77
+
78
+
```
79
+
dbms.security.procedures.unrestricted=spatial.*
80
+
```
81
+
82
+
If you are concerned about the security implications of unrestricted access, my best advice is to review
83
+
the code and decide for yourself the level of risk you face. See, for example, the method `IndexAccessMode.withIndexCreate`,
84
+
which adds index create capabilities to the security model.
85
+
This means that users without index creation privileges will be able to create the necessary spatial support indexes
86
+
described above.
87
+
This code was not written because we wanted to allow for that case, it was written because in the Neo4j security model,
88
+
procedures that can write data (mode=`WRITE`) are not allowed to create indexes.
89
+
So this security-fix was required even in the Community Edition of Neo4j.
90
+
91
+
---
92
+
93
+
The rest of the README might have information that is no longer accurate for the current version of this library.
94
+
Please report any mistakes as issues, or consider raising a pull-request with an appropriate fix.
95
+
96
+
## Concept Overview
97
+
98
+
The key concepts of this library include:
99
+
100
+
* Allow the user to model geograph data in whatever way they wish, through providing an adapter (extend `GeometryEncoder`).
101
+
Built-in encoders include:
102
+
* WKT and WKB stored as properties of nodes
103
+
* Simple points as properties of nodes (two doubles, or a double[] or a native Neo4j `Point`)
104
+
* OpenStreetMap with complex geometries stored as sub-graphs to reflect the original topology of the OSM model
105
+
* Multile CoordinationReferenceSystem support using GeoTools
106
+
* Support the concept of multiple geographic layers, each with its own CRS and Index
107
+
* Include an index capable of searching for complex geometries (in-graph RTree index)
108
+
* Support import and export in a number of known formats (eg. Shapefile and OSM)
109
+
* Embed the library and Neo4j within GIS tools like uDig and GeoServer
11
110
12
111
Some key features include:
13
112
@@ -137,9 +236,18 @@ For further Procedures examples, refer to the code in the [SpatialProceduresTest
137
236
138
237
## Neo4j Spatial Geoserver Plugin ##
139
238
140
-
*IMPORTANT*: Examples in this readme were originally tested with GeoServer 2.1.1. However, regular testing of new releases of Neo4j Spatial against GeoServer is not done, and so we welcome feedback on which versions are known to work, and which ones do not, and perhaps some hints as to the errors or problems encountered.
239
+
*IMPORTANT*: Examples in this readme were originally tested with GeoServer 2.1.1.
240
+
However, regular testing of new releases of Neo4j Spatial against GeoServer is not done,
241
+
and so we welcome feedback on which versions are known to work, and which ones do not,
242
+
and perhaps some hints as to the errors or problems encountered.
243
+
244
+
Each release of Neo4j Spatial builds against a specific version of GeoTools and should then be used in the version of GeoServer that corresponds to that.
245
+
The list of releases below starting at Neo4j 2.0.8 were built with GeoTools 9.0 for GeoServer 2.3.2,
246
+
but most release for Neo4j 3.x were ported to GeoTools 14.4 for GeoServer 2.8.4.
141
247
142
-
Each release of Neo4j Spatial builds against a specific version of GeoTools and should then be used in the version of GeoServer that corresponds to that. The list of releases below starting at Neo4j 2.0.8 were built with GeoTools 9.0 for GeoServer 2.3.2, but recent releases have been ported to GeoTools 14.4 for GeoServer 2.8.4.
248
+
For the port to Neo4j 4.0 we needed to upgrade GeoTools to 24.x to avoid bugs with older GeoTools in Java 11.
249
+
This also required a complete re-write of the Neo4jDataStore and related classes.
250
+
This has not been tested at all in any GeoTools enabled application, but could perhaps work with GeoServer 2.18.
143
251
144
252
### Building ###
145
253
@@ -210,7 +318,7 @@ For more info head over to [Neo4j Wiki on uDig](http://wiki.neo4j.org/content/Ne
210
318
211
319
## Using the Neo4j Spatial Server plugin ##
212
320
213
-
The Neo4j Spatial Plugin is available for inclusion in the server version of Neo4j 2.xand Neo4j 3.x.
321
+
The Neo4j Spatial Plugin is available for inclusion in the server version of Neo4j 2.x, Neo4j 3.x and Neo4j 4.x.
214
322
215
323
* Using GeoTools 9.0 (for GeoServer 2.3.2):
216
324
*[v0.12 for Neo4j 2.0.4](https://github.com/neo4j-contrib/m2/blob/master/releases/org/neo4j/neo4j-spatial/0.12-neo4j-2.0.4/neo4j-spatial-0.12-neo4j-2.0.4-server-plugin.zip?raw=true)
@@ -225,6 +333,8 @@ The Neo4j Spatial Plugin is available for inclusion in the server version of Neo
225
333
*[v0.25.5 for Neo4j 3.3.5](https://github.com/neo4j-contrib/m2/blob/master/releases/org/neo4j/neo4j-spatial/0.25.5-neo4j-3.3.5/neo4j-spatial-0.25.5-neo4j-3.3.5-server-plugin.jar?raw=true)
226
334
*[v0.26.2 for Neo4j 3.4.12](https://github.com/neo4j-contrib/m2/blob/master/releases/org/neo4j/neo4j-spatial/0.26.2-neo4j-3.4.12/neo4j-spatial-0.26.2-neo4j-3.4.12-server-plugin.jar?raw=true)
227
335
*[v0.26.2 for Neo4j 3.5.2](https://github.com/neo4j-contrib/m2/blob/master/releases/org/neo4j/neo4j-spatial/0.26.2-neo4j-3.5.2/neo4j-spatial-0.26.2-neo4j-3.5.2-server-plugin.jar?raw=true)
336
+
* Using GeoTools 24.2 (for GeoServer 2.18.x):
337
+
*[v0.27.0 for Neo4j 4.0.3](https://github.com/neo4j-contrib/m2/blob/master/releases/org/neo4j/neo4j-spatial/0.27.0-neo4j-4.0.3/neo4j-spatial-0.27.0-neo4j-4.0.3-server-plugin.jar?raw=true)
228
338
229
339
For versions up to 0.15-neo4j-2.3.4:
230
340
@@ -259,6 +369,7 @@ The server plugin provides access to the internal spatial capabilities using thr
259
369
* A REST API for creating layers and adding nodes or geometries to layers.
260
370
* For usage information see [Neo4j Spatial Manual REST](http://neo4j-contrib.github.io/spatial/#spatial-server-plugin)
261
371
* Note that this API provides only limited access to Spatial, with no access the the GeoPipes or import utilities
372
+
* This API was entirely removed when support for Neo4j 4.0 was added (version 0.27)
262
373
* An IndexProvider API (2.x only) for Cypher access using START node=node:geom({query})
263
374
* It is only possible to add nodes and query for nodes, and the resulting graph structure is not compatible with any other spatial API (not compatible with Java API, REST or Procedures), so if you use this approach, do not blend it with the other approaches.
264
375
* There is some brief documentation at [Finding geometries within distance using cypher](http://neo4j-contrib.github.io/spatial/#rest-api-find-geometries-within--distance-using-cypher)
@@ -267,12 +378,12 @@ The server plugin provides access to the internal spatial capabilities using thr
267
378
* Documentation is not yet available, but you can list the available procedures within Neo4j using the query `CALL spatial.procedures`
268
379
* This API uses the _Procedures_ capabilities released in Neo4j 3.0, and is therefor not available for Neo4j 2.x
269
380
270
-
At the time of writing the procedures were still being developed and changing.
271
-
However, they are already more extensive than the REST API, making them by far
272
-
the best option for accessing Neo4j remotely or through Cypher.
273
-
The IndexProvider approach has already been removed, and it is anticipated the REST API might follow suite.
381
+
During the Neo4j 3.x releases, support for spatial procedures changed a little,
382
+
through the addition of various new capabilities.
383
+
They were very quickly much more capable than the older REST API,
384
+
making them by far the best option for accessing Neo4j remotely or through Cypher.
274
385
275
-
The Java API (the original API for Neo4j Spatial), will, however, remain the most feature rich for some time,
386
+
The Java API (the original API for Neo4j Spatial) still remains, however, the most feature rich,
276
387
and therefor we recommend that if you need to access Neo4j server remotely, and want deeper access to Spatial functions,
277
388
consider writing your own Procedures. The Neo4j 3.0 documentation provides some good information on how to do this,
278
389
and you can also refer to the [Neo4j Spatial procedures source code](https://github.com/neo4j-contrib/spatial/blob/master/src/main/java/org/neo4j/gis/spatial/procedures/SpatialProcedures.java) for examples.
@@ -340,7 +451,7 @@ Add the following repositories and dependency to your project's pom.xml:
0 commit comments