All guides

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.

What You Need

How to complete this guide

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:

When you finish, you can check your results against the code in gs-accessing-data-neo4j/complete.

Starting with Spring Initializr

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:

  1. Navigate to https://start.cupchino.shop. This service pulls in all the dependencies you need for an application and does most of the setup for you.

  2. Choose either Gradle or Maven and the language you want to use. This guide assumes that you chose Java.

  3. Click Dependencies and select Spring Data Neo4j.

  4. Click Generate.

  5. Download the resulting ZIP file, which is an archive of the application that is configured with your choices.

If your IDE has the Spring Initializr integration, you can complete this process from your IDE.
You can also fork the project from GitHub and open it in your IDE or other editor.

Standing up a Neo4j Server

Before you can build this application, you need to set up a Neo4j server.

Neo4j has an open source server you can install for free, or you can run it with Docker.

To install the server on a Mac that has Homebrew installed, run the following command:

$ brew install neo4j

For other options, visit https://neo4j.com/download/community-edition/.

Once installed, launch it with its default settings by running the following command:

$ neo4j start

You should see output similar to the following:

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/<version>/libexec/logs/neo4j.log for current status.

By default, Neo4j has a username of neo4j and a password of neo4j. However, it requires that the new account password be changed. To do so, open the Neo4j Browser at http://localhost:7474 and log in with the default credentials. You will be prompted to set a new password.

This guide uses spring+neo4j as the new password — 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.

docker run \
  --publish=7474:7474 --publish=7687:7687 \
  --volume=$HOME/neo4j/data:/data \
  --env NEO4J_AUTH=neo4j/spring+neo4j \
  neo4j

Define a Simple Entity

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 who a person has referred (referrals 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:

package com.example.accessingdataneo4j;

import java.util.Collections;
import java.util.HashSet;
import java.util.Optional;
import java.util.Set;
import java.util.stream.Collectors;

import org.jspecify.annotations.Nullable;
import org.springframework.data.neo4j.core.schema.GeneratedValue;
import org.springframework.data.neo4j.core.schema.Id;
import org.springframework.data.neo4j.core.schema.Node;
import org.springframework.data.neo4j.core.schema.Relationship;

@Node
public class Person {

  @Id
  @GeneratedValue
  private @Nullable Long id;

  private String name;

  private Person() {
    // Empty constructor required as of Neo4j API 2.0.5
  };

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

  @Relationship(type = "REFERRED")
  public Set<Person> referrals;

  public void referred(Person person) {
    if (referrals == null) {
      referrals = new HashSet<>();
    }
    referrals.add(person);
  }

  public String toString() {

    return this.name + " referred => "
      + Optional.ofNullable(this.referrals).orElse(
          Collections.emptySet()).stream()
            .map(Person::getName)
            .collect(Collectors.toList());
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }
}

Here you have a Person class that has only one attribute: name.

The Person class is annotated with @Node. When Neo4j stores it, a new node is created. This class also has an id marked @Id and @GeneratedValue. Neo4j uses this field internally to track the data.

The next important piece is the set of referrals. 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. The default direction is OUTGOING, meaning the REFERRED relationship points from this person to each person they have referred.

With the referred() method, you can easily record who referred whom.

Finally, you have a convenient toString() method to print out the person’s name and who they have referred.

Create Simple Queries

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:

package com.example.accessingdataneo4j;

import java.util.List;

import org.jspecify.annotations.Nullable;
import org.springframework.data.neo4j.repository.Neo4jRepository;

public interface PersonRepository extends Neo4jRepository<Person, Long> {

  @Nullable
  Person findByName(String name);

  List<Person> findByReferralsName(String name);
}

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 findByReferralsName, which traverses the REFERRED relationship in reverse: given a person’s name, it returns all Person nodes that have referred them.

Permissions to Access Neo4j

Neo4j Community Edition requires credentials to access it. You can configure these credential by setting a couple of properties (in src/main/resources/application.properties), as the following listing shows:

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

This includes the default username (neo4j) and the newly set password we picked earlier (spring+neo4j).

Do NOT store real credentials in your source repository. Instead, configure them in your runtime using Spring Boot’s property overrides.

With this in place, you can wire this up and see what it looks like!

Create an Application Class

Spring Initializr creates a simple class for the application. The following listing shows the class that Initializr created for this example (in src/main/java/com/example/accessingdataneo4j/AccessingDataNeo4jApplication.java):

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

}

@SpringBootApplication is a convenience annotation that adds all of the following:

  • @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.

Logging output is displayed. The service should be up and running within a few seconds.

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 has referred anyone (yet).

At first, you find Greg, indicate that he referred Roy and Craig, and then persist him. Because the relationship direction is OUTGOING, only Greg’s outgoing REFERRED relationships are saved at this point.

Next, you fetch Roy fresh from Neo4j (to ensure you have the latest state of that node) and record that he referred Craig, then persist Roy.

Craig has no referrals yet in this example, so no additional code is needed for Craig. You can see the results as you iterate over each person and print their information to the console.

Finally, check out that other query where you look backwards, answering the question of "Who referred Craig?"

The following listing shows the finished AccessingDataNeo4jApplication class (at src/main/java/com/example/accessingdataneo4j/AccessingDataNeo4jApplication.java):

package com.example.accessingdataneo4j;

import java.util.Arrays;
import java.util.List;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

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.referred(roy);
			greg.referred(craig);
			personRepository.save(greg);

			roy = personRepository.findByName(roy.getName());
			roy.referred(craig);
			personRepository.save(roy);

			// Craig has no referrals yet

			log.info("Lookup each person by name...");
			team.stream().forEach(person -> log.info(
					"\t" + personRepository.findByName(person.getName()).toString()));

			List<Person> referrers = personRepository.findByReferralsName(craig.getName());
			log.info("The following referred Craig...");
			referrers.stream().forEach(person -> log.info("\t" + person.getName()));
		};
	}

}

Build an executable JAR

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:

java -jar build/libs/gs-accessing-data-neo4j-0.0.1-SNAPSHOT.jar

If you use Maven, you can run the application by using ./mvnw spring-boot:run. Alternatively, you can build the JAR file with ./mvnw clean package and then run the JAR file, as follows:

java -jar target/gs-accessing-data-neo4j-0.0.1-SNAPSHOT.jar

You should see something similar to the following listing (with other stuff, such as queries, as well):

Before linking up with Neo4j...
	Greg referred => []
	Roy referred => []
	Craig referred => []

Lookup each person by name...
	Greg referred => [Roy, Craig]
	Roy referred => [Craig]
	Craig referred => []

The following referred Craig...
	Greg
	Roy

You can see from the output that (initially) no one has referred anyone. Then, after you establish the relationships, you can see who referred whom. Finally, you can see the handy reverse lookup that finds everyone who referred a given person.

Summary

Congratulations! You just set up an embedded Neo4j server, stored some simple related entities, and developed some quick queries.

If you want to expose Neo4j repositories with a hypermedia-based RESTful front end with little effort, read Accessing Neo4j Data with REST.

See Also

The following guides may also be helpful:

Want to write a new guide or contribute to an existing one? Check out our contribution guidelines.

All guides are released with an ASLv2 license for the code, and an Attribution, NoDerivatives creative commons license for the writing.

Get the Code

Go To Repo