This tutorial explains how to integrate Neo4j with Spring Boot using Java, including node creation, relationships, Cypher queries, and a complete REST API example.

Let’s be honest.

Every backend developer eventually reaches that moment when SQL joins start looking like a family tree diagram from a complicated soap opera.

You write one JOIN.
Then another JOIN.
Then a JOIN on a JOIN.
Suddenly your query looks like this:

SELECT * FROM users
JOIN friends ON ...
JOIN friends_of_friends ON ...
JOIN friends_of_friends_of_friends ON ...

And you sit there wondering:

“Why am I doing this to myself?”

That’s usually the moment when someone on your team says:

“Maybe we should try Neo4j.”

And just like that, you enter the world of graph databases.

In this guide we’ll walk through how to integrate Neo4j with Spring Boot, step by step.

No complex jargon.
Just Java, graphs, and a little bit of developer sanity.

What is Neo4j (In Simple Words)

Traditional databases store data in tables.

Neo4j stores data as a graph.

Instead of tables and joins, Neo4j uses:

• Nodes → entities (User, Movie, Product)
• Relationships → connections between nodes
• Properties → attributes

Example:

(User)-[:FRIENDS_WITH]->(User)
(User)-[:WATCHED]->(Movie)

So instead of writing crazy joins, Neo4j lets you simply traverse relationships.

Why Use Neo4j with Spring Boot

If you’re building backend systems with Java, Spring Boot + Neo4j is a powerful combo.

It works great for systems involving relationships like:

• Social networks
• Recommendation systems
• Knowledge graphs
• Network analysis
• Dependency graphs

In other words, if your data looks like connections instead of spreadsheets, Neo4j is your friend.

Actual Tutorial/Guide

Step 1 — Create a Spring Boot Project

You can generate your project from :

https://start.spring.io

Select:

Spring Web
Spring Data Neo4j
Lombok (optional but nice)

Your project structure will look something like this:

src
 ├── controller
 ├── service
 ├── repository
 └── model

Pretty standard Spring Boot setup.

Nothing scary yet.

Step 2 — Add Neo4j Dependency

If you didn’t add it earlier, include this in your pom.xml.

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-data-neo4j</artifactId>
</dependency>

Spring Boot will handle most of the configuration automatically, which is nice because developers are lazy by design.

Step 3 — Configure Neo4j Connection

In your application.properties:

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

The Bolt protocol is Neo4j’s fast binary protocol.
Translation: Your queries travel faster than your debugging sessions.

Step 4 — Create a Node Entity

Let’s create a simple Person node.

import org.springframework.data.neo4j.core.schema.*;
import java.util.*;

@Node("Person")
public class Person {

    @Id
    @GeneratedValue
    private Long id;

    private String name;

    @Relationship(type = "FRIENDS_WITH")
    private List<Person> friends = new ArrayList<>();

    public Person() {}

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

    public void addFriend(Person friend){
        this.friends.add(friend);
    }

    // getters setters
}

This tells Spring Boot:

“Hey, this class represents a node in Neo4j.”

Simple enough.

Step 5 — Create Repository Layer

Spring Data Neo4j works very similarly to JPA.

Create a repository:

import org.springframework.data.neo4j.repository.Neo4jRepository;
import org.springframework.stereotype.Repository;

@Repository
public interface PersonRepository 
        extends Neo4jRepository<Person, Long> {

}

Boom. You now have methods like:

• save()
• findById()
• findAll()
• delete()

Spring generates them automatically, which means less code and fewer headaches.

Step 5.1 — Writing a Cypher Query

Neo4j uses a query language called Cypher.

Example query:

MATCH (p:Person)
RETURN p

In Spring Boot:

@Query("MATCH (p:Person{city:'Melbourne'}) RETURN p")
List<Person> getAllPeopleInMelbourne();

Cypher is actually very readable. Almost like English, which is refreshing compared to some SQL queries. This way you can have your custom queries.

Step 6 — Service Layer

Service contains business logic.

import org.springframework.stereotype.Service;
import java.util.*;

@Service
public class PersonService {

    private final PersonRepository repository;

    public PersonService(PersonRepository repository) {
        this.repository = repository;
    }

    public Person createPerson(String name) {
        Person person = new Person(name);
        return repository.save(person);
    }

    public Person addFriend(Long personId, Long friendId) {

        Person person = repository.findById(personId).orElseThrow();
        Person friend = repository.findById(friendId).orElseThrow();

        person.addFriend(friend);

        return repository.save(person);
    }

    public List<Person> getAllPersons(){
        return repository.findAll();
    }
}

Important line:

person.addFriend(friend);

This creates the relationship.

Step 7 — REST Controller

Controller handles HTTP requests.

import org.springframework.web.bind.annotation.*;
import java.util.*;

@RestController
@RequestMapping("/api/persons")
public class PersonController {

    private final PersonService service;

    public PersonController(PersonService service) {
        this.service = service;
    }

    @PostMapping
    public Person createPerson(@RequestParam String name){
        return service.createPerson(name);
    }

    @PostMapping("/{id}/friend/{friendId}")
    public Person addFriend(@PathVariable Long id,
                            @PathVariable Long friendId){

        return service.addFriend(id, friendId);
    }

    @GetMapping
    public List<Person> getAllPersons(){
        return service.getAllPersons();
    }
}

Now we have endpoints:

POST /api/persons?name=Alice
POST /api/persons?name=Bob
POST /api/persons/1/friend/2
GET  /api/persons

Nice and simple.

Step 8 — Check Data in Neo4j

Open Neo4j Browser and run:

MATCH (p:Person)-[r:FRIENDS_WITH]->(f:Person)
RETURN p,r,f

Graph result:

(Alice)-[:FRIENDS_WITH]->(Bob)

Your graph relationship is now created successfully.

When Neo4j Is a Great Choice

Neo4j shines when your data has many relationships.

Examples:

• Social networks
• Recommendation engines
• Fraud detection
• Knowledge graphs
• Dependency tracking

If your data is basically a network, Neo4j will outperform relational databases.

Neo4j Performance Tips

A few things developers learn the hard way.

Save yourself some pain:

Create Indexes

Indexes speed up lookups.

Example:

CREATE INDEX FOR (p:Person) ON (p.name)

---

Avoid Deep Traversals

Traversing 8–10 hops can get expensive.

Keep relationships meaningful.

---

Model Relationships Carefully

Graph performance depends heavily on good data modeling.

Bad graph design = slow queries.

Just like bad schema design in SQL.

Conclusion

Integrating Neo4j with Spring Boot is surprisingly easy.

Spring Data Neo4j handles most of the heavy lifting, allowing developers to focus on:

• graph modeling
• business logic
• building useful APIs

Instead of writing giant SQL joins that slowly destroy your happiness.

If you’re a Java developer working with connected data, Neo4j is definitely worth exploring.

Your future self will thank you.

And your queries will look a lot less terrifying.

Get your Neo4j Certified Professional Certificate from GraphAcademy.

Also checkout the recommendation engine using Neo4j and Springboot

---