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.

IDE's not providing the full AJ support might mark parts of your code as errors. You should rely on your build-system and test 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: http://download.eclipse.org/tools/ajdt/37/update/ (it might be necessary to use the latest development snapshot of the plugin http://download.eclipse.org/tools/ajdt/36/dev/update). 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.

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 overridden 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 and @GraphTraversal.

@NodeEntity
public class Movie {
    String title;
}

It is not necessary to annotate data fields, as they are persisted by default; all fields that contain primitive values are persisted directly to the graph. All fields convertible to 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.

Currently there is no support for handling arbitrary collections of primitive or convertable values. Support for this will be added by the 1.1. release.

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.

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 used by the Spring Data Neo4j aspects. 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 id of the current entity. For instance start n=({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, an Iterable of a concrete type or an Iterable of Map<String,Object>. Additional parameters are taken from the params attribute of the @Query annotation. The tuples form key-value pairs that are provided to the query at execution time.

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

The @GraphTraversal annotation leverages the delegation infrastructure used by the Spring Data Neo4j aspects. It provides dynamic fields which, when accessed, return an Iterable of node 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 traversalBuilder attribute. The class of the resulting node entities must be provided with the elementClass attribute.

@NodeEntity
public class Group {
    @GraphTraversal(traversalBuilder = 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. If the field is set to null, the relationship is removed.

@NodeEntity
public class Movie {
    private Actor mostPaidActor;
}

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 java.util.Set<T>, and read-only fields are java.lang.Iterable<T>, where T is a @NodeEntity-annotated class.

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

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

Fields referencing other entities should not be manually initialized, as they are managed by Spring Data Neo4j under the hood. 1:N fields can be accessed immediately, and Spring Data Neo4j will provide a java.util.Set representing the relationships. If the returned set is modified, the changes are reflected in the graph. Spring Data Neo4j also ensures that there is only one relationship of a given type between any two given entities.

When you use an Interface as target type for the Set and/or as elementClass please make sure that it implements NodeBacked either by extending that Super-Interface manually or by annotating the Interface with @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.

The relationships can also be accessed by using the aspect-introduced methods entity.getRelationshipTo(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.

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 link node entities together via relationships, but it provides no way of accessing the relationships themselves.

Relationship entities cannot be instantiated directly but are rather created via node entities, either by @RelatedToVia-annotated fields (see Section 20.5.3, “@RelatedToVia: Accessing relationship entities”), or by the introduced entity.relateTo(target, relationshipClass, type) and entity.getRelationshipTo(target, relationshipClass, type) methods (see Section 20.11, “Introduced methods”).

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.

@NodeEntity
public class Actor {
    public Role playedIn(Movie movie, String title) {
        return relatedTo(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 java.lang.Iterable<T>, where T is a @RelationshipEntity-annotated class. These fields provide read-only access to relationship entities.

@NodeEntity
public class Actor {
    @RelatedToVia(type = "ACTS_IN")
    private Iterable<Role> roles;

    public Role playedIn(Movie movie, String title) {
        Role role = relateTo(movie, Role.class, "ACTS_IN");
        role.setTitle(title);
        return role;
    }
}

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.

The @Indexed annotation also provides the option of using a custom index. 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.

The indexes can be queried by using a repository (see Section 20.8, “CRUD with repositories”). Typically, the repository is an instance of org.springframework.data.neo4j.repository.DirectGraphRepositoryFactory. 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).

@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 boolean fulltext attribute. 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*");

The index for a domain class is also available from GraphDatabaseContext 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 GraphDatabaseContext gdc;

// Default index
Index<Node> personIndex = gdc.getIndex(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 = gdc.getIndex(Person.class, "people");
namedPersonIndex.get("name", "Mark");

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

Neo4jTemplate also offers index support, providing auto-indexing for fields at creation time. There is an autoIndex method that can also add indexes for a set of fields in one go.

For querying the index, the template offers query methods that take either the exact match parameters or a query object/expression, and push the results wrapped uniformly as Paths to the supplied PathMapper to be converted or collected.

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.

        // TODO auto-post-construct !!
        Neo4jOperations neo = new Neo4jTemplate(graphDatabase).postConstruct();

        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");
        // Cypher TODO
        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.ResultConverterAdapter<PropertyContainer, String>() {
            public String convert(PropertyContainer element, Class<String> type) {
                return (String) element.getProperty("name");
            }
        }).single());

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() method. 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 Traversal.description() 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 configurable implicit transactions for all its methods. By default it creates a transaction for each call (which is a no-op if there is already a transaction running). If you call the constructor with the useExplicitTransactions parameter set to true, it won't create any transactions so you have to provide them using @Transactional or the TransactionTemplate.

If the template is configured to use a RestGraphDatabase the expensive operations like traversals and querying are executed efficiently on the server side by using the REST API to forward those calls. All the other template methods require single network operations.

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

Important to note here is that the save, delete, and deleteAll methods are only there to conform to the org.springframework.data.repository.Repository interface. The recommended way of saving and deleting entities is by using entity.persist() and entity.remove().

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.

The Repository instances are either created manually via a DirectGraphRepositoryFactory, bound to a concrete node or relationship entity class. The DirectGraphRepositoryFactory is configured in the Spring context and can be injected.

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

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

Person dave = graphRepository.findOne(123);

Long numberOfPeople = graphRepository.count();

Person mark = graphRepository.findByPropertyValue("name", "mark");

Iterable<Person> devs = graphRepository.findAllByProperyValue("occupation", "developer");

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

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

Iterable<Person> davesFriends = graphRepository.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 {}

// 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);

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

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

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

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 persist 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 parametrizable in the future).

If the relationships form a cycle, then the entities will first 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.