Neo4j Use Cases

This section documents Spring Boot 4.1.x and Spring Framework 7.0.x on the Java 17/21+ baseline, as described by the official Spring Boot reference documentation and each sub-project’s own site (Spring Data, Spring for Apache Kafka, Micrometer, Project Reactor, springdoc-openapi, Spring gRPC, and the others listed in this section’s Bibliography) — which are the references these pages are written and verified against.

This content was generated with the assistance of AI and should be verified against those official docs before being relied on in production. Spring Boot and its ecosystem continue to evolve; the examples here target the current 4.1.x / 7.0.x releases.

This section’s bibliography lists the reference material consulted while preparing these pages.

The Use Cases & Algorithms in Practice page of the Neo4j Reference explains which graph algorithm answers which business question, in Cypher and Graph Data Science (GDS) procedure calls. The Spring Data Neo4j page documents the mapping and repository layer feature by feature. This section sits between the two: each page takes one scenario and builds the application around it — the domain model, the repositories, the Neo4jClient calls to Cypher, GDS and APOC, the service and REST layers, the scheduled analytics jobs and a Testcontainers integration test — on Spring Boot 4.1 and Spring Data Neo4j 8.1.

The pages do not repeat either of those references. The algorithm rationale is linked to the Neo4j Reference, the mapping annotations are linked to the Spring Data Neo4j page, and the pages concentrate on how the pieces are wired together in a Spring Boot service. Datasets are the ones used on the Neo4j Reference page, so the Cypher result there and the result asserted in the Spring test here can be compared line by line.

Reference architecture

All the use cases share the same shape. Requests arrive through a REST controller or a Kafka listener, a @Service owns the transaction boundary, and the data access is a mix of Spring Data Neo4j repositories (entity-shaped reads and writes) and Neo4jClient (batched UNWIND writes, GDS and APOC calls, flat projections). Expensive analytics do not run in the request: a scheduled job projects a subgraph, runs the algorithm and writes the scores back onto the graph, so that the request path only reads a property or a few relationships.

flowchart LR client["REST client"] --> controller["RestController"] topic["Kafka topic"] --> listener["KafkaListener"] controller --> service["Service layer"] listener --> service service --> repos["SDN repositories"] service --> neo4jclient["Neo4jClient"] job["Scheduled analytics job"] --> neo4jclient repos --> db[("Neo4j with GDS and APOC")] neo4jclient --> db job -. "scores written back" .-> db

The transactional layer, the scheduling with ShedLock and the Kafka listeners are the ones of the existing SpringBoot Reference pages (REST APIs, Kafka messaging and Scheduling & ShedLock), and are not explained again.

The pages of this section

Use case Algorithms and techniques Neo4j Reference section Spring Boot page

Fraud detection

WCC, Louvain, Betweenness Centrality, shared-identifier and transfer-cycle queries

Fraud and AML ring detection

Fraud Detection

Opportunity detection and recommendations

Collaborative filtering in Cypher, Filtered Node Similarity, link prediction, shortest paths for warm introductions

Recommendation engines

Opportunity Detection & Recommendations

Logistics and supply chain

Dijkstra, A*, Yen’s k-shortest paths, Betweenness Centrality, bounded variable-length traversals

Routing and logistics optimization

Logistics & Supply Chain

Identity resolution and KYC

Blocking keys, Node Similarity, WCC, apoc.refactor.mergeNodes

Identity and access graphs (entity resolution)

Identity Resolution & KYC

Graph-based access control

Variable-length path and EXISTS subqueries, Spring Security method security, cached decisions

Identity and access graphs (entity resolution)

Graph-Based Access Control

Dependency and impact analysis

Blast-radius traversals, Betweenness Centrality, Strongly Connected Components

Root-cause and dependency analysis

Dependency & Impact Analysis

Three cross-cutting pages complete the section:

  • Calling Graph Data Science from Spring Boot — the projection lifecycle, the AutoCloseable helper, YIELD mapping, transactions and memory estimates that every use case reuses. Read it first.

  • Testing Graph Use Cases — the Testcontainers recipe, fixtures and ranking-based assertions on non-deterministic algorithms.

  • Production Considerations — schema management, batching, clusters, a dedicated analytics instance, observability and least-privilege users.

Shared project setup

Every example assumes the same project. The starter brings Spring Data Neo4j and the Neo4j Java Driver, and Spring Boot auto-configures the driver, the Neo4jClient, the Neo4jTemplate and the repositories from the connection properties; no Driver bean is declared by hand (Spring Boot — NoSQL, Neo4j).

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-neo4j</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-docker-compose</artifactId>
        <scope>runtime</scope>
        <optional>true</optional>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-data-neo4j-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-testcontainers</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-neo4j</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.testcontainers</groupId>
        <artifactId>testcontainers-junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Spring Boot 4 splits the web starter by stack (spring-boot-starter-webmvc for the servlet controllers used here, see Getting Started) and ships each test slice in its own module: spring-boot-data-neo4j-test provides @DataNeo4jTest (Spring Boot — Auto-configured Data Neo4j Tests). The versions are managed by the Spring Boot parent or BOM, so none is declared (Spring Boot — Dependency Versions). The versions the pages are written against are listed in the version baseline. The connection uses the standard properties:

spring:
  neo4j:
    uri: bolt://localhost:7687
    authentication:
      username: neo4j
      password: ${NEO4J_PASSWORD}

For local development, spring-boot-docker-compose starts the services of a compose.yaml found at the project root and turns the running Neo4j container into connection details, so the properties above are not needed during development (Spring Boot — Docker Compose support). The GDS and APOC plugins are installed by the image through NEO4J_PLUGINS:

services:
  neo4j:
    image: neo4j:2026.10.1
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      NEO4J_AUTH: neo4j/local-dev-password
      NEO4J_PLUGINS: '["graph-data-science", "apoc"]'
    volumes:
      - neo4j-data:/data

volumes:
  neo4j-data:

The Neo4j, GDS and APOC versions must match on year and month, and NEO4J_PLUGINS is a development convenience; see GDS — Docker installation and APOC — Installation. Running the same stack in automated tests is the subject of Testing Graph Use Cases, and the Compose and Testcontainers tooling itself is covered in the sibling Docker reference.

Repositories, Neo4jClient or Neo4jTemplate

Spring Data Neo4j offers three ways to reach the database, and the use-case pages mix them deliberately. They share the same driver and transaction manager, so they can be combined in one @Transactional service method.

API Use it for Used in this section for

Neo4jRepository and @Query

Entity-shaped CRUD, derived finders, paging and sorting, auditing, and custom Cypher whose result maps onto a @Node graph

Loading and saving accounts, services or users; transactional lookups such as the permission check (Spring Data Neo4j — Repositories)

Neo4jClient

Flat projections to records, batched UNWIND writes, multi-statement or dynamically built Cypher, and every GDS and APOC procedure call

Projecting graphs, running algorithms, writing scores back and merging nodes (Spring Data Neo4j — Neo4j Client)

Neo4jTemplate

Programmatic entity operations when a repository interface is awkward: saving a batch of entities, finding by an ad hoc Cypher statement, with the same mapping as a repository

Not needed; the pages use a repository for entities and the client for everything else (Spring Data Neo4j — Custom queries)

GDS has no official Java client library, so the pages always call it as Cypher through Neo4jClient; the helper that does so is in Calling Graph Data Science from Spring Boot.

See also

  • Neo4j Reference — the Cypher, indexing, GDS and operations background for every page of this section.

  • Spring Data Neo4j — the mapping, repository and Neo4jClient features applied here.

  • Unit and Integration Testing — the general Testcontainers and slice-test background.

  • This section does not cover knowledge-graph retrieval-augmented generation (GraphRAG), text-to-Cypher or the Neo4j vector store. Those are the subject of the Spring AI work tracked in GitHub issue #197 and the RAG systems in production work tracked in GitHub issue #208.