Neo4j Manual Milestone

448

Transcript of Neo4j Manual Milestone

The Neo4j Manual v1.7

The Neo4j Team neo4j.org neotechnology.com

The Neo4j Manual v1.7Publication date 2012-04-1818:27:40 Copyright 2012 Neo Technology

by The Neo4j Team neo4j.org neotechnology.com

Quickstart Section2.1, What is a Graph Database? Chapter4, Using Neo4j embedded in Java applications Chapter11, Using Neo4j embedded in Python applications Chapter18, Neo4j Server Chapter19, REST API

License: Creative Commons 3.0

This book is presented in open source and licensed through Creative Commons 3.0. You are free to copy, distribute, transmit, and/or adapt the work. This license is based upon the following conditions: Attribution. You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work). Share Alike. If you alter, transform, or build upon this work, you may distribute the resulting work only under the same, similar or a compatible license. Any of the above conditions can be waived if you get permission from the copyright holder. In no way are any of the following rights affected by the license: Your fair dealing or fair use rights The authors moral rights Rights other persons may have either in the work itself or in how the work is used, such as publicity or privacy rights

Note

For any reuse or distribution, you must make clear to the others the license terms of this work. The best way to do this is with a direct link to this page: http://creativecommons.org/licenses/by-sa/3.0/

Table of ContentsPreface .................................................................................................................................................. xi I. Introduction ........................................................................................................................................ 1 1. Neo4j Highlights ....................................................................................................................... 2 2. Graph Database Concepts ......................................................................................................... 3 2.1. What is a Graph Database? ........................................................................................... 4 2.2. Comparing Database Models ......................................................................................... 8 3. The Neo4j Graph Database .................................................................................................... 11 3.1. Nodes ........................................................................................................................... 12 3.2. Relationships ................................................................................................................ 13 3.3. Properties ..................................................................................................................... 16 3.4. Paths ............................................................................................................................. 18 3.5. Traversal ....................................................................................................................... 19 II. Tutorials ......................................................................................................................................... 20 4. Using Neo4j embedded in Java applications .......................................................................... 21 4.1. Include Neo4j in your project ..................................................................................... 22 4.2. Hello World ................................................................................................................. 25 4.3. User database with index ............................................................................................. 28 4.4. Basic unit testing ......................................................................................................... 30 4.5. Traversal ....................................................................................................................... 32 4.6. Domain entities ............................................................................................................ 41 4.7. Graph Algorithm examples .......................................................................................... 42 4.8. Reading a management attribute ................................................................................. 44 4.9. Execute Cypher Queries from Java ............................................................................. 45 5. Cypher Cookbook ................................................................................................................... 47 5.1. Hyperedges and Cypher ............................................................................................... 48 5.2. Basic Friend finding based on social neighborhood .................................................... 51 5.3. Co-favorited places ...................................................................................................... 52 5.4. Find people based on similar favorites ........................................................................ 54 5.5. Multirelational (social) graphs ..................................................................................... 55 5.6. A multilevel indexing structure (path tree) ................................................................. 56 6. Using the Neo4j REST API ................................................................................................... 60 6.1. How to use the REST API from Java ......................................................................... 61 7. Extending the Neo4j Server ................................................................................................... 66 7.1. Server Plugins .............................................................................................................. 67 7.2. Unmanaged Extensions ................................................................................................ 71 8. The Traversal Framework ...................................................................................................... 73 8.1. Main concepts .............................................................................................................. 74 8.2. Traversal Framework Java API ................................................................................... 75 9. Domain Modeling Gallery ...................................................................................................... 82 9.1. User roles in graphs ..................................................................................................... 83 9.2. ACL structures in graphs ............................................................................................. 87 10. Languages ............................................................................................................................. 91 11. Using Neo4j embedded in Python applications .................................................................... 92 11.1. Hello, world! .............................................................................................................. 93 11.2. A sample app using traversals and indexes ............................................................... 94 III. Reference ...................................................................................................................................... 96 12. Capabilities ............................................................................................................................ 97 iii

The Neo4j Manual v1.7 12.1. Data Security ............................................................................................................. 98 12.2. Data Integrity ............................................................................................................. 99 12.3. Data Integration ....................................................................................................... 100 12.4. Availability and Reliability ...................................................................................... 101 12.5. Capacity ................................................................................................................... 102 Transaction Management .................................................................................................... 104 13.1. Interaction cycle ....................................................................................................... 105 13.2. Isolation levels ......................................................................................................... 106 13.3. Default locking behavior ......................................................................................... 107 13.4. Deadlocks ................................................................................................................. 108 13.5. Delete semantics ...................................................................................................... 109 13.6. Creating unique nodes ............................................................................................. 110 13.7. Transaction events ................................................................................................... 112 Data Import ......................................................................................................................... 113 14.1. Batch Insertion ......................................................................................................... 114 Indexing .............................................................................................................................. 117 15.1. Introduction .............................................................................................................. 118 15.2. Create ....................................................................................................................... 119 15.3. Delete ....................................................................................................................... 120 15.4. Add ........................................................................................................................... 121 15.5. Remove .................................................................................................................... 122 15.6. Update ...................................................................................................................... 123 15.7. Search ....................................................................................................................... 124 15.8. Relationship indexes ................................................................................................ 126 15.9. Scores ....................................................................................................................... 127 15.10. Configuration and fulltext indexes ........................................................................ 128 15.11. Extra features for Lucene indexes ......................................................................... 129 15.12. Automatic Indexing ............................................................................................... 131 Cypher Query Language ..................................................................................................... 135 16.1. Operators .................................................................................................................. 137 16.2. Expressions .............................................................................................................. 138 16.3. Parameters ................................................................................................................ 139 16.4. Identifiers ................................................................................................................. 140 16.5. Comments ................................................................................................................ 141 16.6. Start .......................................................................................................................... 142 16.7. Match ....................................................................................................................... 145 16.8. Where ....................................................................................................................... 154 16.9. Return ....................................................................................................................... 159 16.10. Aggregation ............................................................................................................ 162 16.11. Order by ................................................................................................................. 167 16.12. Skip ........................................................................................................................ 169 16.13. Limit ....................................................................................................................... 171 16.14. Functions ................................................................................................................ 172 16.15. Compatibility .......................................................................................................... 182 Graph Algorithms ............................................................................................................... 183 17.1. Introduction .............................................................................................................. 184 Neo4j Server ....................................................................................................................... 185 18.1. Server Installation .................................................................................................... 186 18.2. Server Configuration ................................................................................................ 189 iv

13.

14. 15.

16.

17. 18.

The Neo4j Manual v1.7 18.3. Setup for remote debugging .................................................................................... 18.4. Using the server (including web administration) with an embedded database ......... 18.5. Server Performance Tuning ..................................................................................... 18.6. Server Installation in the Cloud ............................................................................... 19. REST API ........................................................................................................................... 19.1. Service root .............................................................................................................. 19.2. Nodes ....................................................................................................................... 19.3. Relationships ............................................................................................................ 19.4. Relationship types .................................................................................................... 19.5. Node properties ........................................................................................................ 19.6. Relationship properties ............................................................................................ 19.7. Indexes ..................................................................................................................... 19.8. Unique Indexes ........................................................................................................ 19.9. Automatic Indexes ................................................................................................... 19.10. Configurable Automatic Indexing ......................................................................... 19.11. Traversals ............................................................................................................... 19.12. Cypher queries ....................................................................................................... 19.13. Built-in Graph Algorithms ..................................................................................... 19.14. Batch operations ..................................................................................................... 19.15. Cypher Plugin ........................................................................................................ 19.16. Gremlin Plugin ....................................................................................................... 20. Python embedded bindings ................................................................................................. 20.1. Installation ................................................................................................................ 20.2. Core API .................................................................................................................. 20.3. Indexes ..................................................................................................................... 20.4. Cypher Queries ........................................................................................................ 20.5. Traversals ................................................................................................................. IV. Operations ................................................................................................................................... 21. Installation & Deployment ................................................................................................. 21.1. Deployment Scenarios ............................................................................................. 21.2. System Requirements ............................................................................................... 21.3. Installation ................................................................................................................ 21.4. Upgrading ................................................................................................................. 21.5. Usage Data Collector ............................................................................................... 22. Configuration & Performance ............................................................................................ 22.1. Introduction .............................................................................................................. 22.2. Performance Guide .................................................................................................. 22.3. Caches in Neo4j ....................................................................................................... 22.4. JVM Settings ............................................................................................................ 22.5. Compressed storage of short strings ........................................................................ 22.6. Compressed storage of short arrays ......................................................................... 22.7. Memory mapped IO settings ................................................................................... 22.8. Linux Performance Guide ........................................................................................ 22.9. Linux specific notes ................................................................................................. 23. High Availability ................................................................................................................ 23.1. Architecture .............................................................................................................. 23.2. Setup and configuration ........................................................................................... 23.3. How Neo4j HA operates ......................................................................................... 23.4. High Availability setup tutorial ............................................................................... v 191 192 194 195 196 197 198 202 213 214 218 222 228 232 234 238 262 266 274 279 282 301 302 304 309 311 313 317 318 319 320 322 324 326 328 329 330 334 341 344 345 346 348 351 352 353 354 357 358

The Neo4j Manual v1.7 23.5. Setting up HAProxy as a load balancer ................................................................... 24. Backup ................................................................................................................................ 24.1. Embedded and Server .............................................................................................. 24.2. Online Backup from Java ........................................................................................ 24.3. High Availability ..................................................................................................... 24.4. Restoring Your Data ................................................................................................ 25. Security ............................................................................................................................... 25.1. Securing access to the Neo4j Server ....................................................................... 26. Monitoring .......................................................................................................................... 26.1. JMX .......................................................................................................................... V. Tools ............................................................................................................................................. 27. Web Administration ............................................................................................................ 27.1. Dashboard tab .......................................................................................................... 27.2. Data tab .................................................................................................................... 27.3. Console tab .............................................................................................................. 27.4. The Server Info tab .................................................................................................. 28. Neo4j Shell ......................................................................................................................... 28.1. Starting the shell ...................................................................................................... 28.2. Passing options and arguments ................................................................................ 28.3. Enum options ........................................................................................................... 28.4. Filters ....................................................................................................................... 28.5. Node titles ................................................................................................................ 28.6. How to use (individual commands) ......................................................................... 28.7. Extending the shell: Adding your own commands .................................................. 28.8. An example shell session ......................................................................................... 28.9. A Matrix example .................................................................................................... VI. Community ................................................................................................................................. 29. Community Support ............................................................................................................ 30. Contributing to Neo4j ......................................................................................................... 30.1. Contributor License Agreement ............................................................................... 30.2. Writing Neo4j Documentation ................................................................................. 30.3. Areas for contribution .............................................................................................. 30.4. Contributors .............................................................................................................. A. Manpages ..................................................................................................................................... neo4j .......................................................................................................................................... neo4j-shell ................................................................................................................................. neo4j-backup ............................................................................................................................. neo4j-coordinator ...................................................................................................................... neo4j-coordinator-shell .............................................................................................................. B. Questions & Answers .................................................................................................................. 363 366 367 368 369 370 371 372 376 377 383 384 385 386 387 389 390 391 393 394 395 396 397 400 401 402 406 407 408 409 411 422 423 425 426 428 430 432 433 434

vi

List of Figures2.1. RDBMS .......................................................................................................................................... 8 2.2. Graph Database as RDBMS .......................................................................................................... 8 2.3. Key-Value Store ............................................................................................................................ 9 2.4. Graph Database as Key-Value Store ............................................................................................. 9 2.5. Document Store ........................................................................................................................... 10 2.6. Graph Database as Document Store ............................................................................................ 10 4.1. Hello World Graph ...................................................................................................................... 26 4.2. Node space view of users ............................................................................................................ 28 4.3. Matrix node space view .............................................................................................................. 32 4.4. Descendants Example Graph ....................................................................................................... 37 4.5. Social network data model .......................................................................................................... 38 8.1. Traversal Example Graph ............................................................................................................ 79 15.1. Movie and Actor Graph ........................................................................................................... 121 16.1. Example Graph ........................................................................................................................ 135 19.1. Final Graph .............................................................................................................................. 197 19.2. Final Graph .............................................................................................................................. 198 19.3. Final Graph .............................................................................................................................. 198 19.4. Final Graph .............................................................................................................................. 199 19.5. Final Graph .............................................................................................................................. 200 19.6. Final Graph .............................................................................................................................. 200 19.7. Final Graph .............................................................................................................................. 200 19.8. Final Graph .............................................................................................................................. 202 19.9. Final Graph .............................................................................................................................. 203 19.10. Starting Graph ........................................................................................................................ 203 19.11. Final Graph ............................................................................................................................ 204 19.12. Starting Graph ........................................................................................................................ 204 19.13. Final Graph ............................................................................................................................ 205 19.14. Final Graph ............................................................................................................................ 205 19.15. Starting Graph ........................................................................................................................ 206 19.16. Final Graph ............................................................................................................................ 206 19.17. Final Graph ............................................................................................................................ 207 19.18. Starting Graph ........................................................................................................................ 207 19.19. Final Graph ............................................................................................................................ 207 19.20. Final Graph ............................................................................................................................ 208 19.21. Final Graph ............................................................................................................................ 209 19.22. Final Graph ............................................................................................................................ 210 19.23. Final Graph ............................................................................................................................ 211 19.24. Final Graph ............................................................................................................................ 212 19.25. Final Graph ............................................................................................................................ 213 19.26. Final Graph ............................................................................................................................ 214 19.27. Final Graph ............................................................................................................................ 214 19.28. Final Graph ............................................................................................................................ 215 19.29. Final Graph ............................................................................................................................ 215 19.30. Final Graph ............................................................................................................................ 215 19.31. Final Graph ............................................................................................................................ 216 19.32. Starting Graph ........................................................................................................................ 216 19.33. Final Graph ............................................................................................................................ 216 vii

The Neo4j Manual v1.7 19.34. 19.35. 19.36. 19.37. 19.38. 19.39. 19.40. 19.41. 19.42. 19.43. 19.44. 19.45. 19.46. 19.47. 19.48. 19.49. 19.50. 19.51. 19.52. 19.53. 19.54. 19.55. 19.56. 19.57. 19.58. 19.59. 19.60. 19.61. 19.62. 19.63. 19.64. 19.65. 19.66. 19.67. 19.68. 19.69. 19.70. 19.71. 19.72. 19.73. 19.74. 19.75. 19.76. 19.77. 19.78. 19.79. 19.80. 19.81. 19.82. Final Graph ............................................................................................................................ Starting Graph ........................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ Final Graph ............................................................................................................................ viii 218 218 219 219 220 220 222 222 223 223 224 225 225 225 226 227 228 228 229 230 231 232 232 235 236 236 236 237 240 242 243 244 262 263 263 264 265 266 268 270 272 274 276 279 280 280 281 282 283

The Neo4j Manual v1.7 19.83. Final Graph ............................................................................................................................ 19.84. Final Graph ............................................................................................................................ 19.85. Final Graph ............................................................................................................................ 19.86. Final Graph ............................................................................................................................ 19.87. Final Graph ............................................................................................................................ 19.88. Final Graph ............................................................................................................................ 19.89. Final Graph ............................................................................................................................ 19.90. Final Graph ............................................................................................................................ 19.91. Final Graph ............................................................................................................................ 19.92. Final Graph ............................................................................................................................ 19.93. Final Graph ............................................................................................................................ 19.94. Final Graph ............................................................................................................................ 19.95. Final Graph ............................................................................................................................ 19.96. Starting Graph ........................................................................................................................ 19.97. Final Graph ............................................................................................................................ 19.98. Starting Graph ........................................................................................................................ 19.99. Final Graph ............................................................................................................................ 19.100. Final Graph .......................................................................................................................... 23.1. Typical setup when running multiple Neo4j instances in HA mode ....................................... 26.1. Connecting JConsole to the Neo4j Java process ..................................................................... 26.2. Neo4j MBeans View ............................................................................................................... 27.1. Web Administration Dashboard .............................................................................................. 27.2. Entity charting ......................................................................................................................... 27.3. Status indicator panels ............................................................................................................. 27.4. Browsing and manipulating data ............................................................................................. 27.5. Editing properties ..................................................................................................................... 27.6. Traverse data with Gremlin ..................................................................................................... 27.7. Query data with Cypher .......................................................................................................... 27.8. Interact over HTTP .................................................................................................................. 27.9. JMX Attributes ........................................................................................................................ 28.1. Shell Matrix Example .............................................................................................................. 30.1. Hello World Graph .................................................................................................................. 284 286 287 287 288 289 291 292 293 294 295 296 297 298 298 299 299 300 353 378 378 385 385 385 386 386 387 387 388 389 402 419

ix

List of Tables3.1. Using relationship direction and type .......................................................................................... 14 3.2. Property value types .................................................................................................................... 16 6.1. Neo4j REST clients contributed by the community. ................................................................... 60 10.1. Neo4j embedded drivers contributed by the community. .......................................................... 91 15.1. Lucene indexing configuration parameters .............................................................................. 128 18.1. neo4j-wrapper.conf JVM tuning properties ............................................................................. 194 21.1. Neo4j deployment options ....................................................................................................... 319 21.2. Neo4j editions .......................................................................................................................... 322 21.3. Upgrade process for Neo4J version ......................................................................................... 324 22.1. Guidelines for heap size .......................................................................................................... 342 23.1. HighlyAvailableGraphDatabase configuration parameters ...................................................... 355 26.1. MBeans exposed by the Neo4j Kernel .................................................................................... 379 26.2. MBean Memory Mapping ....................................................................................................... 379 26.3. MBean Locking ....................................................................................................................... 379 26.4. MBean Transactions ................................................................................................................ 379 26.5. MBean Cache ........................................................................................................................... 380 26.6. MBean Configuration .............................................................................................................. 380 26.7. MBean Primitive count ............................................................................................................ 381 26.8. MBean XA Resources ............................................................................................................. 381 26.9. MBean Store file sizes ............................................................................................................. 381 26.10. MBean Kernel ........................................................................................................................ 381 26.11. MBean High Availability ...................................................................................................... 382

x

PrefaceThis is the reference manual for Neo4j version 1.7, written by the Neo4j Team. The main parts of the manual are: PartI, Introduction introducing graph database concepts and Neo4j. PartII, Tutorials learn how to use Neo4j. PartIII, Reference detailed information on Neo4j. PartIV, Operations how to install and maintain Neo4j. PartV, Tools guides on tools. PartVI, Community getting help from, contributing to. AppendixA, Manpages command line documentation. AppendixB, Questions & Answers common questions.

The material is practical, technical, and focused on answering specific questions. It addresses how things work, what to do and what to avoid to successfully run Neo4j in a production environment. The goal is to be thumb-through and rule-of-thumb friendly. Each section should stand on its own, so you can hop right to whatever interests you. When possible, the sections distill "rules of thumb" which you can keep in mind whenever you wander out of the house without this manual in your back pocket. The included code examples are executed when Neo4j is built and tested. Also, the REST API request and response examples are captured from real interaction with a Neo4j server. Thus, the examples are always in sync with Neo4j. Who should read this? The topics should be relevant to architects, administrators, developers and operations personnel.

xi

This part gives a birds eye view of what a graph database is, and then outlines some specifics of Neo4j.

PartI.Introduction

Chapter1.Neo4j HighlightsAs a robust, scalable and high-performance database, Neo4j is suitable for full enterprise deployment or a subset of the full server can be used in lightweight projects. It features: true ACID transactions high availability scales to billions of nodes and relationships high speed querying through traversals

Proper ACID behavior is the foundation of data reliability. Neo4j enforces that all mutating operations occur within a transaction, guaranteeing consistent data. This robustness extends from single instance embedded graphs to multi-server high availability installations. For details, see Chapter13, Transaction Management. Reliable graph storage can easily be added to any application. A property graph can scale in size and complexity as the application evolves, with little impact on performance. Whether starting new development, or augmenting existing functionality, Neo4j is only limited by physical hardware. A single server instance can handle a graph of billions of nodes and relationships. When data throughput is insufficient, the graph database can be distributed among multiple servers in a high availability configuration. See Chapter23, High Availability to learn more. The graph database storage shines when storing richly-connected data. Querying is performed through traversals, which can perform millions of traversal steps per second. A traversal step resembles a join in a RDBMS.

2

Chapter2.Graph Database ConceptsThis chapter contains an introduction to the graph data model and also compares it to other data models used when persisting data.

3

Graph Database Concepts

2.1.What is a Graph Database?A graph database stores data in a graph, the most generic of data structures, capable of elegantly representing any kind of data in a highly accessible way. Lets follow along some graphs, using them to express graph concepts. Well read a graph by following arrows around the diagram to form sentences.

2.1.1.A Graph contains Nodes and RelationshipsA Graph records data in Nodes which have Properties The simplest possible graph is a single Node, a record that has named values referred to as Properties. A Node could start with a single Property and grow to a few million, though that can get a little awkward. At some point it makes sense to distribute the data into multiple nodes, organized with explicit Relationships.Graph

records dat a in

records dat a in

Relat ionships

organize

Nodes

have

have

Propert ies

2.1.2.Relationships organize the GraphNodes are organized by Relationships which also have Properties Relationships organize Nodes into arbitrary structures, allowing a Graph to resemble a List, a Tree, a Map, or a compound Entity any of which can be combined into yet more complex, richly interconnected structures.

2.1.3.Query a Graph with a TraversalA Traversal navigates a Graph; it identifies Paths which order Nodes A Traversal is how you query a Graph, navigating from starting Nodes to related Nodes according to an algorithm, finding answers to questions like what music do my friends like that I dont yet own, or if this power supply goes down, what web services are affected? 4

Graph Database Concepts

Traversal

navigat es

ident ifies

expresses

Graph

Algorit hm

records dat a in

Pat hs

Relat ionships

records dat a in

order

organize

Nodes

2.1.4.Indexes look-up Nodes or RelationshipsAn Index maps from Properties to either Nodes or Relationships Often, you want to find a specific Node or Relationship according to a Property it has. Rather than traversing the entire graph, use an Index to perform a look-up, for questions like find the Account for username master-of-graphs.

5

Graph Database Concepts

Indexes

m ap t o

Relat ionships

m ap t o

organize

m ap from

have

Nodes

have

Propert ies

2.1.5.Neo4j is a Graph DatabaseA Graph Database manages a Graph and also manages related Indexes Neo4j is a commercially supported open-source graph database. It was designed and built from the ground-up to be a reliable database, optimized for graph structures instead of tables. Working with Neo4j, your application gets all the expressiveness of a graph, with all the dependability you expect out of a database.

6

Graph Database Concepts

Graph Dat abase

Traversal

m anages

m anages

navigat es

ident ifies

expresses

Indexes

Graph

Algorit hm

m ap t o

records dat a in

Pat hs

m ap t o

Relat ionships

records dat a in

order

m ap from

organize

have

Nodes

have

Propert ies

7

Graph Database Concepts

2.2.Comparing Database ModelsA Graph Database stores data structured in the Nodes and Relationships of a graph. How does this compare to other persistence models? Because a graph is a generic structure, lets compare how a few models would look in a graph.

2.2.1.A Graph Database transforms a RDBMSTopple the stacks of records in a relational database while keeping all the relationships, and youll see a graph. Where an RDBMS is optimized for aggregated data, Neo4j is optimized for highly connected data. Figure2.1.RDBMS

A1 A2 A3

B1 B2 B3 B4

C1 C2 C3

B5 B6 B7

Figure2.2.Graph Database as RDBMSC3 A1 A2 C1 A3 C2

B2

B6

B1

B4

B5

B3

B7

2.2.2.A Graph Database elaborates a Key-Value StoreA Key-Value model is great for lookups of simple values or lists. When the values are themselves interconnected, youve got a graph. Neo4j lets you elaborate the simple data structures into more complex, interconnected data.

8

Graph Database Concepts Figure2.3.Key-Value StoreV1 K2 K1 K2 K3 V2 K1 K3

V3 K1 K*

represents a key, V* a value. Note that some keys point to other keys as well as plain values. Figure2.4.Graph Database as Key-Value Store

K2

V2

K1

V1

V3

K3

2.2.3.A Graph Database relates Column-FamilyColumn Family (BigTable-style) databases are an evolution of key-value, using "families" to allow grouping of rows. Stored in a graph, the families could become hierarchical, and the relationships among data becomes explicit.

2.2.4.A Graph Database navigates a Document StoreThe container hierarchy of a document database accommodates nice, schema-free data that can easily be represented as a tree. Which is of course a graph. Refer to other documents (or document elements) within that tree and you have a more expressive representation of the same data. When in Neo4j, those relationships are easily navigable.

9

Graph Database Concepts Figure2.5.Document StoreD1 S1D2/S2 V1 D1/S1

D2 S3V4 V3

S2V2

D=Document, S=Subdocument, V=Value, D2/S2

= reference to subdocument in (other) document.

Figure2.6.Graph Database as Document StoreD1 V1 V2 S3 S1 S2 V3 V4

D2

10

Chapter3.The Neo4j Graph DatabaseThis chapter goes into more detail on the data model and behavior of Neo4j.

11

The Neo4j Graph Database

3.1.NodesThe fundamental units that form a graph are nodes and relationships. In Neo4j, both nodes and relationships can contain properties. Nodes are often used to represent entities, but depending on the domain relationships may be used for that purpose as well.A Node

can have

can have

Relat ionships

Propert ies

Lets start out with a really simple graph, containing only a single node with one property:nam e: Marko

12

The Neo4j Graph Database

3.2.RelationshipsRelationships between nodes are a key part of a graph database. They allow for finding related data. Just like nodes, relationships can have properties.

A Relat ionship

has a

has a

has a

can have

St art node

End node

Relat ionship t ype

Propert ies

uniquely ident ified by

Nam e

A relationship connects two nodes, and is guaranteed to have valid start and end nodes.relat ionship

St art node

End node

As relationships are always directed, they can be viewed as outgoing or incoming relative to a node, which is useful when traversing the graph:incom ing relat ionship out going relat ionship

Node

Relationships are equally well traversed in either direction. This means that there is no need to add duplicate relationships in the opposite direction (with regard to traversal or performance). While relationships always have a direction, you can ignore the direction where it is not useful in your application. Note that a node can have relationships to itself as well:

Node

loop

To further enhance graph traversal all relationships have a relationship type. Note that the word type might be misleading here, you could rather think of it as a label. The following example shows a simple social network with two relationship types. 13

The Neo4j Graph Database

Maja

Alice

follows

follows

follows

Oscar

blocks

William

Using relationship direction and type What get who a person follows get the followers of a person get who a person blocks get who a person is blocked by How outgoing follows relationships, depth one incoming follows relationships, depth one outgoing blocks relationships, depth one incoming blocks relationships, depth one

This example is a simple model of a file system, which includes symbolic links:/

A

file

file

B

C

sym bolic link { nam e: " E" }

file

D

Depending on what you are looking for, you will use the direction and type of relationships during traversal. 14

The Neo4j Graph Database What get the full path of a file get all paths for a file get all files in a directory get all files in a directory, excluding symbolic links get all files in a directory, recursively How incoming file relationships incoming file and symbolic link relationships outgoing file and symbolic link relationships, depth one outgoing file relationships, depth one outgoing file and symbolic link relationships

15

The Neo4j Graph Database

3.3.PropertiesBoth nodes and relationships can have properties. Properties are key-value pairs where the key is a string. Property values can be either a primitive or an array of one primitive type. For example String, int and int[] values are valid for properties.

Notenull

is not a valid property value. Nulls can instead be modeled by the absence of a key.

A Propert y

has a

has a

Value

Key

can be an array of can be a

is a

boolean byt e short int Prim it ive long float double char St ring

Property value types Typeboolean byte short int long float double

Description 8-bit integer 16-bit integer 32-bit integer 64-bit integer 32-bit IEEE 754 floating-point number 64-bit IEEE 754 floating-point number 16

Value rangetrue/false -128

to 127, inclusive to 32767, inclusive to 2147483647, inclusive

-32768

-2147483648

-9223372036854775808 to 9223372036854775807, inclusive

The Neo4j Graph Database Typechar String

Description 16-bit unsigned integers representing Unicode characters sequence of Unicode characters

Value rangeu0000

to uffff (0 to 65535)

For further details on float/double values, see Java Language Specification .

17

The Neo4j Graph Database

3.4.PathsA path is one or more nodes with connecting relationships, typically retrieved as a query or traversal result.A Pat h

has a can cont ain one or m ore

has an

St art Node

Relat ionship

End Node

accom panied by a

Node

The shortest possible path has length zero and looks like this:Node

A path of length one:Node 1

Relat ionship 1

Node 2

18

The Neo4j Graph Database

3.5.TraversalTraversing a graph means visiting its nodes, following relationships according to some rules. In most cases only a subgraph is visited, as you already know where in the graph the interesting nodes and relationships are found. Neo4j comes with a callback based traversal API which lets you specify the traversal rules. At a basic level theres a choice between traversing breadth- or depth-first. For an in-depth introduction to the traversal framework, see Chapter8, The Traversal Framework. For Java code examples see Section4.5, Traversal. Other options to traverse or query graphs in Neo4j are Cypher and Gremlin.

19

The tutorial part describes how to set up your environment, and write programs using Neo4j. It takes you from Hello World to advanced usage of graphs.

PartII.Tutorials

Chapter4.Using Neo4j embedded in Java applicationsIts easy to use Neo4j embedded in Java applications. In this chapter you will find everything needed from setting up the environment to doing something useful with your data.

21

Using Neo4j embedded in Java applications

4.1.Include Neo4j in your projectAfter selecting the appropriate edition for your platform, embed Neo4j in your Java application by including the Neo4j library jars in your build. The following sections will show how to do this by either altering the build path directly or by using dependency management.

4.1.1.Add Neo4j to the build pathGet the Neo4j libraries from one of these sources: Extract a Neo4j download zip/tarball, and use the jar files found in the lib/ directory. Use the jar files available from Maven Central Repository Add the jar files to your project: JDK tools Append to -classpath Eclipse Right-click on the project and then go Build Path Configure Build Path. In the dialog, choose Add External JARs, browse to the Neo4j lib/ directory and select all of the jar files. Another option is to use User Libraries . IntelliJ IDEA See Libraries, Global Libraries, and the Configure Library dialog NetBeans Right-click on the Libraries node of the project, choose Add JAR/Folder, browse to the Neo4j lib/ directory and select all of the jar files. You can also handle libraries from the project node, see Managing a Projects Classpath .

4.1.2.Add Neo4j as a dependencyFor an overview of the main Neo4j artifacts, see Neo4j editions. The artifacts listed there are top-level artifacts that will transitively include the actual Neo4j implementation. You can either go with the toplevel artifact or include the individual components directly. The examples included here use the toplevel artifact approach. Maven Maven dependency. ... org.neo4jneo4j${neo4j-version} ...

22

Using Neo4j embedded in Java applications ...

Where ${neo4j-version} is the desired version and the artifactId is found in Neo4j editions. Eclipse and Maven For development in Eclipse , it is recommended to install the M2Eclipse plugin and let Maven manage the project build classpath instead, see above. This also adds the possibility to build your project both via the command line with Maven and have a working Eclipse setup for development. Ivy Make sure to resolve dependencies from Maven Central, for example using this configuration in your ivysettings.xml file:

With that in place you can add Neo4j to the mix by having something along these lines to your ivy.xml file:.. .. .. ..

Where ${neo4j-version} is the desired version and the name is found in Neo4j editions. Gradle The example below shows an example gradle build script for including the Neo4j libraries.def neo4jVersion = "[set-version-here]" apply plugin: 'java' repositories { mavenCentral() } dependencies { compile "org.neo4j:neo4j:${neo4jVersion}" }

Where neo4jVersion is the desired version and the name ("neo4j" in the example) is found in Neo4j editions.

4.1.3.Starting and stoppingTo create a new database or pen an existing one you instantiate an EmbeddedGraphDatabase . 23

Using Neo4j embedded in Java applicationsgraphDb = new GraphDatabaseFactory().newEmbeddedDatabase( DB_PATH ); registerShutdownHook( graphDb );

Note

The EmbeddedGraphDatabase instance can be shared among multiple threads. Note however that you cant create multiple instances pointing to the same database. To stop the database, call the shutdown() method:graphDb.shutdown();

To make sure Neo4j is shut down properly you can add a shutdown hook:private static void registerShutdownHook( final GraphDatabaseService graphDb ) { // Registers a shutdown hook for the Neo4j instance so that it // shuts down nicely when the VM exits (even if you "Ctrl-C" the // running example before it's completed) Runtime.getRuntime().addShutdownHook( new Thread() { @Override public void run() { graphDb.shutdown(); } } ); }

If you want a read-only view of the database, use EmbeddedReadOnlyGraphDatabase .

To start Neo4j with configuration settings, a Neo4j properties file can be loaded like this:GraphDatabaseService graphDb = new GraphDatabaseFactory(). newEmbeddedDatabaseBuilder( "target/database/location" ). loadPropertiesFromFile( pathToConfig + "neo4j.properties" ). newGraphDatabase();

Or you could of course create you own Map programatically and use that instead. For configuration settings, see Chapter22, Configuration & Performance.

24

Using Neo4j embedded in Java applications

4.2.Hello World

Learn how to create and access nodes and relationships. For information on project setup, see Section4.1, Include Neo4j in your project. Remember, from Section2.1, What is a Graph Database?, that a Neo4j graph consist of: Nodes that are connected by Relationships, with Properties on both nodes and relationships. All relationships have a type. For example, if the graph represents a social network, a relationship type could be KNOWS. If a relationship of the type KNOWS connects two nodes, that probably represents two people that know each other. A lot of the semantics (that is the meaning) of a graph is encoded in the relationship types of the application. And although relationships are directed they are equally well traversed regardless of which direction they are traversed.

Tip

The source code of this example is found here: EmbeddedNeo4j.java

4.2.1.Prepare the databaseRelationship types can be created by using an enum. In this example we only need a single relationship type. This is how to define it:private static enum RelTypes implements RelationshipType { KNOWS }

We also prepare some variables to use:GraphDatabaseService graphDb; Node firstNode; Node secondNode; Relationship relationship;

The next step is to start the database server. Note that if the directory given for the database doesnt already exist, it will be created.graphDb = new GraphDatabaseFactory().newEmbeddedDatabase( DB_PATH ); registerShutdownHook( graphDb );

Note that starting a database server is an expensive operation, so dont start up a new instance every time you need to interact with the database! The instance can be shared by multiple threads. Transactions are thread confined. As seen, we register a shutdown hook that will make sure the database shuts down when the JVM exits. Now its time to interact with the database.

4.2.2.Wrap mutating operations in a transactionAll mutating transactions have to be performed in a transaction. This is a conscious design decision, since we believe transaction demarcation to be an important part of working with a real enterprise database. Now, transaction handling in Neo4j is very easy:Transaction tx = graphDb.beginTx();

25

Using Neo4j embedded in Java applicationstry { // Mutating operations go here tx.success(); } finally { tx.finish(); }

For more information on transactions, see Chapter13, Transaction Management and Java API for Transaction .

4.2.3.Create a small graphNow, lets create a few nodes. The API is very intuitive. Feel free to have a look at the JavaDocs at http://components.neo4j.org/neo4j/1.7/apidocs/. Theyre included in the distribution, as well. Heres how to create a small graph consisting of two nodes, connected with one relationship and some properties:firstNode = graphDb.createNode(); firstNode.setProperty( "message", "Hello, " ); secondNode = graphDb.createNode(); secondNode.setProperty( "message", "World!" ); relationship = firstNode.createRelationshipTo( secondNode, RelTypes.KNOWS ); relationship.setProperty( "message", "brave Neo4j " );

We now have a graph that looks like this: Figure4.1.Hello World Graphm essage = 'Hello, '

KNOWS m essage = 'brave Neo4j '

m essage = 'World! '

4.2.4.Print the resultAfter weve created our graph, lets read from it and print the result.System.out.print( firstNode.getProperty( "message" ) ); System.out.print( relationship.getProperty( "message" ) ); System.out.print( secondNode.getProperty( "message" ) );

Which will output: Hello, brave Neo4j World!

4.2.5.Remove the dataIn this case well remove the data before committing:// let's remove the data firstNode.getSingleRelationship( RelTypes.KNOWS, Direction.OUTGOING ).delete();

26

Using Neo4j embedded in Java applicationsfirstNode.delete(); secondNode.delete();

Note that deleting a node which still has relationships when the transaction commits will fail. This is to make sure relationships always have a start node and an end node.

4.2.6.Shut down the database serverFinally, shut down the database server when the application finishes:graphDb.shutdown();

27

Using Neo4j embedded in Java applications

4.3.User database with indexYou have a user database, and want to retrieve users by name. To begin with, this is the structure of the database we want to create: Figure4.2.Node space view of users

That is, the reference node is connected to a users-reference node to which all users are connected.

Tip

The source code used in this example is found here: EmbeddedNeo4jWithIndexing.java To begin with, we define the relationship types we want to use:private static enum RelTypes implements RelationshipType { USERS_REFERENCE, USER }

Then we have created two helper methods to handle user names and adding users to the database:private static String idToUserName( final int id ) { return "user" + id + "@neo4j.org"; } private static Node createAndIndexUser( final String username ) { Node node = graphDb.createNode(); node.setProperty( USERNAME_KEY, username ); nodeIndex.add( node, USERNAME_KEY, username ); return node; }

The next step is to start the database server:graphDb = new GraphDatabaseFactory().newEmbeddedDatabase( DB_PATH ); nodeIndex = graphDb.index().forNodes( "nodes" ); registerShutdownHook();

28

Using Neo4j embedded in Java applications Its time to add the users:Transaction tx = graphDb.beginTx(); try { // Create users sub reference node Node usersReferenceNode = graphDb.createNode(); graphDb.getReferenceNode().createRelationshipTo( usersReferenceNode, RelTypes.USERS_REFERENCE ); // Create some users and index their names with the IndexService for ( int id = 0; id < 100; id++ ) { Node userNode = createAndIndexUser( idToUserName( id ) ); usersReferenceNode.createRelationshipTo( userNode, RelTypes.USER ); }

And heres how to find a user by Id:int idToFind = 45; Node foundUser = nodeIndex.get( USERNAME_KEY, idToUserName( idToFind ) ).getSingle(); System.out.println( "The username of user " + idToFind + " is " + foundUser.getProperty( USERNAME_KEY ) );

29

Using Neo4j embedded in Java applications

4.4.Basic unit testingThe basic pattern of unit testing with Neo4j is illustrated by the following example. To access the Neo4j testing facilities you should have the neo4j-kernel tests.jar on the classpath during tests. You can download it from Maven Central: org.neo4j:neo4j-kernel . Using Maven as a dependency manager you would typically add this dependency as: Maven dependency. ... org.neo4jneo4j-kernel${neo4j-version}test-jartest ... ...

Where ${neo4j-version} is the desired version of Neo4j. With that in place, were ready to code our tests.

Tip

For the full source code of this example see: Neo4jBasicTest.java Before each test, create a fresh database:@Before public void prepareTestDatabase() { graphDb = new TestGraphDatabaseFactory().newImpermanentDatabaseBuilder().newGraphDatabase(); }

After the test has executed, the database should be shut down:@After public void destroyTestDatabase() { graphDb.shutdown(); }

During a test, create nodes and check to see that they are there, while enclosing write operations in a transaction.Transaction tx = graphDb.beginTx(); Node n = null; try { n = graphDb.createNode(); n.setProperty( "name", "Nancy" ); tx.success();

30

Using Neo4j embedded in Java applications} catch ( Exception e ) { tx.failure(); } finally { tx.finish(); } // The node should have an id greater than 0, which is the id of the // reference node. assertThat( n.getId(), is( greaterThan( 0l ) ) ); // Retrieve a node by using the id of the created node. The id's and // property should match. Node foundNode = graphDb.getNodeById( n.getId() ); assertThat( foundNode.getId(), is( n.getId() ) ); assertThat( (String) foundNode.getProperty( "name" ), is( "Nancy" ) );

If you want to set configuration parameters at database creation, its done like this:Map config = new HashMap(); config.put( "neostore.nodestore.db.mapped_memory", "10M" ); config.put( "string_block_size", "60" ); config.put( "array_block_size", "300" ); GraphDatabaseService db = new ImpermanentGraphDatabase( config );

31

Using Neo4j embedded in Java applications

4.5.TraversalFor reading about traversals, see Chapter8, The Traversal Framework. For more examples of traversals, see Chapter9, Domain Modeling Gallery.

4.5.1.The MatrixThis is the first node space we want to traverse into: Figure4.3.Matrix node space view

Tip

The source code of the examples is found here: Matrix.java Friends and friends of friends.private static Traverser getFriends( final Node person ) { return person.traverse( Order.BREADTH_FIRST, StopEvaluator.END_OF_GRAPH, ReturnableEvaluator.ALL_BUT_START_NODE, RelTypes.KNOWS, Direction.OUTGOING ); }

Lets perform the actual traversal and print the results:int numberOfFriends = 0; String output = neoNode.getProperty( "name" ) + "'s friends:\n"; Traverser friendsTraverser = getFriends( neoNode ); for ( Node friendNode : friendsTraverser ) { output += "At depth " + friendsTraverser.currentPosition().depth() + " => " + friendNode.getProperty( "name" ) + "\n"; numberOfFriends++; } output += "Number of friends found: " + numberOfFriends + "\n";

Which will give us the following output: 32

Using Neo4j embedded in Java applicationsThomas Anderson's friends: At depth 1 => Trinity At depth 1 => Morpheus At depth 2 => Cypher At depth 3 => Agent Smith Number of friends found: 4

Who coded the Matrix?private static Traverser findHackers( final Node startNode ) { return startNode.traverse( Order.BREADTH_FIRST, StopEvaluator.END_OF_GRAPH, new ReturnableEvaluator() { @Override public boolean isReturnableNode( final TraversalPosition currentPos ) { return !currentPos.isStartNode() && currentPos.lastRelationshipTraversed() .isType( RelTypes.CODED_BY ); } }, RelTypes.CODED_BY, Direction.OUTGOING, RelTypes.KNOWS, Direction.OUTGOING ); }

Print out the result:String output = "Hackers:\n"; int numberOfHackers = 0; Traverser traverser = findHackers( getNeoNode() ); for ( Node hackerNode : traverser ) { output += "At depth " + traverser.currentPosition().depth() + " => " + hackerNode.getProperty( "name" ) + "\n"; numberOfHackers++; } output += "Number of hackers found: " + numberOfHackers + "\n";

Now we know who coded the Matrix:Hackers: At depth 4 => The Architect Number of hackers found: 1

4.5.2.New traversal framework NoteThe following examples use a new experimental traversal API. It shares the underlying implementation with the old traversal API, so performance-wise they should be equal. However, expect the new API to evolve and thus undergo changes. The Matrix The traversals from the Matrix example above, this time using the new traversal API:

Tip

The source code of the examples is found here: NewMatrix.java 33

Using Neo4j embedded in Java applications Friends and friends of friends.private static Traverser getFriends( final Node person ) { TraversalDescription td = Traversal.description() .breadthFirst() .relationships( RelTypes.KNOWS, Direction.OUTGOING ) .evaluator( Evaluators.excludeStartPosition() ); return td.traverse( person ); }

Lets perform the actual traversal and print the results:int numberOfFriends = 0; String output = neoNode.getProperty( "name" ) + "'s friends:\n"; Traverser friendsTraverser = getFriends( neoNode ); for ( Path friendPath : friendsTraverser ) { output += "At depth " + friendPath.length() + " => " + friendPath.endNode() .getProperty( "name" ) + "\n"; numberOfFriends++; } output += "Number of friends found: " + numberOfFriends + "\n";

Which will give us the following output:Thomas Anderson's friends: At depth 1 => Trinity At depth 1 => Morpheus At depth 2 => Cypher At depth 3 => Agent Smith Number of friends found: 4

Who coded the Matrix?private static Traverser findHackers( final Node startNode ) { TraversalDescription td = Traversal.description() .breadthFirst() .relationships( RelTypes.CODED_BY, Direction.OUTGOING ) .relationships( RelTypes.KNOWS, Direction.OUTGOING ) .evaluator( Evaluators.returnWhereLastRelationshipTypeIs( RelTypes.CODED_BY ) ); return td.traverse( startNode ); }

Print out the result:String output = "Hackers:\n"; int numberOfHackers = 0; Traverser traverser = findHackers( getNeoNode() ); for ( Path hackerPath : traverser ) { output += "At depth " + hackerPath.length() + " => " + hackerPath.endNode() .getProperty( "name" ) + "\n"; numberOfHackers++; } output += "Number of hackers found: " + numberOfHackers + "\n";

Now we know who coded the Matrix:Hackers: At depth 4 => The Architect

34

Using Neo4j embedded in Java applicationsNumber of hackers found: 1

Walking an ordered path This example shows how to use a path context holding a representation of a path.

Tip

The source code of this example is found here: OrderedPath.java Create a toy graph.Node A = db.createNode(); Node B = db.createNode(); Node C = db.createNode(); Node D = db.createNode(); A.createRelationshipTo( B, B.createRelationshipTo( C, C.createRelationshipTo( D, A.createRelationshipTo( C,

REL1 REL2 REL3 REL2

); ); ); );

A

REL1

B

REL2

REL2

C

REL3

D

Now, the order of relationships (REL1 REL2 REL3) is stored in an ArrayList. Upon traversal, the Evaluator can check against it to ensure that only paths are included and returned that have the predefined order of relationships: Define how to walk the path.final ArrayList orderedPathContext = new ArrayList(); orderedPathContext.add( REL1 ); orderedPathContext.add( withName( "REL2" ) ); orderedPathContext.add( withName( "REL3" ) ); TraversalDescription td = Traversal.description()

35

Using Neo4j embedded in Java applications.evaluator( new Evaluator() { @Override public Evaluation evaluate( final Path path ) { if ( path.length() == 0 ) { return Evaluation.EXCLUDE_AND_CONTINUE; } RelationshipType expectedType = orderedPathContext.get( path.length() - 1 ); boolean isExpectedType = path.lastRelationship() .isType( expectedType ); boolean included = path.length() == orderedPathContext.size() && isExpectedType; boolean continued = path.length() < orderedPathContext.size() && isExpectedType; return Evaluation.of( included, continued ); } } );

Perform the traversal and print the result.Traverser traverser = td.traverse( A ); PathPrinter pathPrinter = new PathPrinter( "name" ); for ( Path path : traverser ) { output += Traversal.pathToString( path, pathPrinter ); }

Which will output:(A)--[REL1]-->(B)--[REL2]-->(C)--[REL3]-->(D)

In this case we use a custom class to format the path output. This is how its done:static class PathPrinter implements Traversal.PathDescriptor { private final String nodePropertyKey; public PathPrinter( String nodePropertyKey ) { this.nodePropertyKey = nodePropertyKey; } @Override public String nodeRepresentation( Path path, Node node ) { return "(" + node.getProperty( nodePropertyKey, "" ) + ")"; } @Override public String relationshipRepresentation( Path path, Node from, Relationship relationship ) { String prefix = "--", suffix = "--"; if ( from.equals( relationship.getEndNode() ) ) { prefix = ""; } return prefix + "[" + relationship.getType().name() + "]" + suffix; } }

36

Using Neo4j embedded in Java applications For options regarding output of a Path, see the Traversal class.

4.5.3.Uniqueness of Paths in traversalsThis example is demonstrating the use of node uniqueness. Below an imaginary domain graph with Principals that own pets that are descendant to other pets. Figure4.4.Descendants Example GraphNode[ 5] nam e = 'Principal1' Node[ 3] nam e = 'Pet 0' Node[ 6] nam e = 'Principal2'

owns

owns

descendant

descendant

descendant

owns

Node[ 1] nam e = 'Pet 1'

Node[ 4] nam e = 'Pet 3'

Node[ 2] nam e = 'Pet 2'

In order to return all descendants of Pet0 which have the relation owns to Principal1 (Pet1 and Pet3), the Uniqueness of the traversal needs to be set to NODE_PATH rather than the default NODE_GLOBAL so that nodes can be traversed more that once, and paths that have different nodes but can have some nodes in common (like the start and end node) can be returned.final Node target = data.get().get( "Principal1" ); TraversalDescription td = Traversal.description() .uniqueness( Uniqueness.NODE_PATH ) .evaluator( new Evaluator() { @Override public Evaluation evaluate( Path path ) { if ( path.endNode().equals( target ) ) { return Evaluation.INCLUDE_AND_PRUNE; } return Evaluation.EXCLUDE_AND_CONTINUE; } } ); Traverser results = td.traverse( start );

This will return the following paths:(3)--[descendant,0]-->(1)(4)(4) denotes a node with ID=1 having a relationship with ID 2 or type knows to a node with ID-4. Lets create a new TraversalDescription from the old one, having NODE_GLOBAL uniqueness to see the difference.

Tip

The TraversalDescription object is immutable, so we have to use the new instance returned with the new uniqueness setting.TraversalDescription nodeGlobalTd = td.uniqueness( Uniqueness.NODE_GLOBAL );

37

Using Neo4j embedded in Java applicationsresults = nodeGlobalTd.traverse( start );

Now only one path is returned:(3)--[descendant,0]-->(1)"reference node"} | "reference node" | +----------------------------------------------------+ 1 row, 0 ms

Caution

The classes used here are from the org.neo4j.cypher.javacompat package, not org.neo4j.cypher, see link to the Java API below. You can get a list of the columns in the result:List columns = result.columns(); System.out.println( columns );

This outputs:[n, n.name]

To fetch the result items in a single column, do like this:Iterator n_column = result.columnAs( "n" ); for ( Node node : IteratorUtil.asIterable( n_column ) ) { // note: we're grabbing the name property from the node, // not from the n.name in this case. nodeResult = node + ": " + node.getProperty( "name" ); System.out.println( nodeResult ); }

In this case theres only one node in the result:Node[0]: reference node

45

Using Neo4j embedded in Java applications To get all columns, do like this instead:for ( Map row : result ) { for ( Entry column : row.entrySet() ) { rows += column.getKey() + ": " + column.getValue() + "; "; } rows += "\n"; } System.out.println( rows );

This outputs:n: Node[0]; n.name: reference node;

For more information on the Java interface to Cypher, see the Java API . For more information and examples for Cypher, see Chapter16, Cypher Query Language and Chapter5, Cypher Cookbook.

46

Chapter5.Cypher CookbookThe following cookbook aims to provide a few snippets, examples and use-cases and their querysolutions in Cypher. For the Cypher reference documentation, see Chapter16, Cypher Query Language.

47

Cypher Cookbook

5.1.Hyperedges and CypherImagine a user being part of different groups. A group can have different roles, and a user can be part of different groups. He also can have different roles in different groups apart from the membership. The association of a User, a Group and a Role can be referred to as a HyperEdge. However, it can be easily modeled in a property graph as a node that captures this n-ary relationship, as depicted below in the U1G2R1 node. Graph

nam e = 'User1'

hasRoleInGroup

hasRoleInGroup

nam e = 'U1G2R1'

in

in

nam e = 'U1G1R2'

hasGroup

hasGroup

hasRole

nam e = 'Group2'

nam e = 'Group1'

hasRole

canHave

isA

canHave

canHave

isA

canHave

nam e = 'Role1'

nam e = 'Group'

nam e = 'Role2'

isA

isA

nam e = 'Role'

5.1.1.Find GroupsTo find out in what roles a user is for a particular groups (here Group2), the following Cypher Query can traverse this HyperEdge node and provide answers. QuerySTART n=node:node_auto_index(name = "User1") MATCH n-[:hasRoleInGroup]->hyperEdge-[:hasGroup]->group, hyperEdge-[:hasRole]->role WHERE group.name = "Group2" RETURN role.name

The role of User1:

48

Cypher Cookbook Result role.name"Role1"

1 row, 1 ms

5.1.2.Find all groups and roles for a userHere, find all groups and the roles a user has, sorted by the roles names. QuerySTART n=node:node_auto_index(name = "User1") MATCH n-[:hasRoleInGroup]->hyperEdge-[:hasGroup]->group, hyperEdge-[:hasRole]->role RETURN role.name, group.name ORDER BY role.name asc

The groups and roles of User1 Result role.name"Role1" "Role2"

group.name"Group2" "Group1"

2 rows, 0 ms

5.1.3.Find common groups based on shared rolesAssume you have a more complicated graph: 1. 2. 3. 4. 5. 2 user nodes User1, User2 User1 is in Group1, Group2, Group3. User1 has Role1, Role2 in Group1; Role2, Role3 in Group2; Role3, Role4 in Group3 (hyper edges) User2 is in Group1, Group2, Group3 User2 has Role2, Role5 in Group1; Role3, Role4 in Group2; Role5, Role6 in Group3 (hyper edges)

The graph for this looks like the following (nodes like U1G2R23 representing the HyperEdges): GraphNode[ 3] nam e = 'User2' Node[ 4] nam e = 'User1'

hasRoleInGroup

hasRoleInGroup

hasRoleInGroup

hasRoleInGroup

hasRoleInGroup

hasRoleInGroup

Node[ 1] nam e = 'U2G2R34'

Node[ 6] nam e = 'U1G2R23'

Node[ 2] nam e = 'U1G3R34'

Node[ 17] nam e = 'U2G3R56'

Node[ 9] nam e = 'U2G1R25'

Node[ 15] nam e = 'U1G1R12'

hasGroup

hasGroup

hasRole

hasRole

hasRole

hasRole

hasRole

hasGroup

hasGroup

hasRole

hasRole

hasRole

hasRole

hasRole

hasRole

hasGroup

hasGroup

hasRole

Node[ 12] nam e = 'Group2'

Node[ 13] nam e = 'Role3'

Node[ 7] nam e = 'Role4'

Node[ 14] nam e = 'Group3'

Node[ 5] nam e = 'Role6'

Node[ 8] nam e = 'Role5'

Node[ 11] nam e = 'Role2'

Node[ 10] nam e = 'Group1'

Node[ 16] nam e = 'Role1'

To return Group1 and Group2 as User1 and User2 share at least one common role in those 2 groups, the cypher query looks like: QuerySTART u1=node:node_auto_index(name = "User1"),u2=node:node_auto_index(name = "User2") MATCH u1-[:hasRoleInGroup]->hyperEdge1-[:hasGroup]->group, hyperEdge1-[:hasRole]->role,

49

Cypher Cookbooku2-[:hasRoleInGroup]-