Skip to main content
skill CX Codex

neo4j-spring-data-skill — Claude Code skill: install

The neo4j-spring-data-skill Claude Code skill supports Spring Boot projects that use Neo4j through Spring Data Neo4j. It comes into play when defining entities, repositories, and Cypher queries in a Spring application.

MIT 427 installs ★ 121 updated 2026-11-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add neo4j-contrib/neo4j-skills --skill neo4j-spring-data-skill -a claude-code
Open on GitHub

What neo4j-spring-data-skill does

The skill covers connecting Neo4j to Spring Boot and accessing the database through Spring Data Neo4j. Its examples include @Node entities and relationships, Neo4jRepository and ReactiveNeo4jRepository interfaces, Cypher in @Query, projections, and application.yml settings.

For custom queries, it describes Neo4jClient and Neo4jTemplate; it also covers transactions, auditing, and vector search with Spring AI's Neo4jVectorStore. The configuration examples read NEO4J_URI, NEO4J_USERNAME, and NEO4J_PASSWORD from environment variables rather than embedding credentials in the config. The version table pairs SDN 8.0.x with Spring Boot 3.3.x / 3.4.x and Java 17+. This skill does not cover standalone Java-driver code or authoring Cypher independently.

What it helps with

  • configure a Spring Boot connection to Neo4j
  • map entities and relationships with SDN annotations
  • define a repository with CRUD and Cypher methods
  • shape and paginate repository results with projections
  • add Neo4jVectorStore search to a Spring application

Example prompts for the agent

  • Set up the Spring Boot connection to Neo4j in application.yml.
  • Model a Person entity with outgoing KNOWS relationships for Spring Data Neo4j.
  • Create a Neo4jRepository method that finds friends using @Query.

How to install neo4j-spring-data-skill

1Skills CLI (Vercel)

npx skills add neo4j-contrib/neo4j-skills --skill neo4j-spring-data-skill -a claude-code

2Manually: put the files in place

~/.claude/skills/neo4j-spring-data-skill/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/neo4j-spring-data-skill/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about neo4j-spring-data-skill

How do I install neo4j-spring-data-skill in Claude Code?

Run npx skills add neo4j-contrib/neo4j-skills --skill neo4j-spring-data-skill -a claude-code. The skill file is placed at ~/.claude/skills/neo4j-spring-data-skill/SKILL.md.

What does neo4j-spring-data-skill do?

It helps build Spring Boot applications with Neo4j through Spring Data Neo4j, covering entity and relationship mapping, repositories, Cypher queries, projections, and connection settings.

Which Spring Data Neo4j and Java versions does neo4j-spring-data-skill cover?

Its version table includes SDN 8.0.x, 8.1.x, and 7.5.x, all paired with Java 17+. For SDN 8.0.x it lists Spring Boot 3.3.x / 3.4.x; for 8.1.x, Spring Boot 3.4.x+.

Source text

SKILL.md · MIT
---
name: neo4j-spring-data-skill
description: Use when building Spring Boot applications with Neo4j using Spring Data Neo4j (SDN 7.x/8.x) —
  @Node entity mapping, @Relationship, @RelationshipProperties, Neo4jRepository, ReactiveNeo4jRepository,
  @Query annotations, application.yml configuration, projections, Neo4jClient, Neo4jTemplate,
  transactions, auditing, or Spring AI Neo4jVectorStore vector search.
  Does NOT handle raw Java driver code without Spring — use neo4j-driver-java-skill.
  Does NOT handle Cypher query authoring — use neo4j-cypher-skill.
  Does NOT handle driver version upgrades — use neo4j-migration-skill.
version: 1.0.5
allowed-tools: Bash WebFetch
---

# Neo4j Spring Data Skill

## When to Use

- Configuring Spring Boot with Neo4j (`spring-boot-starter-data-neo4j`)
- Writing `@Node` entity classes and `@Relationship`/`@RelationshipProperties` mappings
- Defining `Neo4jRepository` or `ReactiveNeo4jRepository` interfaces
- Writing `@Query` annotations with Cypher on repository methods
- Using Spring projections (interface-based, DTO, dynamic) with Neo4j
- Configuring `application.yml` for Neo4j connection
- Custom queries via `Neo4jClient` or `Neo4jTemplate`
- Spring AI `Neo4jVectorStore` for vector search in Spring apps
- Transaction management, auditing, optimistic locking

## When NOT to Use

- **Raw Java driver without Spring** → `neo4j-driver-java-skill`
- **Cypher query authoring** → `neo4j-cypher-skill`
- **Driver version upgrades** → `neo4j-migration-skill`
- **GDS algorithms** → `neo4j-gds-skill`

---

## Version Matrix

| SDN    | Spring Boot | Spring Framework | Java | Neo4j |
|--------|-------------|-----------------|------|-------|
| 8.0.x  | 3.3.x / 3.4.x | 6.2.x          | 17+  | 5.15+ |
| 8.1.x  | 3.4.x+      | 7.0.x           | 17+  | 5.15+ |
| 7.5.x  | 3.2.x       | 6.1.x           | 17+  | 4.4+  |

Use `spring-boot-starter-data-neo4j` — it pulls SDN + driver. No explicit SDN version needed when using Spring Boot BOM.

---

## Setup

### Maven

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

### Gradle

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

### Reactive stack (add alongside above)

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>
```

---

## Configuration

### application.yml — imperative (standard)

```yaml
spring:
  neo4j:
    uri: ${NEO4J_URI:bolt://localhost:7687}
    authentication:
      username: ${NEO4J_USERNAME:neo4j}
      password: ${NEO4J_PASSWORD}
  data:
    neo4j:
      database: ${NEO4J_DATABASE:neo4j}
```

### application.yml — Aura (TLS required)

```yaml
spring:
  neo4j:
    uri: ${NEO4J_URI}            # neo4j+s://xxxx.databases.neo4j.io
    authentication:
      username: ${NEO4J_USERNAME:neo4j}
      password: ${NEO4J_PASSWORD}
  data:
    neo4j:
      database: ${NEO4J_DATABASE:neo4j}
```

Credentials: store in `.env`; never hardcode. Verify `.env` is in `.gitignore`.

---

## Entity Mapping

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

// Internal generated ID (default for most cases)
@Node("Person")
public class PersonEntity {
    @Id @GeneratedValue private Long id;         // element ID (Long)
    private String name;
    @Property("birth_year") private Integer birthYear;  // custom property name
    @Relationship(type = "KNOWS", direction = Relationship.Direction.OUTGOING)
    private List<PersonEntity> friends = new ArrayList<>();
}

// UUID business key
@Node("Product")
public class ProductEntity {
    @Id @GeneratedValue(generatorClass = GeneratedValue.UUIDStringGenerator.class)
    private String id;
    @Version private Long version;               // optimistic locking; required with business key
}

// User-assigned key (caller sets value; no @GeneratedValue)
@Node("Country")
public class CountryEntity {
    @Id private String isoCode;
    private String name;
}

// Multiple static labels
@Node(primaryLabel = "Vehicle", labels = {"Car", "Auditable"})
public class CarEntity { ... }

// Runtime labels
@Node("Content")
public class ContentEntity {
    @Id @GeneratedValue private Long id;
    @DynamicLabels private Set<String> tags = new HashSet<>();  // labels added at runtime
}
```

---

## Relationship Properties

Use `@RelationshipProperties` when the relationship itself carries data.

```java
@RelationshipProperties
public class RolesRelationship {

    @RelationshipId                     // internal relationship ID; required
    private Long id;

    private List<String> roles;

    @TargetNode                         // marks the other end of the relationship
    private PersonEntity person;
}
```

```java
@Node("Movie")
public class MovieEntity {

    @Id @GeneratedValue
    private Long id;

    private String title;

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

---

## Repository Interfaces

### Basic CRUD

```java
import org.springframework.data.neo4j.repository.Neo4jRepository;

public interface PersonRepository extends Neo4jRepository<PersonEntity, Long> {

    Optional<PersonEntity> findByName(String name);

    List<PersonEntity> findByBirthYearBetween(int from, int to);

    List<PersonEntity> findByNameContainingIgnoreCase(String fragment);

    long countByBirthYearGreaterThan(int year);

    void deleteByName(String name);
}
```

### @Query — custom Cypher

```java
// CORRECT: $param bound parameter
@Query("MATCH (p:Person {name: $name})-[:KNOWS]->(f:Person) RETURN f")
List<PersonEntity> findFriendsOf(String name);

// With pagination
@Query(value = "MATCH (p:Person) RETURN p ORDER BY p.name",
       countQuery = "MATCH (p:Person) RETURN count(p)")
Page<PersonEntity> findAllPaged(Pageable pageable);

// Return relationship-rich entity; map target via @Node return
@Query("MATCH (m:Movie)<-[r:ACTED_IN]-(p:Person {name: $name}) RETURN m, collect(r), collect(p)")
List<MovieEntity> findMoviesActedInBy(String name);
```

**Security rule**: NEVER string-concatenate user input into Cypher. Always use `$paramName`.

### Pagination and sorting

```java
Page<PersonEntity> findByBirthYearGreaterThan(int year, Pageable pageable);

List<PersonEntity> findTop10ByOrderByNameAsc();

List<PersonEntity> findByName(String name, Sort sort);
```

Usage:

```java
Pageable page = PageRequest.of(0, 20, Sort.by("name").ascending());
Page<PersonEntity> result = repo.findByBirthYearGreaterThan(1980, page);
```

---

## Projections

### Interface projection (closed — query-optimizable)

```java
public interface PersonSummary {
    String getName();
    Integer getBirthYear();
}

List<PersonSummary> findByBirthYearLessThan(int year);
```

### DTO projection (record — preferred in Java 17+)

```java
public record PersonDto(String name, Integer birthYear) {}

List<PersonDto> findByName(String name);
```

### Dynamic projection

```java
<T> List<T> findByName(String name, Class<T> type);

// Usage
repo.findByName("Alice", PersonSummary.class);
repo.findByName("Alice", PersonEntity.class);
```

### Open projection — SpEL (disables query optimization)

```java
public interface FullName {
    @Value("#{target.name + ' (' + target.birthYear + ')'}") String getDisplayName();
}
```

---

## Reactive Repository

```java
import org.springframework.data.neo4j.repository.ReactiveNeo4jRepository;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

public interface ReactivePersonRepository extends ReactiveNeo4jRepository<PersonEntity, Long> {

    Mono<PersonEntity> findByName(String name);

    @Query("MATCH (p:Person {name: $name})-[:KNOWS]->(f) RETURN f")
    Flux<PersonEntity> findFriendsOf(String name);
}
```

Do NOT mix imperative and reactive database access in the same application context.

---

## Custom Repository Implementation

Fragment pattern — use when `@Query` is not enough.

```java
// 1. Fragment interface
public interface PersonRepositoryCustom {
    List<PersonEntity> findByComplexCriteria(String criteria);
}

// 2. Impl — must end with "Impl"
public class PersonRepositoryCustomImpl implements PersonRepositoryCustom {
    private final Neo4jClient neo4jClient;
    PersonRepositoryCustomImpl(Neo4jClient c) { this.neo4jClient = c; }

    @Override
    public List<PersonEntity> findByComplexCriteria(String c) {
        return new ArrayList<>(neo4jClient
            .query("MATCH (p:Person) WHERE p.name CONTAINS $c RETURN p").bind(c).to("c")
            .fetchAs(PersonEntity.class)
            .mappedBy((t, r) -> { var e = new PersonEntity(); e.setName(r.get("p").asNode().get("name").asString()); return e; })
            .all());
    }
}

// 3. Compose
public interface PersonRepository extends Neo4jRepository<PersonEntity, Long>, PersonRepositoryCustom {}
```

---

## Neo4jClient — Low-Level Queries

Use when `@Query` is insufficient or you need full control over Cypher execution.

```java
// Bind params + fetch single scalar
neo4jClient.query("MATCH (p:Person {name: $name}) RETURN count(*) AS cnt")
    .bind("Alice").to("name")
    .fetchAs(Long.class)
    .mappedBy((t, r) -> r.get("cnt").asLong())
    .one();

// Bind + run write (no result)
neo4jClient.query("MERGE (p:Person {name: $name})")
    .bind(personName).to("name")
    .run();

// Custom object mapping
neo4jClient.query("MATCH (p:Person)-[:DIRECTED]->(m:Movie) WHERE p.name=$n RETURN p, collect(m) AS movies")
    .bind("Lilly Wachowski").to("n")
    .fetchAs(Director.class)
    .mappedBy((typeSystem, record) -> new Director(
        record.get("p").asNode().get("name").asString(),
        record.get("movies").asList(v -> new Movie(v.get("title").asString()))
    )).one();
```

Full API: [references/neo4j-client.md](references/neo4j-client.md)

---

## Transaction Management

```java
@Service
@Transactional                      // class-level: all methods transactional
public class PersonService {
    @Transactional(readOnly = true) // read-only hint
    public Optional<PersonEntity> findByName(String name) { ... }

    @Transactional                  // explicit write
    public PersonEntity save(PersonEntity p) { return repository.save(p); }
}
```

`Neo4jTransactionManager` auto-configured. Do NOT mix with JPA `PlatformTransactionManager` without explicit qualifier. Use `@Transactional` on concrete class, not interface.

---

## Spring AI — Neo4jVectorStore

### Dependency

```xml
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-neo4j</artifactId>
</dependency>
```

### application.yml

```yaml
spring:
  ai:
    vectorstore:
      neo4j:
        initialize-schema: true         # creates vector index on first run
        index-name: my-index
        embedding-dimension: 1536       # must match your embedding model
        distance-type: cosine           # cosine (default) or euclidean
        label: Document                 # node label for stored chunks
        embedding-property: embedding   # property for the vector
```

Requires Neo4j 5.15+. Reuses `spring.neo4j.*` connection config.

### Usage

```java
@Autowired VectorStore vectorStore;

// Store
vectorStore.add(List.of(new Document("text", Map.of("author", "alice"))));

// Similarity search
List<Document> results = vectorStore.similaritySearch(
    SearchRequest.builder().query("spring neo4j").topK(5).similarityThreshold(0.75).build()
);

// With metadata filter
vectorStore.similaritySearch(
    SearchRequest.builder().query("spring neo4j").topK(5)
        .filterExpression("author == 'alice'").build()
);
```

---

## Common Errors

| Error | Cause | Fix |
|---|---|---|
| `MappingException: Could not find entity` | Entity not scanned | Check `@EnableNeo4jRepositories` base package |
| Relationships null after load | Default depth may skip deep rels | Use `@Query` with `RETURN m, collect(r), collect(p)` |
| N+1 queries | Per-entity relationship fetch | Rewrite with single `@Query`; use projections |
| `OptimisticLockingFailureException` | Stale `@Version` on concurrent write | Retry in service layer |
| `IllegalStateException: Cannot mix reactive/imperative` | Both repo types in same context | Pick one stack |
| Projection null fields | Getter name mismatch | Match getter to property name; check `@Property` alias |
| `@Query` empty with rels | Missing `collect(r), collect(p)` | Return root node + rels + related nodes together |
| `Cannot delete node, node has relationships` | `deleteById` without detach | Use `@Query` with `DETACH DELETE` |
| Transaction not rolling back | `@Transactional` on interface | Apply on concrete service class |

---

## Relationship Loading — Key Rule

SDN loads related entities eagerly up to a configured depth (default: 1 hop). For deeper graphs:

```java
// Explicit @Query to control what gets loaded
@Query("""
    MATCH (m:Movie)<-[r:ACTED_IN]-(p:Person)
    WHERE m.title = $title
    RETURN m, collect(r), collect(p)
    """)
Optional<MovieEntity> findByTitleWithCast(String title);
```

`collect(r), collect(p)` in RETURN is required for SDN to map `@RelationshipProperties` correctly.

---

## References

- [Spring Data Neo4j Reference (8.x)](https://docs.spring.io/spring-data/neo4j/reference/)
- [Spring AI Neo4jVectorStore](https://docs.spring.io/spring-ai/reference/api/vectordbs/neo4j.html)
- [GraphAcademy: Building Neo4j Apps with Spring Data](https://graphacademy.neo4j.com/courses/app-spring-data/)
- [Neo4j Getting Started — SDN](https://neo4j.com/docs/getting-started/languages-guides/java/spring-data-neo4j/)
- [SDN Advanced projections](https://docs.spring.io/spring-data/neo4j/reference/repositories/projections.html)
- [SDN Auditing](https://docs.spring.io/spring-data/neo4j/reference/object-mapping/auditing.html)
- [Modeling pitfalls, projection guide, type mapping](references/modeling-pitfalls.md)

---

## Checklist

- [ ] `@Node` uses explicit label string, not default class name
- [ ] `@Id @GeneratedValue` (or `@Id` + `@Version` for business key with optimistic lock)
- [ ] `@RelationshipProperties` class has `@RelationshipId` and `@TargetNode`
- [ ] `@Relationship` direction is explicit (OUTGOING / INCOMING)
- [ ] `@Query` Cypher uses `$paramName` — no string concatenation
- [ ] Relationship-rich `@Query` returns `collect(r), collect(p)` alongside root node
- [ ] Database name set in `application.yml` (avoids default DB ambiguity)
- [ ] Unique constraint exists in DB for any business key used in repository lookups
- [ ] `@Transactional` on concrete service class (not interface)
- [ ] No imperative + reactive mix in same application context
- [ ] Credentials in env vars; `.env` in `.gitignore`
- [ ] `spring.ai.vectorstore.neo4j.initialize-schema: true` for first run (Spring AI)

© neo4j-contrib · MIT · neo4j-contrib/neo4j-skills

Similar skills

All skills for Backend and APIs →
spring-data-neo4j giuseppe-trisciuoglio spring-data-neo4j — a skill for integrating Neo4j graph database into Spring Boot applications. Teaches how to map nodes and relationships, write Cypher queries, configure repositories, and test with embedded databases. CX Codex +1 4,000installs 315-frameworks-spring-mongodb Juan Antonio Breña Moral 315-frameworks-spring-mongodb — a skill for designing and implementing MongoDB data access in Spring Boot. Covers document modeling, repositories, indexing, optimistic locking, and error handling strategies. CX Codex +1 284installs spring-boot-expert 0xfurai spring-boot-expert is a Claude Code subagent for developing and maintaining Spring Boot applications. It handles work on REST APIs, security, data access, and microservices. CX Codex ★ 1,029repo stars spring-boot-development manutej spring-boot-development — a skill that gives your coding agent a Spring Boot reference: auto-configuration, dependency injection, REST controllers, Spring Data and Spring Security. CX Codex +1 537installs spring-data-jpa giuseppe-trisciuoglio spring-data-jpa is a Claude Code skill for building Spring Data JPA persistence layers. It comes into play for repository, query, relationship, transaction, audit, and pagination work. CX Codex +1 4,300installs convert-jpa-to-spring-data-cosmos official github convert-jpa-to-spring-data-cosmos — a step-by-step Copilot rule for moving a Spring Boot app off JPA and onto Azure Cosmos DB with Spring Data Cosmos. Useful once the migration is already decided. CX Codex +1 ★ 41,430repo stars

From the same set28

The whole set →
neo4j-spark-skill neo4j-spark-skill — a skill for Claude Code that configures data transfer between Neo4j and Apache Spark or Databricks. It provides integration code for the Neo4j Connector for Spark. CX Codex +1 813installs neo4j-driver-dotnet-skill neo4j-driver-dotnet-skill — a Claude Code skill that guides Neo4j .NET Driver v6 integration in C# projects. Triggers on IDriver setup, ASP.NET Core DI registration, or ExecutableQuery calls. CX Codex +1 807installs neo4j-aura-agent-skill Skill for Claude Code manages Neo4j Aura GraphRAG agents via the v2beta1 REST API. Configures CypherTemplate, SimilaritySearch, and Text2Cypher tools on an active AuraDB instance. CX Codex +1 804installs neo4j-snowflake-graph-analytics-skill neo4j-snowflake-graph-analytics-skill — a skill for Claude Code that executes Neo4j Graph Analytics algorithms in Snowflake. Formats projection views with required casting and builds SQL CALL statements without data movement. CX Codex +1 797installs neo4j-nvl-skill neo4j-nvl-skill — a skill for Claude Code and Codex that guides Neo4j graph rendering via NVL. Triggers when wiring interactive graphs in vanilla JS, Vite, or React apps. CX Codex +1 774installs neo4j-mcp-skill Configures the official Neo4j MCP server. It generates client config files, verifies database connectivity, and handles access modes. CX Codex +1 590installs neo4j-migration-skill The neo4j-migration-skill Claude Code skill updates Neo4j driver code and Cypher queries from older releases. It runs for driver upgrades and migrations to Cypher 25. CX Codex +1 525installs neo4j-driver-javascript-skill neo4j-driver-javascript-skill — a Claude Code skill for the official neo4j-driver v6. Activates when configuring connections, sessions, or transaction workflows for Neo4j in Node.js and browser apps. CX Codex +1 454installs

Project sponsors

Companies that keep this analytics open