diff --git a/src/docbkx/index.xml b/src/docbkx/index.xml index 87cb48bbc..ac3ca748e 100644 --- a/src/docbkx/index.xml +++ b/src/docbkx/index.xml @@ -2,6 +2,17 @@ + Good Relationships The Spring Data Graph Guide Book @@ -23,14 +34,6 @@ David Montag - - Mark - Pollack - - - Thomas - Risberg - @@ -40,6 +43,9 @@ further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. + + Copyright 2010-2011 Neo Technology + diff --git a/src/docbkx/introduction/about.xml b/src/docbkx/introduction/about.xml index 916fa350a..b94656469 100644 --- a/src/docbkx/introduction/about.xml +++ b/src/docbkx/introduction/about.xml @@ -3,44 +3,76 @@ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> About this guide book - - Welcome to the Spring Data Graph Guide Book. Thank you for taking the time to get an in depth look - into Spring Data Graph. - This project is part of the Spring Data project, - which brings the convenient programming model of the Spring Framework to modern NOSQL databases. - Spring Data Graph, as the name alludes to, aims to provide support for graph databases. It currently - supports Neo4j. - - - It was written by developers for developers. Hopefully we've created a document that is well received - by our peers. - - - If you have any feedback on Spring Data Graph or this book, please provide it via the - SpringSource JIRA, the - SpringSource NOSQL Forum, - github comments or issues, - or the Neo4j mailing list. - - - This book is presented as a duplex book, - a term coined by Martin Fowler. A duplex book consists of at least two parts. The first part is an easily - accessible tutorial that gives the reader an overview of the topics contained in the book. It contains lots - of examples and discussion topics. This part of the book is highly suited for cover-to-cover reading. - - - We chose a tutorial describing the creation of a web application that allows movie enthusiasts to - find their favorite movies, rate them, connect with fellow movie geeks, and enjoy social features such as - recommendations. The application is running on Neo4j using Spring Data Graph and the well-known Spring - Web Stack. - - - The second part of the book is the classic reference documentation, containing detailed information about - the library. It discusses the programming model, the underlying assumptions, and internals, as well as the - APIs for the object-graph mapping. The reference documentation is typically used to look up concrete bits of - information, or to drill down into certain topics. For hackers wanting to really delve into Spring Data - Graph, it can of course also be read cover-to-cover. - +
+ The Spring Data Graph Project + + Welcome to the Spring Data Graph Guide Book. Thank you for taking the time to get an in depth look + into Spring Data Graph. + This project is part of the Spring Data project, + which brings the convenient programming model of the Spring Framework to modern NOSQL databases. + Spring Data Graph, as the name alludes to, aims to provide support for graph databases. It currently + supports Neo4j. + +
+
+ Feedback + + It was written by developers for developers. Hopefully we've created a guide that is well received + by our peers. + + + If you have any feedback on Spring Data Graph or this book, please provide it via the + SpringSource JIRA, the + SpringSource NOSQL Forum, + github comments or issues, + or the Neo4j mailing list. + +
+
Format of the Book + + This book is presented as a duplex book, + a term coined by Martin Fowler. A duplex book consists of at least two parts. The first part is an easily + accessible tutorial that gives the reader an overview of the topics contained in the book. It contains lots + of examples and discussion topics. This part of the book is highly suited for cover-to-cover reading. + + + We chose a tutorial describing the creation of a web application that allows movie enthusiasts to + find their favorite movies, rate them, connect with fellow movie geeks, and enjoy social features such as + recommendations. The application is running on Neo4j using Spring Data Graph and the well-known Spring + Web Stack. + + + The second part of the book is the classic reference documentation, containing detailed information about + the library. It discusses the programming model, the underlying assumptions, and internals, as well as the + APIs for the object-graph mapping. The reference documentation is typically used to look up concrete bits of + information, or to drill down into certain topics. For hackers wanting to really delve into Spring Data + Graph, it can of course also be read cover-to-cover. + +
+
Acknowledgements + + We would like to thank everyone who contributed to this book, especially Mark Pollack and Thomas Risberg, + the leads of the Spring Data Project, who helped a lot during the development of the library as well as sharing + great feedback about the book. Also Oliver Gierke, our local German VMWare/SpringSource engineer, who invested a + lot of time discussing various aspects of the library as well as providing the superb foundations for the Spring + Data Repositories. We tortured Andy Clement, the AspectJ project lead, with many questions and issues around our + advanced AspectJ usage which caused some headaches. He always quickly solved our issues and gave us excellent + answers. + + + We also appreciate very much the foresight of Rod Johnson and Emil Eifrem to initiate the project, and now + also providing great forewords. Their leadership inspired collaboration between the engineering teams at + SpringSource and Neo Technology, a tremendous help during the making of Spring Data Graph. +   + +   + + Last but not least we thank our vibrant community, both in the Spring Forums as well as on the Neo4j + Mailing list and on many other places on the internet for giving us feedback, reporting issues and suggesting + improvements. Without that important feedback we wouldn't be where we are today. +   + +
  Enjoy the book! diff --git a/src/docbkx/reference/neo4j-server.xml b/src/docbkx/reference/neo4j-server.xml index 6c23db072..851b442a8 100644 --- a/src/docbkx/reference/neo4j-server.xml +++ b/src/docbkx/reference/neo4j-server.xml @@ -88,8 +88,8 @@ public void foo( @Context WorldRepository repo ) { Please also keep in mind that performing graph operations via the REST-API is about one order of - magnitude slower than location operations. Try to use the Neo4j-Query-Language or - server-side traversals whenever possible (RestTraversal) for retrieving large sets of data. + magnitude slower than location operations. Try to use the Neo4j Cypher query language, + server-side traversals (RestTraversal) or Gremlin expressions whenever possible for retrieving large sets of data. Future versions of Spring Data Graph will use the more performant batching as well as a binary protocol. @@ -124,5 +124,8 @@ public void foo( @Context WorldRepository repo ) { to the remote instance. (e.g. queryEngineFor(), index() and createTraversalDescription()). Please use those methods when interacting with a remote server for optimal performance. + + + diff --git a/src/docbkx/reference/neo4j.xml b/src/docbkx/reference/neo4j.xml index eec2043c9..bc587b1d4 100644 --- a/src/docbkx/reference/neo4j.xml +++ b/src/docbkx/reference/neo4j.xml @@ -150,6 +150,91 @@ try { for (Node foundNode : nodeIndex.get("property","value")) { // found node } +]]> + + +
+ Querying with Cypher + + With version 1.4.M04 Neo4j introduced a textual query language called + "Cypher" which draws from many + sources. From graph matching like in SPARQL, some keywords and query structure that reminds of SQL and + some iconic representation. A screencast presenting cypher queries on the cineasts.net dataset is available + at video.neo4j.org. Cypher was written + in Scala to leverage the high expressiveness for lazy sequence operations of the language and the great + parser combinator library. + + + Cypher queries always begin with a start set of nodes. Those can be either expressed by their + id's or by a index lookup expression. Those start-nodes are then related to other nodes in the + match clause to other nodes. Start and match clause can introduce new identifiers for nodes and + relationships. In the where clause additional filtering of the result set is applied by evaluating + boolean expressions. The return clause defines which part of the query result will be available. + Aggregation also happens in the return clause by using aggregation functions on some of the values. + Sorting can happen in the order by clause and the skip and limit parts + restrict the result set to a certain window. + + + Cypher can be executed on an embedded graph db using ExecutionEngine and + CypherParser. This is encapsulated in Spring Data Graph with + CypherQueryEngine. The Neo4j-REST-Server comes with a Cypher-Plugin that is accessible remotely and is + available in the Spring Data Graph REST-Binding. + + + Cypher Examples on the Cineasts.net Dataset + (movie) where r.stars > 3 + return movie.title, r.stars, r.comment + +// Mutual Friend recommendations: +start user=(User,login,'micha') match (user)-[:FRIEND]-(friend)-[r,:RATED]->(movie) where r.stars > 3 + return friend.name, movie.title, r.stars, r.comment? + +// Movie suggestions based on a movie: +start movie=(Movie,id,'13') match (movie)<-[:ACTS_IN]-()-[:ACTS_IN]->(suggestion) + return suggestion.title, count(*) order by count(*) desc limit 5 + +// Co-Actors, sorted by count and name of Lucy Liu +start lucy=(1000) match (lucy)-[:ACTS_IN]->(movie)<-[:ACTS_IN]-(co_actor) + return count(*), co_actor.name order by count(*) desc,co_actor.name limit 20 + +// recommendations including counts, grouping and sorting +start user=(User,login,'micha') match (user)-[:FRIEND]-(friend)-[r,:RATED]->(movie) + return movie.title, AVG(r.stars), count(*) order by AVG(r.stars) desc, count(*) desc +]]> + +
+
+ Gremlin a Graph Traversal DSL + + Gremlin is an expressive Groovy DSL developed by Marko Rodriguez + as part of the tinkerpop stack. It builds on top of a pipe implementation + (Blueprints Pipes) that uses connected operations to traverse a graph. Gremlin has a concise syntax but is + turing complete. + + Gremlin can be executed by including the tinkerpop and blueprints dependencies and then requesting a ScriptEngine + of type "gremlin" from the javax.Script* facilities. In Spring Data Graph this is encapsulated in + GremlinQueryEngine. The Neo4j-REST-Server also comes with a Gremlin-Plugin that is accessible remotely and is + available in the Spring Data Graph REST-Binding. + + + Sample Gremlin Queries + 30}.name + +// calculate basic collaborative filtering for vertex 1 +m = [:] +g.v(1).out('likes').in('likes').out('likes').groupCount(m) +m.sort{a,b -> a.value <=> b.value} ]]>
diff --git a/src/docbkx/reference/programming-model/aspectj.xml b/src/docbkx/reference/programming-model/aspectj.xml index f40b7a951..4b18c21ea 100644 --- a/src/docbkx/reference/programming-model/aspectj.xml +++ b/src/docbkx/reference/programming-model/aspectj.xml @@ -59,7 +59,7 @@ The AspectJ support in IntelliJ IDEA lacks some of the features. JetBrains is working on improving - the situation in their upcoming 10.5 release of their popular IDE. Their latest work is available + the situation in their upcoming 11 release of their popular IDE. Their latest work is available under their early access program (EAP). Building the project with the AspectJ compiler ajc works in IDEA (Options -> Compiler -> Java Compiler should show ajc). Make sure to give the compiler at least 512 MB of RAM. diff --git a/src/docbkx/reference/template.xml b/src/docbkx/reference/template.xml index 18f34fa4e..4179c40bf 100644 --- a/src/docbkx/reference/template.xml +++ b/src/docbkx/reference/template.xml @@ -14,68 +14,89 @@ There are methods (createNode() and createRelationship()) for creating nodes and - relationships that automatically set provided properties and optionally index certain fields. + relationships that automatically set provided properties. Neo4j template - +// Cypher +assert "Mark".equals(neo.query("start p=(%person) match p<-[:WORKS_WITH]-other return other.name", + map("person",thomas)).to(String.class).single()); + +// Gremlin +assert thomas.equals(neo.execute("g.v(person).out('WORKS_WITH')", + map("person",mark)).to(Node.class).single()); + +// Index lookup +assert mark.equals(neo.lookup("devs","name","Mark").single()); + +// Index lookup with Result Converter +assert "Mark".equals(neo.lookup("devs","name","Mark").to(String.class, new ResultConverter { + public String convert(PropertyContainer element, Class type) { + return (String) element.getProperty("name"); + }}));]]> +
+ QueryResult + + All querying methods of the template return a uniform result type: QueryResult<T> + which is also an Iterable<T>. The query result offers methods of converting each + element to a target type queryResult.to(Type.class) optionally supplying a + ResultConverter<FROM,TO> which takes care of custom conversions. By default most + query methods can already handle conversions from and to: Paths, Nodes, Relationship and GraphEntities + as well as conversions backed by registered ConversionServices. A converted QueryResult<FROM> is an + Iterable<TO>. QueryResults can be limited to a single value using the queryResult.single() + method. It also offers support for a pure callback function using a Handler<T>. + +
Indexing Adding nodes and relationships to an index is done with the index() method. - The query() methods either take a field/value combination to look for exact matches in the - index, or a Lucene query object or string to handle more complex queries. All query() - methods provide Path results to a PathMapper. + The lookup() methods either take a field/value combination to look for exact matches in the + index, or a Lucene query object or string to handle more complex queries. All lookup() + methods return a QueryResult<PropertyContainer> to be used or transformed.
Graph traversal - The traversal methods are at the core of graph operations. As such, they are fully supported in the - Neo4jTemplate. The traverseNext() method traverses to the direct neighbors - of the start node, filtering the relationships according to the parameters. - - + The traversal methods are at the core of graph operations. The traverse() method covers the full traversal operation that takes a TraversalDescription (typically built with the Traversal.description() - DSL) and runs it from the start node. Each path that is returned by the traversal is passed to the - PathMapper to be converted into the desired type. + DSL) and runs it from the given start node. traverse returns a QueryResult<Path> + to be used or transformed.
- Path abstraction and PathMapper + Cypher Queries - For the querying operations Neo4jTemplate unifies the result with the Path abstraction that - comes from Neo4j. Much like a result set, a path contains a chain of nodes() connected by - relationships(), starting at a startNode() and ending at a - endNode(). The lastRelationship() is also available separately. The - Path abstraction also wraps results that contain just nodes or relationships. + The Neo4jTemplate also allows execution of arbitrary Cypher queries. Via the query + methods the statement and parameter-Map are provided. Cypher Queries return tabular results, so the + QueryResult<Map<String,Object>> contains the rows which can be either used as they are + or converted as needed. +
+
+ Gremlin Scripts - Using implementations of PathMapper<T> and PathMapper.WithoutResult - (comparable with RowMapper and RowCallbackHandler), the paths can be converted - to arbitrary Java objects. - - - With EntityPath and EntityMapper there is also support for using - node entities within the Path and PathMapper constructs. + Gremlin Scripts can run with the execute method, which also takes the parameters that will be + available as variables inside the script. The result of the executions is a generic + QueryResult<Object> fit for conversion or usage.
@@ -88,4 +109,11 @@ assert "Mark".equals(neo.query("devs","name","Mark",new NodeNamePathMapper())); or the TransactionTemplate.
+
+ Neo4j REST Server + If the template is configured to use a RestGraphDatabase the expensive operations + like traversals and querying are executed efficiently on the server side by using the REST API to forward + those calls. All the other template methods require single network operations. + +