/spring-data-neo4j

name: spring-data-neo4j
description: Provides Spring Data Neo4j integration patterns for Spring Boot applications. Use when you need to work with a graph database, Neo4j nodes and relationships, Cypher queries, or Spring Data Neo4j. Creates node entities with @Node annotation, defines relationships with @Relationship, writes Cypher queries using @Query, configures imperative and reactive Neo4j repositories, implements graph traversal patterns, and sets up testing with embedded databases.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep

Spring Data Neo4j Integration Patterns

Overview

Provides Spring Data Neo4j integration patterns for Spring Boot applications. Covers node entity mapping with `@Node` and `@Relationship`, repository configuration (imperative and reactive), custom Cypher queries with `@Query`, and integration testing with embedded Neo4j databases.

When to Use

Use this skill when working with:

• Graph databases and Neo4j integration in Spring Boot
• Node entities, relationships, and Cypher queries
• Spring Data Neo4j repositories (imperative or reactive)
• Neo4j testing with embedded databases

Instructions

1. Set Up Spring Data Neo4j

**Add the dependency:**

Maven:

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

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-data-neo4j'

**Configure connection in application.properties:**

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

**Configure Cypher-DSL dialect (recommended):**

@Configuration
public class Neo4jConfig {
    @Bean
    Configuration cypherDslConfiguration() {
        return Configuration.newConfig()
            .withDialect(Dialect.NEO4J_5).build();
    }
}

> **Validation Checkpoint**: Run `MATCH (n) RETURN count(n)` via cypher-shell to verify the connection works before proceeding.

2. Define Node Entities

1. **Use `@`Node annotation** to mark entity classes 2. **Choose ID strategy:**

• Business key as `@`Id (immutable, natural identifier)
• Generated `@`Id `@`GeneratedValue (Neo4j internal ID)

3. **Define relationships** with `@`Relationship annotation 4. **Keep entities immutable** with final fields 5. **Use `@`Property** for custom property names

> **Validation Checkpoint**: If entity save fails, check for constraint violations—duplicate IDs violate uniqueness constraints.

3. Create Repositories

1. **Extend repository interface:**

• `Neo4jRepository<Entity, ID>` for imperative operations
• `ReactiveNeo4jRepository<Entity, ID>` for reactive operations

2. **Use query derivation** for simple queries 3. **Apply `@`Query annotation** for complex Cypher queries 4. **Use `$`paramName syntax** for parameters

> **Validation Checkpoint**: Test repository with `findAll()` first—if empty, verify the Neo4j instance is running and credentials are correct.

4. Test Your Implementation

1. **Use `@`DataNeo4jTest** for repository testing with test slicing 2. **Set up Neo4j Harness** with embedded database and fixtures 3. **Provide test data** via `withFixture()` Cypher queries 4. **Clean up test data** between tests

> **Validation Checkpoint**: If tests fail with "Connection refused", ensure the embedded Neo4j started successfully in `@BeforeAll`.

Basic Entity Mapping

Node Entity with Business Key

@Node("Movie")
public class MovieEntity {

    @Id
    private final String title;  // Business key as ID

    @Property("tagline")
    private final String description;

    private final Integer year;

    @Relationship(type = "ACTED_IN", direction = Direction.INCOMING)
    private List<Roles> actorsAndRoles = new ArrayList<>();

    @Relationship(type = "DIRECTED", direction = Direction.INCOMING)
    private List<PersonEntity> directors = new ArrayList<>();

    public MovieEntity(String title, String description, Integer year) {
        this.title = title;
        this.description = description;
        this.year = year;
    }
}

Node Entity with Generated ID

@Node("Movie")
public class MovieEntity {

    @Id @GeneratedValue
    private Long id;

    private final String title;

    @Property("tagline")
    private final String description;

    public MovieEntity(String title, String description) {
        this.id = null;  // Never set manually
        this.title = title;
        this.description = description;
    }

    // Wither method for immutability with generated IDs
    public MovieEntity withId(Long id) {
        if (this.id != null && this.id.equals(id)) {
            return this;
        } else {
            MovieEntity newObject = new MovieEntity(this.title, this.description);
            newObject.id = id;
            return newObject;
        }
    }
}

Repository Patterns

Basic Repository Interface

@Repository
public interface MovieRepository extends Neo4jRepository<MovieEntity, String> {

    // Query derivation from method name
    MovieEntity findOneByTitle(String title);

    List<MovieEntity> findAllByYear(Integer year);

    List<MovieEntity> findByYearBetween(Integer startYear, Integer endYear);
}

Reactive Repository

@Repository
public interface MovieRepository extends ReactiveNeo4jRepository<MovieEntity, String> {

    Mono<MovieEntity> findOneByTitle(String title);

    Flux<MovieEntity> findAllByYear(Integer year);
}

**Imperative vs Reactive:**

• Use `Neo4jRepository` for blocking, imperative operations
• Use `ReactiveNeo4jRepository` for non-blocking, reactive operations
• **Do not mix imperative and reactive in the same application**
• Reactive requires Neo4j 4+ on the database side

Custom Queries with `@`Query

@Repository
public interface AuthorRepository extends Neo4jRepository<Author, Long> {

    @Query("MATCH (b:Bo