|
|
Accessing Data with Neo4j
This guide walks you through the process of using Spring Data Neo4j to build an application that stores data in and retrieves it from Neo4j , a graph-based database.
What You Will Build
You will use Neo4j’s NoSQL graph-based data store to build an embedded Neo4j server, store entities and relationships, and develop queries.
Java 17 or later
You can also import the code straight into your IDE:
Like most Spring Getting Started guides , you can start from scratch and complete each step or you can bypass basic setup steps that are already familiar to you. Either way, you end up with working code.
To start from scratch , move on to Starting with Spring Initializr .
To skip the basics , do the following:
Download
and unzip the source repository for this guide, or clone it using
Git
:
git clone
https://github.com/spring-guides/gs-accessing-data-neo4j.git
cd into
gs-accessing-data-neo4j/initial
Jump ahead to Define a Simple Entity .
When you finish
, you can check your results against the code in
gs-accessing-data-neo4j/complete
.
You can use this pre-initialized project and click Generate to download a ZIP file. This project is configured to fit the examples in this tutorial.
To manually initialize the project:
Navigate to https://start.spring.io . This service pulls in all the dependencies you need for an application and does most of the setup for you.
Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.
Click Dependencies and select Spring Data Neo4j .
Click Generate .
Download the resulting ZIP file, which is an archive of a web application that is configured with your choices.
Starting Neo4j. Started neo4j (pid 96416). By default, it is available at http://localhost:7474/ There may be a short delay until the server is ready. See /usr/local/Cellar/neo4j/3.0.6/libexec/logs/neo4j.log for current status.
This changes the password from
neo4j
to
secret
— something to NOT do in production! With that step completed, you should be ready to run the rest of this guide.
Alternatively, to run with the
Neo4j Docker image
. You can change the password with the
NEO4J_AUTH
environment variable.
Neo4j captures entities and their relationships, with both aspects being of equal importance. Imagine you are modeling a system where you store a record for each person. However, you also want to track a person’s co-workers (
teammates
in this example). With Spring Data Neo4j, you can capture all that with some simple annotations, as the following listing (in
src/main/java/com/example/accessingdataneo4j/Person.java
) shows:
The
Person
class is annotated with
@NodeEntity
. When Neo4j stores it, a new node is created. This class also has an
id
marked
@GraphId
. Neo4j uses
@GraphId
internally to track the data.
The next important piece is the set of
teammates
. It is a simple
Set<Person>
but is marked as
@Relationship
. This means that every member of this set is expected to also exist as a separate
Person
node. Note how the direction is set to
UNDIRECTED
. This means that when you query the
TEAMMATE
relationship, Spring Data Neo4j ignores the direction of the relationship.
With the
worksWith()
method, you can easily link people together.
Finally, you have a convenient
toString()
method to print out the person’s name and that person’s co-workers.
Spring Data Neo4j is focused on storing data in Neo4j. But it inherits functionality from the Spring Data Commons project, including the ability to derive queries. Essentially, you need not learn the query language of Neo4j. Instead, you can write a handful of methods and let the queries be written for you.
To see how this works, create an interface that queries
Person
nodes. The following listing (in
src/main/java/com/example/accessingdataneo4j/PersonRepository.java
) shows such a query:
PersonRepository
extends the
Neo4jRepository
interface and plugs in the type on which it operates:
Person
. This interface comes with many operations, including standard CRUD (create, read, update, and delete) operations.
But you can define other queries by declaring their method signatures. In this case, you added
findByName
, which seeks nodes of type
Person
and finds the one that matches on
name
. You also have
findByTeammatesName
, which looks for a
Person
node, drills into each entry of the
teammates
field, and matches based on the teammate’s
name
.
package com.example.accessingdataneo4j;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class AccessingDataNeo4jApplication {
public static void main(String[] args) {
SpringApplication.run(AccessingDataNeo4jApplication.class, args);
@Configuration: Tags the class as a source of bean definitions for the application context.
@EnableAutoConfiguration: Tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings. For example, if spring-webmvc is on the classpath, this annotation flags the application as a web application and activates key behaviors, such as setting up a DispatcherServlet.
@ComponentScan: Tells Spring to look for other components, configurations, and services in the com/example package, letting it find the controllers.
The main() method uses Spring Boot’s SpringApplication.run() method to launch an application. Did you notice that there was not a single line of XML? There is no web.xml file, either. This web application is 100% pure Java and you did not have to deal with configuring any plumbing or infrastructure.
Spring Boot automatically handles those repositories as long as they are included in the same package (or a sub-package) of your @SpringBootApplication class. For more control over the registration process, you can use the @EnableNeo4jRepositories annotation.
By default, @EnableNeo4jRepositories scans the current package for any interfaces that extend one of Spring Data’s repository interfaces. You can use its basePackageClasses=MyRepository.class to safely tell Spring Data Neo4j to scan a different root package by type if your project layout has multiple projects and it does not find your repositories.
Now autowire the instance of PersonRepository that you defined earlier. Spring Data Neo4j dynamically implements that interface and plugs in the needed query code to meet the interface’s obligations.
The main method uses Spring Boot’s SpringApplication.run() to launch the application and invoke the CommandLineRunner that builds the relationships.
In this case, you create three local Person instances: Greg, Roy, and Craig. Initially, they only exist in memory. Note that no one is a teammate of anyone (yet).
At first, you find Greg, indicate that he works with Roy and Craig, and then persist him again. Remember, the teammate relationship was marked as UNDIRECTED (that is, bidirectional). That means that Roy and Craig have been updated as well.
That is why when you need to update Roy. It is critical that you fetch that record from Neo4j first. You need the latest status on Roy’s teammates before adding Craig to the list.
Why is there no code that fetches Craig and adds any relationships? Because you already have it! Greg earlier tagged Craig as a teammate, and so did Roy. That means there is no need to update Craig’s relationships again. You can see it as you iterate over each team member and print their information to the console.
Finally, check out that other query where you look backwards, answering the question of "Who works with whom?"
The following listing shows the finished AccessingDataNeo4jApplication class (at src/main/java/com/example/accessingdataneo4j/AccessingDataNeo4jApplication.java):
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.data.neo4j.repository.config.EnableNeo4jRepositories;
@SpringBootApplication
@EnableNeo4jRepositories
public class AccessingDataNeo4jApplication {
private final static Logger log = LoggerFactory.getLogger(AccessingDataNeo4jApplication.class);
public static void main(String[] args) throws Exception {
SpringApplication.run(AccessingDataNeo4jApplication.class, args);
System.exit(0);
@Bean
CommandLineRunner demo(PersonRepository personRepository) {
return args -> {
personRepository.deleteAll();
Person greg = new Person("Greg");
Person roy = new Person("Roy");
Person craig = new Person("Craig");
List<Person> team = Arrays.asList(greg, roy, craig);
log.info("Before linking up with Neo4j...");
team.stream().forEach(person -> log.info("\t" + person.toString()));
personRepository.save(greg);
personRepository.save(roy);
personRepository.save(craig);
greg = personRepository.findByName(greg.getName());
greg.worksWith(roy);
greg.worksWith(craig);
personRepository.save(greg);
roy = personRepository.findByName(roy.getName());
roy.worksWith(craig);
// We already know that roy works with greg
personRepository.save(roy);
// We already know craig works with roy and greg
log.info("Lookup each person by name...");
team.stream().forEach(person -> log.info(
"\t" + personRepository.findByName(person.getName()).toString()));
List<Person> teammates = personRepository.findByTeammatesName(greg.getName());
log.info("The following have Greg as a teammate...");
teammates.stream().forEach(person -> log.info("\t" + person.getName()));
You can run the application from the command line with Gradle or Maven. You can also build a single executable JAR file that contains all the necessary dependencies, classes, and resources and run that. Building an executable jar makes it easy to ship, version, and deploy the service as an application throughout the development lifecycle, across different environments, and so forth.
If you use Gradle, you can run the application by using ./gradlew bootRun. Alternatively, you can build the JAR file by using ./gradlew build and then run the JAR file, as follows:
Lookup each person by name...
Greg's teammates => [Roy, Craig]
Roy's teammates => [Greg, Craig]
Craig's teammates => [Roy, Greg]