MACRO NEPAL
Unlocking Connected Data: A Comprehensive Guide to Neo4j Graph Database in Java
awiskar acharya
November 8, 2025
2:27 pm

Graph databases have revolutionized how we handle highly connected data, and Neo4j stands as the most popular and mature graph database in the ecosystem. Unlike traditional relational databases that struggle with complex relationships, Neo4j treats relationships as first-class citizens, making it ideal for social networks, recommendation engines, fraud detection, and knowledge graphs. This article provides a complete guide to using Neo4j with Java, from basic concepts to advanced implementations.

Why Neo4j? The Graph Database Advantage

Traditional Databases vs. Graph Databases:

  • Relational Databases: Use JOINs for relationships, which become expensive and complex with deep connections
  • Graph Databases: Store relationships natively, maintaining constant-time traversal regardless of graph size
  • Performance: Relationships are stored as pointers, making traversals O(1) rather than O(n) or worse

Use Cases for Neo4j:

  • Social networks and relationship mapping
  • Recommendation engines
  • Fraud detection systems
  • Network and IT infrastructure management
  • Knowledge graphs and semantic searches
  • Master data management

Neo4j Core Concepts

1. Nodes: Entities in the graph (similar to rows in RDBMS)
2. Relationships: Connections between nodes (with direction and type)
3. Properties: Key-value pairs on both nodes and relationships
4. Labels: Group nodes into sets (similar to tables in RDBMS)

Example:

(Person:User {name: "Alice", age: 30})-[:FRIENDS_WITH {since: 2020}]->(Person:User {name: "Bob", age: 25})

Project Setup and Dependencies

Add Neo4j Java Driver to your project:

Maven:

<dependency>
<groupId>org.neo4j.driver</groupId>
<artifactId>neo4j-java-driver</artifactId>
<version>5.15.0</version>
</dependency>

Gradle:

implementation 'org.neo4j.driver:neo4j-java-driver:5.15.0'

Docker Setup (Quick Start):

docker run --name neo4j -p 7474:7474 -p 7687:7687 \
-e NEO4J_AUTH=neo4j/password \
-d neo4j:5.15.0

Access Neo4j Browser at: http://localhost:7474

Basic Neo4j Java Driver Usage

Establishing Connection:

import org.neo4j.driver.*;
public class Neo4jConnection {
private static final String URI = "bolt://localhost:7687";
private static final String USER = "neo4j";
private static final String PASSWORD = "password";
public static Driver createDriver() {
return GraphDatabase.driver(URI, AuthTokens.basic(USER, PASSWORD));
}
}

Basic CRUD Operations:

import org.neo4j.driver.*;
import static org.neo4j.driver.Values.parameters;
public class BasicOperations {
public static void createUser(Driver driver, String name, String email) {
try (Session session = driver.session()) {
String query = "CREATE (u:User {name: $name, email: $email, created: timestamp()}) RETURN u";
Record record = session.writeTransaction(tx -> {
Result result = tx.run(query, parameters("name", name, "email", email));
return result.single();
});
System.out.println("Created user: " + record.get("u").get("name").asString());
}
}
public static void findUser(Driver driver, String name) {
try (Session session = driver.session()) {
String query = "MATCH (u:User {name: $name}) RETURN u.name AS name, u.email AS email";
session.readTransaction(tx -> {
Result result = tx.run(query, parameters("name", name));
while (result.hasNext()) {
Record record = result.next();
System.out.println("User: " + record.get("name") + ", Email: " + record.get("email"));
}
return null;
});
}
}
public static void updateUser(Driver driver, String oldName, String newName) {
try (Session session = driver.session()) {
String query = "MATCH (u:User {name: $oldName}) SET u.name = $newName RETURN u";
session.writeTransaction(tx -> {
Result result = tx.run(query, parameters("oldName", oldName, "newName", newName));
System.out.println("Updated " + result.consume().counters().nodesCreated() + " users");
return null;
});
}
}
public static void deleteUser(Driver driver, String name) {
try (Session session = driver.session()) {
String query = "MATCH (u:User {name: $name}) DELETE u";
session.writeTransaction(tx -> {
Result result = tx.run(query, parameters("name", name));
System.out.println("Deleted " + result.consume().counters().nodesDeleted() + " users");
return null;
});
}
}
public static void main(String[] args) {
try (Driver driver = Neo4jConnection.createDriver()) {
createUser(driver, "Alice", "[email protected]");
createUser(driver, "Bob", "[email protected]");
findUser(driver, "Alice");
updateUser(driver, "Alice", "Alice Smith");
deleteUser(driver, "Bob");
}
}
}

Advanced Graph Operations

Creating Relationships:

public class RelationshipOperations {
public static void createFriendship(Driver driver, String person1, String person2) {
try (Session session = driver.session()) {
String query = 
"MATCH (a:User {name: $name1}), (b:User {name: $name2}) " +
"CREATE (a)-[r:FRIENDS_WITH {since: $since}]->(b) " +
"RETURN a.name, b.name, r.since";
session.writeTransaction(tx -> {
Result result = tx.run(query, 
parameters("name1", person1, "name2", person2, "since", 2024));
Record record = result.single();
System.out.printf("Created friendship: %s -[FRIENDS_WITH]-> %s since %d%n",
record.get("a.name"), record.get("b.name"), record.get("r.since").asInt());
return null;
});
}
}
public static void findFriendsOfFriends(Driver driver, String userName) {
try (Session session = driver.session()) {
String query = 
"MATCH (user:User {name: $name})-[:FRIENDS_WITH*2]->(fof:User) " +
"WHERE user <> fof " +
"RETURN DISTINCT fof.name AS friendName";
session.readTransaction(tx -> {
Result result = tx.run(query, parameters("name", userName));
System.out.println("Friends of friends for " + userName + ":");
while (result.hasNext()) {
Record record = result.next();
System.out.println(" - " + record.get("friendName").asString());
}
return null;
});
}
}
}

Complex Queries and Path Finding:

public class AdvancedQueries {
public static void findShortestPath(Driver driver, String startUser, String endUser) {
try (Session session = driver.session()) {
String query = 
"MATCH path = shortestPath((start:User {name: $startName})-[*]-(end:User {name: $endName})) " +
"RETURN [node in nodes(path) | node.name] AS pathNodes, " +
"       length(path) AS distance";
session.readTransaction(tx -> {
Result result = tx.run(query, 
parameters("startName", startUser, "endName", endUser));
if (result.hasNext()) {
Record record = result.next();
System.out.println("Shortest path: " + record.get("pathNodes"));
System.out.println("Distance: " + record.get("distance"));
} else {
System.out.println("No path found");
}
return null;
});
}
}
public static void recommendFriends(Driver driver, String userName) {
try (Session session = driver.session()) {
String query = 
"MATCH (user:User {name: $name})-[:FRIENDS_WITH]->(friend)-[:FRIENDS_WITH]->(suggestion) " +
"WHERE NOT (user)-[:FRIENDS_WITH]->(suggestion) AND user <> suggestion " +
"RETURN suggestion.name AS name, count(*) AS commonFriends " +
"ORDER BY commonFriends DESC " +
"LIMIT 5";
session.readTransaction(tx -> {
Result result = tx.run(query, parameters("name", userName));
System.out.println("Friend recommendations for " + userName + ":");
while (result.hasNext()) {
Record record = result.next();
System.out.printf(" - %s (%d mutual friends)%n",
record.get("name").asString(), record.get("commonFriends").asInt());
}
return null;
});
}
}
}

Domain Model and Repository Pattern

Domain Classes:

public class User {
private Long id;
private String name;
private String email;
private LocalDateTime created;
// Constructors, getters, setters
public User() {}
public User(String name, String email) {
this.name = name;
this.email = email;
this.created = LocalDateTime.now();
}
// Getters and setters...
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public String getEmail() { return email; }
public void setEmail(String email) { this.email = email; }
public LocalDateTime getCreated() { return created; }
public void setCreated(LocalDateTime created) { this.created = created; }
}
public class Friendship {
private Long id;
private User fromUser;
private User toUser;
private int since;
// Constructors, getters, setters
public Friendship(User fromUser, User toUser, int since) {
this.fromUser = fromUser;
this.toUser = toUser;
this.since = since;
}
// Getters and setters...
}

Repository Implementation:

import org.neo4j.driver.*;
import org.neo4j.driver.Record;
import org.neo4j.driver.types.Node;
import java.util.*;
public class UserRepository {
private final Driver driver;
public UserRepository(Driver driver) {
this.driver = driver;
}
public User save(User user) {
try (Session session = driver.session()) {
String query = 
"CREATE (u:User {name: $name, email: $email, created: $created}) " +
"RETURN u";
return session.writeTransaction(tx -> {
Result result = tx.run(query,
parameters("name", user.getName(), 
"email", user.getEmail(),
"created", user.getCreated().toString()));
Record record = result.single();
return mapNodeToUser(record.get("u").asNode());
});
}
}
public Optional<User> findByName(String name) {
try (Session session = driver.session()) {
String query = "MATCH (u:User {name: $name}) RETURN u LIMIT 1";
return session.readTransaction(tx -> {
Result result = tx.run(query, parameters("name", name));
if (result.hasNext()) {
Record record = result.next();
return Optional.of(mapNodeToUser(record.get("u").asNode()));
}
return Optional.empty();
});
}
}
public List<User> findAll() {
try (Session session = driver.session()) {
String query = "MATCH (u:User) RETURN u ORDER BY u.name";
return session.readTransaction(tx -> {
Result result = tx.run(query);
List<User> users = new ArrayList<>();
while (result.hasNext()) {
Record record = result.next();
users.add(mapNodeToUser(record.get("u").asNode()));
}
return users;
});
}
}
public void createFriendship(String user1Name, String user2Name, int since) {
try (Session session = driver.session()) {
String query = 
"MATCH (a:User {name: $name1}), (b:User {name: $name2}) " +
"CREATE (a)-[r:FRIENDS_WITH {since: $since}]->(b)";
session.writeTransaction(tx -> {
tx.run(query, 
parameters("name1", user1Name, "name2", user2Name, "since", since));
return null;
});
}
}
public List<User> findFriends(String userName) {
try (Session session = driver.session()) {
String query = 
"MATCH (:User {name: $name})-[:FRIENDS_WITH]->(friend:User) " +
"RETURN friend ORDER BY friend.name";
return session.readTransaction(tx -> {
Result result = tx.run(query, parameters("name", userName));
List<User> friends = new ArrayList<>();
while (result.hasNext()) {
Record record = result.next();
friends.add(mapNodeToUser(record.get("friend").asNode()));
}
return friends;
});
}
}
private User mapNodeToUser(Node node) {
User user = new User();
user.setId(node.id());
user.setName(node.get("name").asString());
user.setEmail(node.get("email").asString());
if (node.get("created") != null) {
user.setCreated(LocalDateTime.parse(node.get("created").asString()));
}
return user;
}
}

Spring Data Neo4j Integration

For Spring Boot applications, use Spring Data Neo4j:

Dependencies:

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

Entity Configuration:

import org.springframework.data.neo4j.core.schema.*;
import java.util.*;
@Node("User")
public class UserEntity {
@Id @GeneratedValue
private Long id;
@Property("name")
private String username;
private String email;
private LocalDateTime created;
@Relationship(type = "FRIENDS_WITH", direction = Relationship.Direction.OUTGOING)
private Set<FriendshipRelationship> friends = new HashSet<>();
// Constructors, getters, setters
}
@RelationshipProperties
public class FriendshipRelationship {
@Id @GeneratedValue
private Long id;
@TargetNode
private UserEntity friend;
@Property("since")
private int year;
// Constructors, getters, setters
}

Repository Interface:

import org.springframework.data.neo4j.repository.Neo4jRepository;
import org.springframework.data.neo4j.repository.query.Query;
import java.util.List;
import java.util.Optional;
public interface UserRepository extends Neo4jRepository<UserEntity, Long> {
Optional<UserEntity> findByUsername(String username);
@Query("MATCH (u:User)-[:FRIENDS_WITH]->(friend:User) WHERE u.username = $username RETURN friend")
List<UserEntity> findFriendsByUsername(String username);
@Query("MATCH (u:User)-[:FRIENDS_WITH*2]->(fof:User) WHERE u.username = $username RETURN DISTINCT fof")
List<UserEntity> findFriendsOfFriends(String username);
}

Best Practices and Performance

1. Use Parameterized Queries:

// GOOD - Parameterized (prevents injection, allows caching)
String query = "MATCH (u:User {name: $name}) RETURN u";
tx.run(query, parameters("name", userName));
// BAD - String concatenation (vulnerable to injection)
String badQuery = "MATCH (u:User {name: '" + userName + "'}) RETURN u";

2. Use Indexes:

CREATE INDEX user_name_index FOR (u:User) ON (u.name);
CREATE INDEX user_email_index FOR (u:User) ON (u.email);

3. Batch Operations:

public void createUsersInBatch(Driver driver, List<User> users) {
try (Session session = driver.session()) {
String query = 
"UNWIND $users AS user " +
"CREATE (u:User {name: user.name, email: user.email}) " +
"RETURN count(u)";
session.writeTransaction(tx -> {
Map<String, Object> params = new HashMap<>();
params.put("users", users.stream()
.map(user -> Map.of("name", user.getName(), "email", user.getEmail()))
.collect(Collectors.toList()));
Result result = tx.run(query, params);
System.out.println("Created " + result.single().get(0).asInt() + " users");
return null;
});
}
}

4. Connection Management:

public class Neo4jService implements AutoCloseable {
private final Driver driver;
public Neo4jService(String uri, String user, String password) {
this.driver = GraphDatabase.driver(uri, AuthTokens.basic(user, password));
// Verify connectivity
driver.verifyConnectivity();
}
@Override
public void close() {
driver.close();
}
}

Error Handling and Resilience

public class ResilientNeo4jService {
private final Driver driver;
public ResilientNeo4jService(Driver driver) {
this.driver = driver;
}
public <T> T executeWithRetry(TransactionWork<T> work, int maxRetries) {
int attempt = 0;
while (attempt < maxRetries) {
try (Session session = driver.session()) {
return session.writeTransaction(work);
} catch (ServiceUnavailableException e) {
attempt++;
if (attempt >= maxRetries) {
throw new RuntimeException("Failed after " + maxRetries + " attempts", e);
}
try {
Thread.sleep(100 * attempt); // Exponential backoff
} catch (InterruptedException ie) {
Thread.currentThread().interrupt();
throw new RuntimeException("Interrupted during retry", ie);
}
}
}
throw new RuntimeException("Unexpected error in executeWithRetry");
}
}

Conclusion

Neo4j with Java provides a powerful platform for building applications that leverage connected data:

  • Native Relationship Handling: Constant-time traversals regardless of graph size
  • Cypher Query Language: Intuitive and powerful graph querying
  • Java Driver: Robust, production-ready driver with async support
  • Spring Integration: Seamless integration with Spring ecosystem
  • Performance: Excellent for complex relationship queries

When to Choose Neo4j:

  • Your data is highly connected with complex relationships
  • You need to traverse relationships frequently and efficiently
  • Your queries involve path finding or pattern matching
  • Your data model evolves frequently

By mastering Neo4j with Java, you can build sophisticated applications that reveal insights hidden in the connections between your data, enabling powerful features like recommendations, fraud detection, and network analysis that would be challenging with traditional databases.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper