Spring Data Neo4j: repositories and reactive templates over a graph database

What Spring Data Neo4j is for

Spring Data Neo4j, shortened to SDN, is an ongoing effort to create the next generation of Spring Data Neo4j, with full reactive support and lightweight mapping. It works with immutable entities, regardless of whether they are written in Java or Kotlin. The wider framing comes from the Spring Data project itself, whose primary goal is to make it easier to build Spring-powered applications that use new data access technologies such as non-relational databases, map-reduce frameworks and cloud based data services. The SDN project then aims to provide a familiar and consistent Spring-based programming model for integrating with the Neo4j graph database. So the pitch is not a new programming model, it is the Spring model applied to a database that does not fit the relational one.

Two stacks, two configurations

The library offers an imperative API and a reactive one, and the configuration differs between them. The reactive version is annotated with @EnableReactiveNeo4jRepositories and @EnableTransactionManagement and extends AbstractReactiveNeo4jConfig, exposing a driver bean and a base package mapping for entity scanning.

@Configuration
@EnableReactiveNeo4jRepositories
@EnableTransactionManagement
class MyConfiguration extends AbstractReactiveNeo4jConfig {

    @Bean
    public Driver driver() {
        return GraphDatabase.driver("bolt://localhost:7687", AuthTokens.basic("neo4j", "secret"));
    }

    @Override
    protected Collection<String> getMappingBasePackages() {
        return Collections.singletonList(Person.class.getPackage().getName());
    }
}

The imperative version looks pretty much the same but uses EnableNeo4jRepositories and AbstractNeo4jConfig. That single sentence in the README is the whole difference, and it is the kind of difference that costs an afternoon if you assume the wrong one.

The repository abstraction and what it hides

The reactive example shows the shape of the abstraction.

@Node
public class Person {
    private Long id;
    private String name;

    public Person(String name) {
        this.name = name;
    }
}

@Repository
interface PersonRepository extends ReactiveNeo4jRepository<Person, Long> {

    Flux<Person> findAllByName(String name);

    Flux<Person> findAllByNameLike(String name);
}

The entity is a plain class with a @Node annotation and a getter-less name field, and the repository interface extends ReactiveNeo4jRepository with the entity type and the id type as parameters. The two finder methods are derived from their names rather than written as queries, which is the Spring Data convention applied to a graph store: a method name becomes a pattern match. The service layer then treats the repository as a collection-like thing and saves a Flux of entities.

@Service
class MyService {

    @Autowired
    private final PersonRepository repository;

    @Transactional
    public Flux<Person> doWork() {

        Person emil = new Person("Emil");
        Person gerrit = new Person("Gerrit");
        Person michael = new Person("Michael");

        // Persist entities and relationships to graph database
        return this.repository.saveAll(Flux.just(emil, gerrit, michael));
    }
}

The comment on that last save is worth pausing over, because it is where the abstraction shows its hand. The method is called saveAll and takes three people, and the graph is being asked to persist three nodes and the relationships between them. Where those relationships come from is the interesting question, and it is not answered in the example.

Spring Boot or hand-wired

The README states the preference plainly, in capitals: it recommends Spring Boot, the automatic configuration and especially the dependency management through the Starters, in contrast to the manual work of managing dependencies and configuration. The starter coordinates are org.springframework.boot with the artifact spring-boot-starter-data-neo4j, and the underlying library coordinates are org.springframework.data with the artifact spring-data-neo4j. The connection itself is three properties in the configuration file.

spring.neo4j.uri=bolt://localhost:7687
spring.neo4j.authentication.username=neo4j
spring.neo4j.authentication.password=secret

So with Spring Boot you add a starter and set the connection properties, and the auto-configuration does the rest. Without Spring Boot you add the library dependency with an explicit version and write the configuration class yourself, including the driver bean and the mapping base packages. The difference in effort is small for a graph database, which is part of why the project still supports the manual path.

The documentation is AsciiDoc with a properties file behind it

The README in the repository is not a README in the usual sense. It is an AsciiDoc document, README.adoc, and it is assembled from the documentation source, with a properties block at the top that defines the coordinates and versions used in the examples. Those properties cover the Neo4j group and artifact identifiers, the Spring Boot group and artifact, several Neo4j server versions, the Spring Boot version and the Spring Data version, and the values are substituted into the code samples when the documentation is built. The package.json at the repository root is the toolchain for that build, and it is Antora, the static site generator, with the Spring IO extensions and the Asciidoctor tabs extension for including code by language. So the code blocks you read in the published manual come from files in the documentation directory, and the examples in this README are rendered from the same source with the attribute substitution applied.

Support, help and how issues are handled

The help section is unusually explicit about the route to take for each kind of question. The reference documentation and the Javadocs are the first stop, then the Spring basics for people new to Spring, and the guides if you are just starting out with Spring at all. For upgrades, the project points at the changelog of the individual release version in spring-data-commons for new and noteworthy features. Questions are answered on Stack Overflow, where the spring-data-neo4j tag is monitored, and bugs are reported through the GitHub issue tracker. The issue guidance has three concrete asks: search the tracker first, provide as much information as possible including the version of Spring Data Neo4j, the database version and the JVM version you are using, and if possible create a test case or project that reproduces the issue, attaching a link to your code or a compressed file.

Where Spring Data Neo4j is the wrong choice

Four limits apply. It is an abstraction over a graph, and the abstraction is deliberately lossy: a repository interface with derived finder methods is a fine fit when your data is a graph of entities and a poor fit when your queries are graph traversals, because the layer will want you to model the result as a collection of domain objects. It requires the Spring ecosystem, so an application that is not Spring gains the whole framework stack to get it. The reactive and imperative stacks are separate, and picking the wrong one costs an afternoon, as the README's own one-line difference shows. And the entity model is constrained by what the mapping layer supports, so an unusual domain shape will need custom logic inside the framework rather than around it. The repository also still carries the abstract's promise of an ongoing effort at the next generation, which is a fair signal to read the migration notes before pinning a version.

Editorial conclusion

Use Spring Data Neo4j when your application is already Spring and the graph is the right model for the data, because it gives you the repository and template abstractions the rest of Spring code already assumes. Do not reach for it if you want to query the graph the way Cypher wants to be written, since the abstraction layer is there to make a graph look like a collection of aggregates and that cuts both ways. Verify first which of the two stacks you need, because the reactive and imperative configuration classes are different and the reactive one uses a different repository enablement annotation, and that your Neo4j server version is one the release supports, since the documentation tracks several server versions.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. spring-projects/spring-data-neo4j on GitHub