As Spring Data Neo4j uses some advanced features of AspectJ, users may experience issues with their IDE reporting errors where in fact there are none. Features that might be reported wrongfully include: introduction of methods to interfaces, declaration of additional interfaces for annotated classes, and generified introduced methods.

IDEs not providing full AspectJ support might mark parts of your code as having errors. You should rely on your build-system and tests to verify the correctness of the code. You might also have your Entities (or their interfaces) implement the NodeBacked and RelationshipBacked interfaces directly to benefit from completion support and error checking.

Eclipse and STS support AspectJ via the AJDT plugin which can be installed from the update-site listed at http://www.eclipse.org/ajdt/downloads/ (it might be necessary to use the latest development snapshot of the plugin). The current version that does not show incorrect errors is AspectJ 1.6.12 (included in STS 2.8.0), previous versions are reported to mislead the user. Note that AJDT (as of September 2012) requires projects to be rebuild after Eclipse is started to fully support all advanced features.

Note

There might be some issues with the eclipse maven plugin not adding AspectJ files correctly to the build path. If you encounter issues, please try the following: Try editing the build path to include **/*.aj for the spring-data-neo4j-aspects project. You can do this by selecting "Build Path -> Configure Build Path ..." from the Package Explorer. Then for the spring-data-neo4j-aspects/src/main/java add **/*.aj to the Included path. When importing a Spring Data Neo4j project into Eclipse with m2e, please make sure the AspectJ Configurator is installed from the following update-site: http://dist.springsource.org/release/AJDT/configurator

The AspectJ support in IntelliJ IDEA lacks some of the features. JetBrains is working on improving 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.

The @NodeEntity annotation is used to turn a POJO class into an entity backed by a node in the graph database. Fields on the entity are by default mapped to properties of the node. Fields referencing other node entities (or collections thereof) are linked with relationships. If the useShortNames attribute is set to false, the property and relationship names will have the class name of the entity prepended.

@NodeEntity annotations are inherited from super-types and interfaces. It is not necessary to annotate your domain objects at every inheritance level.

If the partial attribute is set to true, this entity takes part in a cross-store setting, where the entity lives in both the graph database and a JPA data source. See Chapter 22, Cross-store persistence for more information.

Entity fields can be annotated with @GraphProperty, @RelatedTo, @RelatedToVia, @Indexed, @GraphId, @Query and @GraphTraversal.

@NodeEntity
public class Movie {
    String title;
}

For the simple mapping this is a required field which must be of type Long. It is used by Spring Data Neo4j to store the node or relationship-id to re-connect the entity to the graph.

	Note
	It must not be a primitive type because then the "non-attached" case can not be represented as the default value 0 would point to the reference node. Please make also sure that an equals() and hashCode() method have to be provided which take the id field into account (and also handle the "non-attached", null case).

For the advanced mapping such a field is optional. Only if the underlying id has to be accessed, it is needed.

Entity Equality

Entity equality can be a grey area, and it is debatable whether natural keys or database ids best describe equality, there is the issue of versioning over time, etc. For Spring Data Neo4j we have adopted the convention that database-issued ids are the basis for equality, and that has some consequences:

1. Before you attach an entity to the database, i.e. before the entity has had its id-field populated, we suggest you rely on object identity for comparisons
2. Once an entity is attached, we suggest you rely solely on the id-field for equality
3. When you attach an entity, its hashcode changes - because you keep equals and hashcode consistent and rely on the database ID, and because Spring Data Neo4j populates the database ID on save

That causes problems if you had inserted the newly created entity into a hash-based collection before saving. While that can be worked around, we strongly advise you adopt a convention of not working with un-attached entities, to keep your code simple. This is best illustrated in code.

Example 20.3. Entity using id-field for equality and attaching new entity immediately

@NodeEntity
public class Studio {
    @GraphId
    Long id

    String name;

    public boolean equals(Object other) {
        if (this == other) return true;

        if (id == null) return false;

        if (! (other instanceof Studio)) return false;

        return id.equals(((Studio) other).id);
    }

    public int hashCode() {
        return id == null ? System.identityHashCode(this) : id.hashCode();
    }
}

...
Set<Studio> studios = new HashSet<Studio>();
Studio studio = studioRepository.save(new Studio("Ghibli"));
studios.add(studio);
Studio sameStudio = studioRepository.findOne(studio.id);
assertThat(studio, is(equalTo(sameStudio));
assertThat(studios.contains(sameStudio), is(true);
assertThat(studios.remove(sameStudio), is(true);

A work-around for the problem of un-attached entities having their hashcode change when they get saved is to cache the hashcode. The hashcode will change next time you load the entity, but at least if you have the entity sitting in a collection, you will still be able to find it:

Example 20.4. Caching hashcode

@NodeEntity
public class Studio {
    @GraphId
    Long id

    String name;

    transient private Integer hash;

    public boolean equals(Object other) {
        if (this == other) return true;

        if (id == null) return false;

        if (! (other instanceof Studio)) return false;

        return id.equals(((Studio) other).id);
    }

    public int hashCode() {
        if (hash == null) hash = id == null ? System.identityHashCode(this) : id.hashCode();

        return hash.hashCode();
    }
}

...
Set<Studio> studios = new HashSet<Studio>();
Studio studio = new Studio("Ghibli")
studios.add(studio);
studioRepository.save(studio);
assertThat(studios.contains(studio), is(true);
assertThat(studios.remove(studio), is(true);
Studio sameStudio = studioRepository.findOne(studio.id);
assertThat(studio, is(equalTo(sameStudio));
assertThat(studio.hashCode(), is(not(equalTo(sameStudio.hashCode())));

	Note
	Remember, transient fields are not saved.

It is not necessary to annotate property fields, as they are persisted by default; all fields that contain primitive values are persisted directly to the graph. All fields convertible to a String using the Spring conversion services will be stored as a string. Spring Data Neo4j includes a custom conversion factory that comes with converters for Enums and Dates. Transient fields are not persisted.

Collections of collections of primitive or convertable values are stored as well. They are converted to arrays of their type or strings respectively.

This annotation is typically used with cross-store persistence. When a node entity is configured as partial, then all fields that should be persisted to the graph must be explicitly annotated with @GraphProperty.

@GraphProperty can specify default values for properties that are not in the graph. Default values are specified as String representations and will be converted to the correct target type using the existing conversion facilities. For example @GraphProperty(defaultValue="20") Integer age.

It is also possible to declare the type that should be used for the storage inside of Neo4j. For instance if a Date property should be stored as an Long value instead of the default String, the annotation would look like @GraphProperty(propertyType = Long.class) For the actual mapping of the Field-Type to the Neo4j-Property type there has to be a Converter registered in the Spring-Config.

The @Indexed annotation can be declared on fields that are intended to be indexed by the Neo4j indexing facilities. The resulting index can be used to later retrieve nodes or relationships that contain a certain property value, e.g. a name. Often an index is used to establish the start node for a traversal. Indexes are accessed by a repository for a particular node or relationship entity type. See Section 20.6, “Indexing” and Section 20.8, “CRUD with repositories” for more information.

The @Query annotation leverages the delegation infrastructure supported by Spring Data Neo4j. It provides dynamic fields which, when accessed, return the values selected by the provided query language expression. The provided query must contain a placeholder named {self} for the the current entity. For instance the query start n=node({self}) match n-[:FRIEND]->friend return friend. Graph queries can return variable number of entities. That's why annotation can be put onto fields with a single value, a subclass of Iterable of a concrete type or an Iterable of Map<String,Object>. Additional parameters are taken from the params attribute of the @Query annotation. These parameter tuples form key-value pairs that are provided to the query at execution time.

@NodeEntity
public class Group {
    @Query(value = "start n=node({self}) match (n)-[r]->(friend) where r.type = {relType} return friend",
                params = {"relType", "FRIEND"})
    private Iterable<Person> friends;
}

	Note
	Please note that this annotation can also be used on repository methods. (Section 20.8, “CRUD with repositories”)

The @GraphTraversal annotation also leverages the delegation infrastructure supported by Spring Data aspects. It provides dynamic fields which, when accessed, return an Iterable of node or relationship entities that are the result of a traversal starting at the entity containing the field. The TraversalDescription used for this is created by the FieldTraversalDescriptionBuilder class defined by the traversal attribute. The class of the resulting node entities must be provided with the elementClass attribute.

@NodeEntity
public class Group {
    @GraphTraversal(traversal = PeopleTraversalBuilder.class,
            elementClass = Person.class, params = "persons")
    private Iterable<Person> people;

    private static class PeopleTraversalBuilder implements FieldTraversalDescriptionBuilder {
        @Override
        public TraversalDescription build(NodeBacked start, Field field, String... params) {
            return new TraversalDescriptionImpl()
                    .relationships(DynamicRelationshipType.withName(params[0]))
                    .filter(Traversal.returnAllButStartNode());
        }
    }
}

Every field of a node entity that references one or more other node entities is backed by relationships in the graph. These relationships are managed by Spring Data Neo4j automatically.

The simplest kind of relationship is a single field pointing to another node entity (1:1). In this case, the field does not have to be annotated at all, although the annotation may be used to control the direction and type of the relationship. When setting the field, a relationship is created when the entity is persisted. If the field is set to null, the relationship is removed.

@NodeEntity
public class Movie {
    private Actor topActor;
}

It is also possible to have fields that reference a set of node entities (1:N). These fields come in two forms, modifiable or read-only. Modifiable fields are of the type Set<T>, and read-only fields are Iterable<T>, where T is a @NodeEntity-annotated class.

@NodeEntity
public class Actor {
    @RelatedTo(type = "topActor", direction = Direction.INCOMING)
    private Set<Movie> topActorIn;

    @RelatedTo(type = "ACTS_IN")
    private Set<Movie> movies;
}

For the simple mapping, the automatic transitive loading of related entities depends on declaration of @Fetch at the property. Otherwise the related node or relationship entities will just be initialized with their id for later loading.

When using the advanced mapping, Fields referencing other entities should not be manually initialized, as they are managed by Spring Data Neo4j Aspects under the hood. 1:N fields can be accessed immediately, and Spring Data Neo4j will provide a Set representing the relationships.

If this Set of related entities is modified, the changes are reflected in the graph, relationships are added, removed or updated accordingly.

	Note
	Spring Data Neo4j ensures by default that there is only one relationship of a given type between any two given entities. This can be circumvented by using the createRelationshipBetween() method with the allowDuplicates parameter on repositories or entities.

	Note
	Before an entity has been persisted for the first time, it will not have its state managed by Spring Data Neo4j. For example, given the Actor class defined above, if actor.movies was accessed in a non-persisted entity, it would return null, whereas if it was accessed in a persisted entity, it would return an empty managed set.

When an Interface is used as target type for the Set and/or as elementClass it should be marked as @NodeEntity too.

By setting direction to BOTH, relationships are created in the outgoing direction, but when the 1:N field is read, it will include relationships in both directions. A cardinality of M:N is not necessary because relationships can be navigated in both directions.

In the advanced mapping mode, the relationships can also be accessed by using the methods entity.getRelationshipBetween(target, type) and entity.relateTo(target, type) available on each NodeEntity. These methods find and create Neo4j relationships. It is also possible to manually remove relationships by using entity.removeRelationshipTo(target, type). Using these methods is significantly faster than adding/removing from the collection of relationships as it doesn't have to re-synchronize a whole set of relationships with the graph.

Methods of the same semantics exist in the repositories to be used in the simple mapping mode.

	Note
	Other collection types than Set are not supported so far, also currently NO Map<RelationshipType,Set<NodeBacked>>.

To access the full data model of graph relationships, POJOs can also be annotated with @RelationshipEntity, making them relationship entities. Just as node entities represent nodes in the graph, relationship entities represent relationships. As described above, fields annotated with @RelatedTo provide a way to only link node entities via relationships, but it provides no way of accessing the relationships themselves.

Relationship entities can be accessed via by @RelatedToVia-annotated (Section 20.5.3, “@RelatedToVia: Accessing relationship entities”) fields or methods like entity.getRelationshipTo() or template|repository.getRelationship(s)Between().

Relationship entities either be instantiated directly and set or added to @RelatedToVia-annotated fields or created by the introduced entity.relateTo(), template|repository.createRelationshipBetween() methods (see alos Section 20.12, “Active Record Methods for Advanced Mapping Mode”)

Fields in relationship entities are, similarly to node entities, persisted as properties on the relationship. For accessing the two endpoints of the relationship, two special annotations are available: @StartNode and @EndNode. A field annotated with one of these annotations will provide read-only access to the corresponding endpoint, depending on the chosen annotation.

For the relationship-type a String or RelationshipType field annotated with @RelationshipType is available. When Relationship-Entities are instantiated directly, the relationship type has to be provided either in this annotated field or as part of the @RelationshipEntity annotation.

@NodeEntity
public class Actor {
    public Role playedIn(Movie movie, String title) {
        return relateTo(movie, Role.class, "ACTS_IN");
    }
}

@RelationshipEntity
public class Role {
    String title;

    @StartNode private Actor actor;
    @EndNode private Movie movie;
}
        

To provide easy programmatic access to the richer relationship entities of the data model, the annotation @RelatedToVia can be added on fields of type Iterable<T> or Set<T> or T, where T is a @RelationshipEntity-annotated class. These fields provide access to relationship entities.

@NodeEntity
public class Actor {
    @RelatedToVia
    @Set<Role> roles=new HashSet<Role>();
    public Role playedIn(Movie movie, String title) {
        Role role=new Role(this,movie,title);
        roles.add(role);
        return role;
    }
    @RelatedToVia(type="FRIEND_OF", direction=Direction.INCOMING)
    Friendship bestFriend;
}

@RelationshipEntity(type = "ACTS_IN")
public class Role {
    String title;

    @StartNode private Actor actor;
    @EndNode private Movie movie;
}
@RelationshipEntity
public class Friendship {
    Date since;

    @StartNode private Actor actor;
    @EndNode private Person buddy;
}
        

In the example above we show how to specify a default relationship type, and how to provide the relationship type using an annotation property. Here is an example of using the @RelationshipType annotation on a member variable on the relationship entity; we call this dynamic relationship type.

@RelationshipEntity(type = "colleague")
public class Acquaintance {
      @StartNode private Actor actor;
      @EndNode private Person acquaintance;
      @RelationshipType private String connection;

      public Acquaintance(Actor actor, Person acquaintance, String connection) {
          ...

Actor frankSinatra = ...
Person carloGambino = ...
new Acquaintance(frankSinatra, carloGambino, "its_complicated")

      

	Note
	Because dynamic type information is, well, dynamic, it is generally not possible to read the mapping backwards using SDN. The relationship still exists, but SDN cannot help you access it because it does not know what type you gave it. Also, for this reason, we require you to specify a default relationship type, so that we can at least attempt the reverse mapping.

Should you happen to provide conflicting relationship types, we have established the following precedence, in priority order:

In some cases, you want to model two different aspects of a conceptual relationship using the same relationship type. Here is a canonical example:

                
                @NodeEntity
                class Person {
                    @RelatedTo(type="OWNS")
                    Car car;

                    @RelatedTo(type="OWNS")
                    Pet pet;
                ...
            

It is clear how we can map these relationships: by looking at the type of the end node. To enable this, we have introduced an boolean annotation parameter enforceTargetType, which is disabled by default. Our example now reads:

                
                @NodeEntity
                class Person {
                    @RelatedTo(type="OWNS", enforceTargetType=true)
                    Car car;

                    @RelatedTo(type="OWNS", enforceTargetType=true)
                    Pet pet;
                ...
            

The example easily generalises to collections too of course, but there are a few note-worthy rules and corner cases:

When using the standard Neo4j API, nodes and relationships have to be manually indexed with key-value pairs, typically being the property name and value. When using Spring Data Neo4j, this task is simplified to just adding an @Indexed annotation on entity fields by which the entity should be searchable. This will result in automatic updates of the index every time an indexed field changes.

Numerical fields are indexed numerically so that they are available for range queries. All other fields are indexed with their string representation. If a numeric field should not be indexed numerically, it is possible to switch it off with @Indexed(numeric=false).

The @Indexed annotation also provides the option of using a custom index name. The default index name is the simple class name of the entity, so that each class typically gets its own index. It is recommended to not have two entity classes with the same class name, regardless of package.

If a field is declared in a superclass but different indexes for subclasses are needed, the level attribute declares what will be used as index. Level.CLASS uses the class where the field was declared and Level.INSTANCE uses the class that is provided or of the actual entity instance.

The indexes can be queried by using a repository (see Section 20.8, “CRUD with repositories”). The repository is an instance of org.springframework.data.neo4j.repository.IndexRepository. The methods findByPropertyValue() and findAllByPropertyValue() work on the exact indexes and return the first or all matches. To do range queries, use findAllByRange() (please note that currently both values are inclusive).

For providing explicit index names the repository has to extend NamedIndexRepository. This adds the shown methods with another signature that take the index name as first parameter.

@NodeEntity
class Person {
    @Indexed(indexName = "people") String name;
    @Indexed int age;
}

GraphRepository<Person> graphRepository = template.repositoryFor(Person.class);

// Exact match, in named index
Person mark = graphRepository.findByPropertyValue("people", "name", "mark");

// Numeric range query, index name inferred automatically
for (Person middleAgedDeveloper : graphRepository.findAllByRange("age", 20, 40)) {
    Developer developer=middleAgedDeveloper.projectTo(Developer.class);
}

Spring Data Neo4j also supports fulltext indexes. By default, indexed fields are stored in an exact lookup index. To have them analyzed and prepared for fulltext search, the @Indexed annotation has the type attribute which can be set to IndexType.FULLTEXT. Please note that fulltext indexes require a separate index name as the fulltext configuration is stored in the index itself.

Access to the fulltext index is provided by the findAllByQuery() repository method. Wildcards like * are allowed. Generally though, the fulltext querying rules of the underlying index provider apply. See the Lucene documentation for more information on this.

@NodeEntity
class Person {
    @Indexed(indexName = "people-search", type=FULLTEXT) String name;
}

GraphRepository<Person> graphRepository =
             template.repositoryFor(Person.class);

Person mark = graphRepository.findAllByQuery("people-search", "name", "ma*");

	Note
	Please note that indexes are currently created on demand, so whenever an index that doesn't exist is requested from a query or get operation it is created. This is subject to change but has currently the implication that those indexes won't be configured as fulltext which causes subsequent fulltext updates to those indexes to fail.

Unique indexing with index.putIfAbsent and UniqueFactory was introduced in Neo4j 1.6. It is also available via the REST API. In Spring Data Neo4j this is made available via Neo4jTemplate.getOrCreateNode and Neo4jTemplate.getOrCreateRelationship.

In an entity at most one field can be annotated with @Indexed(unique=true) regardless of the index-type used. The uniqueness will be taken into account when creating the entity by reusing an existing entity if that unique key-combination already exists. On saving of the field it will be cross-checked against the index and fail with a DataIntegrityViolationException if the field was changed to an already existing unique value. Null values are no longer allowed for these properties.

	Note
	This works for both Node-Entities as well as Relationship-Entities. Relationship-Uniqueness in Neo4j is global so that an existing unique instance of this relationship may connect two completely different nodes and might also have a different type.

// creates or finds a node with the unique index-key-value combination
// and initializes it with the properties given
template.getOrCreateNode("users", "login", "mh", map("name","Michael","age",37));

@NodeEntity class Person {
    @Indexed(unique = true) String name;
}

Person mark1 = repository.save(new Person("mark"));
Person mark2 = repository.save(new Person("mark"));

// just one node is created
assertEquals(mark1,mark2);
assertEquals(1, personRepository.count());

Person thomas = repository.save(new Person("thomas"));
thomas.setName("mark");
repository.save(thomas); // fails with a DataIntegrityViolationException

The index for a domain class is also available from Neo4jTemplate via the getIndex() method. The second parameter is optional and takes the index name if it should not be inferred from the class name. It returns the index implementation that is provided by Neo4j.

@Autowired Neo4jTemplate template;

// Default index
Index<Node> personIndex = template.getIndex(null, Person.class);
personIndex.query(new QueryContext(NumericRangeQuery.newÍntRange("age", 20, 40, true, true))
                       .sort(new Sort(new SortField("age", SortField.INT, false))));

// Named index
Index<Node> namedPersonIndex = template.getIndex("people",Person.class);
namedPersonIndex.get("name", "Mark");

// Fulltext index
Index<Node> personFulltextIndex = template.getIndex("people-search", Person.class);
personFulltextIndex.query("name", "*cha*");
personFulltextIndex.query("{name:*cha*}");

It is also possible to pass in the property name of the entity with an @Indexed annotation whose index should be returned.

@Autowired Neo4jTemplate template;

Index<Node> personIndex = template.getIndex(Person.class, "age");
personIndex.query(new QueryContext(NumericRangeQuery.newÍntRange("age", 20, 40, true, true))
                       .sort(new Sort(new SortField("age", SortField.INT, false))));

// Fulltext index
Index<Node> personFulltextIndex = template.getIndex(Person.class,"name");
personFulltextIndex.query("name", "*cha*");
personFulltextIndex.query("{name:*cha*}");

For querying the index, the template offers query methods that take either the exact match parameters or a query object/expression, return the results as Result objects which can then be converted and projected further using the result-conversion-dsl (see Section 20.7, “Neo4jTemplate”).

Neo4j allows to configure auto-indexing for certain properties on nodes and relationships. This auto-indexing differs from the approach used in Spring Data Neo4j because it only updates the indexes when the transaction is committed. So the index modifications will only be available after the successful commit. It is possible to use the specific index names node_auto_index and relationship_auto_index when querying indexes in Spring Data Neo4j either with the query methods in template and repositories or via Cypher and Gremlin.

Spring Data Neo4j offers limited support for spatial queries using the neo4j-spatial library. See the separate chapter Section 20.11, “Geospatial Queries” for details.

For direct retrieval of nodes and relationships, the getReferenceNode(), getNode() and getRelationship() methods can be used.

There are methods (createNode() and createRelationship()) for creating nodes and relationships that automatically set provided properties.

Neo4jOperations neo = new Neo4jTemplate(graphDatabase);
    
    Node mark = neo.createNode(map("name", "Mark"));
    Node thomas = neo.createNode(map("name", "Thomas"));
    
    neo.createRelationshipBetween(mark, thomas, "WORKS_WITH", 
                                map("project", "spring-data"));
    
    neo.index("devs", thomas, "name", "Thomas");
    
    assertEquals( "Mark", 
        neo.query("start p=node({person}) match p<-[:WORKS_WITH]-other return other.name",
                  map("person", asList(thomas.getId()))).to(String.class).single());
    
    
    
    // Gremlin
    assertEquals(thomas, neo.execute("g.v(person).out('WORKS_WITH')",
            map("person", mark.getId())).to(Node.class).single());
    
    // Index lookup
    assertEquals(thomas, neo.lookup("devs", "name", "Thomas").to(Node.class).single());
    
    // Index lookup with Result Converter
    assertEquals("Thomas", neo.lookup("devs", "name", "Thomas")
      .to(String.class, new ResultConverter<PropertyContainer, String>() {
        public String convert(PropertyContainer element, Class<String> type) {
            return (String) element.getProperty("name");
        }
      }).single());
    

Neo4jTemplate provides access to some of the methods of the Neo4j-Core-API directly. So accessing nodes and relationships (getReferenceNode, getNode, getRelationship, getRelationshipBetween), creating nodes and relationships (createNode, createNodeAs, createRelationshipBetween) and deleting them (delete, deleteRelationshipBetween) are supported. It also provides access to the underlying GraphDatabase via getGraphDatabase.

Neo4jTemplate allows to save, find(One/All), count, delete and projectTo entities. It provides the stored type information via getStoredJavaType and can fetch lazy-loaded entities or load them altogether.

All querying methods of the template return a uniform result type: Result<T> which is also an Iterable<T>. The query result offers methods of converting each element to a target type result.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 Result<FROM> is an Iterable<TO>. Results can be limited to a single value using the result.single() or result.singleOrNull() methods. It also offers support for a pure callback function using a Handler<T>.

Adding nodes and relationships to an index is done with the index() method.

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 Result<PropertyContainer> to be used or transformed.

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 template.getGraphDatabase().traversalDescription() DSL) and runs it from the given start node. traverse returns a Result<Path> to be used or transformed.

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 Result<Map<String,Object>> contains the rows which can be either used as they are or converted as needed.

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 Result<Object> fit for conversion or usage.

The Neo4jTemplate provides implicit transactions for some of its methods. For instance save uses them. For other modifying operations please provide Spring Transaction management using @Transactional or the TransactionTemplate.

If the template is configured to use a SpringRestGraphDatabase the operations that would be expensive over the wire, 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 individual network operations.

The REST-batch-mode of the SpringRestGraphDatabase is not yet exposed via the template, but it is available via the graph database.

Neo4j Template offers basic lifecycle events via Spring's event mechanism using ApplicationListener and ApplicationEvent. The following hooks are available in the form of types of application event:

The following example demonstrates how to hook into the application lifecycle and register listeners that perform behaviour across types of entities during this life cycle:

                @Configuration
    @EnableNeo4jRepositories
    public class ApplicationConfig extends Neo4jConfiguration {
        ...
        @Bean
        ApplicationListener<BeforeSaveEvent> beforeSaveEventApplicationListener() {
            return new ApplicationListener<BeforeSaveEvent>() {
                @Override
                public void onApplicationEvent(BeforeSaveEvent event) {
                    AcmeEntity entity = (AcmeEntity) event.getEntity();
                    entity.setUniqueId(acmeIdFactory.create());
                }
            };
        }

        @Bean
        ApplicationListener<AfterSaveEvent> afterSaveEventApplicationListener() {
            return new ApplicationListener<AfterSaveEvent>() {
                @Override
                public void onApplicationEvent(AfterSaveEvent event) {
                    AcmeEntity entity = (AcmeEntity) event.getEntity();
                    auditLog.onEventSaved(entity);
                }
            };
        }

        @Bean
        ApplicationListener<DeleteEvent> deleteEventApplicationListener() {
            return new ApplicationListener<DeleteEvent>() {
                @Override
                public void onApplicationEvent(DeleteEvent event) {
                    AcmeEntity entity = (AcmeEntity) event.getEntity();
                    auditLog.onEventDeleted(entity);
                }
            };
        }
        ...
            

Changes made to entities in the before-save event handler are reflected in the stored entity - after-save ones are not.

CRUDRepository delegates to the configured TypeRepresentationStrategy (see Section 20.15, “Entity type representation”) for type based queries.

IndexRepository works with the indexing subsystem and provides methods to find entities by indexed properties, ranged queries, and combinations thereof. The index key is the name of the indexed entity field, unless overridden in the @Indexed annotation.

There is also a NamedIndexRepository with the same methods, but with an additional index name parameter, making it possible to query any index.

TraversalRepository delegates to the Neo4j traversal framework.

Spring Data Neo4j supports the new Cypher-DSL to write Cypher queries in a statically typed way. Just by including CypherDslRepository to your repository you get the Page<T> query(Execute query, params, Pageable page), Page<T> query(Execute query, Execute countQuery, params, Pageable page) and the EndResult<T> query(Execute query, params);. The result type of the Cypher-DSL builder is called Execute.

import static org.neo4j.cypherdsl.CypherQuery.*;
import static org.neo4j.cypherdsl.querydsl.CypherQueryDSL.*;

	public interface PersonRepository extends GraphRepository<Person>,
	  CypherDslRepository<Person> {}

	@Autowired PersonRepository repo;
	// START company=node:Company(name={name}) MATCH company<-[:WORKS_AT]->person RETURN person

	Execute query = start( lookup( "company", "Company", "name", param("name") ) ).
	                          match( path().from( "company" ).in( "WORKS_AT" ).to( "person" )).
	                          returns( identifier( "person" ))
	Page<Person> people = repo.query(query , map("name","Neo4j"), new PageRequest(1,10));

	QPerson person = QPerson.person;
	QCompany company = QCompany.company;
	Execute query = start( lookup( company, "Company", company.name, param("name") ) ).
	                          match( path().from( company ).in( "WORKS_AT" ).to( person ).
	                          .where(person.firstName.like("P*").and(person.age.gt(25))).
	                          returns( identifier(person) )
	EndResult<Person> people = repo.query(query , map("name","Neo4j"));

	

To use Cypher-DSL with Query-DSL the Mysema dependencies have to be declared explicitly as they are optional in the Cypher-DSL project.

<dependency>
    <groupId>com.mysema.querydsl</groupId>
    <artifactId>querydsl-core</artifactId>
    <version>2.2.3</version>
    <optional>true</optional>
</dependency>
<dependency>
    <groupId>com.mysema.querydsl</groupId>
    <artifactId>querydsl-lucene</artifactId>
    <version>2.2.3</version>
    <optional>true</optional>
    <exclusions>
        <exclusion>
            <groupId>org.apache.lucene</groupId>
            <artifactId>lucene-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>com.mysema.querydsl</groupId>
    <artifactId>querydsl-apt</artifactId>
    <version>2.2.3</version>
    <scope>provided</scope>
</dependency>

It is possible to use the Cypher-DSL along with the predicates and code generation features of the QueryDSL project. This will allow you to use Java objects as part of the query, rather than strings, for the names of properties and such. In order to get this to work you first have to add a code processor to your Maven build, which will parse your domain entities marked with @NodeEntity, and from that generate QPerson-style classes, as shown in the previous section. Here is what you need to include in your Maven POM file.

            <plugin>
                <groupId>com.mysema.maven</groupId>
                <artifactId>maven-apt-plugin</artifactId>
                <version>1.0.2</version>
                <configuration>
                    <processor>org.springframework.data.neo4j.querydsl.SDNAnnotationProcessor</processor>
                </configuration>
                <executions>
                    <execution>
                        <id>test-sources</id>
                        <phase>generate-test-sources</phase>
                        <goals>
                            <goal>test-process</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>target/generated-sources/test</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

This custom QueryDSL AnnotationProcessor will generate the query classes that can be used when constructing Cypher-DSL queries, as in the previous section.

The Repository instances should normally be injected but can also be created manually via the Neo4jTemplate.

public interface PersonRepository extends GraphRepository<Person> {}

@Autowired PersonRepository repo;
// OR
GraphRepository<Person> repo = template
                           .repositoryFor(Person.class);

Person michael = repo.save(new Person("Michael", 36));

Person dave = repo.findOne(123);

Long numberOfPeople = repo.count();

EndResult<Person> devs = graphRepository.findAllByPropertyValue("occupation", "developer");

EndResult<Person> middleAgedPeople = graphRepository.findAllByRange("age", 20, 40);

EndResult<Person> aTeam = graphRepository.findAllByQuery("name", "A*");

Iterable<Person> aTeam = repo.findAllByQuery("name", "A*");

Iterable<Person> davesFriends = repo.findAllByTraversal(dave,
    Traversal.description().pruneAfterDepth(1)
    .relationships(KNOWS).filter(returnAllButStartNode()));

The recommended way of providing repositories is to define a repository interface per domain class. The mechanisms provided by the repository infrastructure will automatically detect them, along with additional implementation classes, and create an injectable repository implementation to be used in services or other spring beans.

public interface PersonRepository extends GraphRepository<Person>, PersonRepositoryExtension {}

// configure the repositories, preferably via the neo4j:repositories namespace
// (template reference is optional)
<neo4j:repositories base-package="org.example.repository"
    graph-database-context-ref="template"/>

// have it injected
@Autowired
PersonRepository personRepository;
// or created via the template
PersonRepository personRepository = template.repositoryFor(Person.class);


Person michael = personRepository.save(new Person("Michael",36));

Person dave=personRepository.findOne(123);

Iterable<Person> devs = personRepository.findAllByPropertyValue("occupation","developer");

Iterable<Person> aTeam = graphRepository.findAllByQuery( "name","A*");

Iterable<Person> friends = personRepository.findFriends(dave);


// alternatively select some of the required repositories individually
public interface PersonRepository extends CRUDGraphRepository<Node,Person>,
        IndexQueryExecutor<Node,Person>, TraversalQueryExecutor<Node,Person>,
        PersonRepositoryExtension {}

// provide a custom extension if needed
public interface PersonRepositoryExtension {
    Iterable<Person> findFriends(Person person);
}

public class PersonRepositoryImpl implements PersonRepositoryExtension {
    // optionally inject default repository, or use DirectGraphRepositoryFactory
    @Autowired PersonRepository baseRepository;
    public Iterable<Person> findFriends(Person person) {
        return baseRepository.findAllByTraversal(person, friendsTraversal);
    }
}

// configure the repositories, preferably via the datagraph:repositories namespace
// (template reference is optional)
<neo4j:repositories base-package="org.springframework.data.neo4j"
    graph-database-context-ref="template"/>

// have it injected
@Autowired
PersonRepository personRepository;

Person michael = personRepository.save(new Person("Michael",36));

Person dave=personRepository.findOne(123);

EndResult<Person> devs = personRepository.findAllByPropertyValue("occupation","developer");

EndResult<Person> aTeam = graphRepository.findAllByQuery( "name","A*");

Iterable<Person> friends = personRepository.findFriends(dave);

	Note
	If you use <context:component-scan> in your spring config, please make sure to put it behind <neo4j:repositories>, as the RepositoryFactoryBean adds new bean definitions for all the declared repositories, the context scan doesn't pick them up otherwise.

For both queries executed via the result conversion DSL as well as repository methods, it is possible to specify a conversion of complex query results to POJO interfaces or objects. Those result objects are then populated with the query result data and can be serialized and sent to a different part of the applicaton, e.g. a frontend-ui.

Use an interface annotated with @QueryResult and getter methods which might be annotated with @ResultColumn("columnName") to match the query-result column names. Or use a plain POJO, both work.

public interface MovieRepository extends GraphRepository<Movie> {

@Query("START movie=node:Movie(id={0})
        MATCH movie-[rating?:rating]->(),
              movie<-[:ACTS_IN]-actor
        RETURN movie, COLLECT(actor), AVG(rating.stars)")
MovieData getMovieData(String movieId);

@QueryResult
public class MovieData {
    Movie movie;

    @ResultColumn("AVG(rating.stars)")
    Double rating;

    @ResultColumn("COLLECT(actor)")
    Collection<Actor> cast;
}

// alternatively use
@QueryResult
public interface MovieData {
    @ResultColumn("movie")
    Movie getMovie();

    @ResultColumn("AVG(rating.stars)")
    Double getRating();

    @ResultColumn("COLLECT(actor)")
    Iterable<Actor> getCast();
}
}

As mentioned above, an entity simply created with the new keyword starts out detached. It also has no state assigned to it. If you create a new entity with new and then throw it away, the database won't be touched at all.

Now consider this scenario:

@NodeEntity
class Movie {
    private Actor topActor;
    public void setTopActor(Actor actor) {
        topActor = actor;
    }
}

@NodeEntity
class Actor {
}

Movie movie = new Movie();
Actor actor = new Actor();

movie.setTopActor(actor);

Neither the actor nor the movie has been assigned a node in the graph. If we were to call movie.persist(), then Spring Data Neo4j would first create a node for the movie. It would then note that there is a relationship to an actor, so it would call actor.persist() in a cascading fashion. Once the actor has been persisted, it will create the relationship from the movie to the actor. All of this will be done atomically in one transaction.

Important to note here is that if actor.persist() is called instead, then only the actor will be persisted. The reason for this is that the actor entity knows nothing about the movie entity. It is the movie entity that has the reference to the actor. Also note that this behavior is not dependent on any configured relationship direction on the annotations. It is a matter of Java references and is not related to the data model in the database.

The save operation (merge) stores all properties of the entity to the graph database and puts the entity in attached mode. There is no need to update the reference to the Java POJO as the underlying backing node handles the read-through transparently. If multiple object instances that point to the same node are persisted, the ordering is not important as long as they contain distinct changes. For concurrent changes a concurrent modification exception is thrown (subject to be parameterized in the future).

If the relationships form a cycle, then the entities will first of all be assigned a node in the database, and then the relationships will be created. The cascading of persist() is however only cascaded to related entity fields that have been modified.

In the following example, the actor and the movie are both attached entites, having both been previously persisted to the graph:

actor.setName("Billy Bob");
movie.persist();

In this case, even though the movie has a reference to the actor, the name change on the actor will not be persisted by the call to movie.persist(). The reason for this is, as mentioned above, that cascading will only be done for fields that have been modified. Since the movie.topActor field has not been modified, it will not cascade the persist operation to the actor.