Spring Data Neo4j (SDN)

Spring Data Neo4j (SDN) uses annotations to map Java/Kotlin objects to Neo4j nodes and relationships. While mapping can work with plain POJOs without annotations, using them allows the classpath scanner to pre-process metadata, improving performance by avoiding runtime metadata construction during the first save operation.

SDN Annotations

• @Node: Marks a class as a candidate for mapping to a node.
• @Id: Marks the field used for identity.
• @GeneratedValue: Used with @Id to specify identifier generation strategy.
• @Property: Modifies the mapping from a class attribute to a specific Neo4j property name.
• @CompositeProperty: Used for Map type attributes to be read back as a composite.
• @Relationship: Specifies details of a relationship (type and direction).
• @DynamicLabels: Marks a collection (e.g., List<String>) as a source for runtime-managed labels.
• @RelationshipProperties: Marks a class as the target for properties residing on a relationship.
• @TargetNode: Marks the target of a relationship within a @RelationshipProperties class.

Spring Data Commons Annotations

• @Id: (Same as SDN @Id)
• @CreatedBy / @CreatedDate: Auditing annotations for creator info.
• @LastModifiedBy / @LastModifiedDate: Auditing annotations for modifier info.
• @PersistenceCreator: Marks the preferred constructor for reading entities.
• @Persistent: Marks a class as a candidate for mapping (similar to @Node).
• @Version: Used for optimistic locking.
• @ReadOnlyProperty: Marks a property as read-only (hydrated on read, but not written).

When loading data, SDN uses Cypher map projections and pattern comprehensions to ensure only the properties and relationships defined in your Java model are queried.

Key Components of a Load Query:

• ID Mapping: SDN uses a special field ${neo4jInternalId} (which resolves to id(n) or your custom ID) to map database nodes back to Java objects.
• Label Mapping: The ${neo4jLabels} field (resolving to labels(n)) is used to handle inheritance and ensure nodes are mapped to the correct concrete classes.
• Relationship Mapping: Relationships are returned using pattern comprehensions.

Example Map Projection:

RETURN n{.first_name, .personNumber, {neo4jInternalId}: id(n), {neo4jLabels}: labels(n)}

Example with Relationships:

RETURN n{.first_name, ..., Person_Has_Hobby: [(n)-[:Has]->(n_hobbies:Hobby)|n_hobbies{{neo4jInternalId}: id(n_hobbies), .name, {neo4jLabels}: labels(n_hobbies)}]}

Handling Cycles: If your schema contains self-referencing nodes or potential cycles, SDN falls back to a cascading/data-driven query creation. It executes an initial query and then iteratively executes further queries on the fly for discovered relationships until no new nodes or relationships are found.

// Example of a load query with map projection and pattern comprehension
RETURN n{.first_name, ..., Person_Has_Hobby: [(n)-[:Has]->(n_hobbies:Hobby)|n_hobbies{{neo4jInternalId}: id(n_hobbies), .name, {neo4jLabels}: labels(n_hobbies)}]}

When you perform a save operation, Spring Data Neo4j (SDN) issues multiple Cypher statements to synchronize the database graph with your Java domain model.

The Save Process:

1. Upsert Node: A UNION statement is used to either CREATE a node (if the identifier is not found) or UPDATE properties (if the node exists).
2. Relationship Cleanup: If the entity is not new, SDN removes all existing relationships of the first found type defined in your domain model to ensure the graph matches the Java state.
3. Related Entity Upsert: The related entity is created/updated using the same logic as the root entity.
4. Relationship Creation: The relationship itself is created using a MERGE statement.
5. Recursion: This process repeats for all defined relationships and nested related entities.

WARNING: Because SDN removes existing relationships to sync the model, you should avoid loading, manipulating, and saving sub-graphs. Doing so may cause relationships in the database that are not present in your partial Java model to be deleted.

// Example of the UNION statement used for upserting a node
OPTIONAL MATCH (hlp:Person) WHERE id(hlp) = ${neo4jId} 
WITH hlp WHERE hlp IS NULL 
CREATE (n:Person) SET n = ${neo4jProperties} 
RETURN id(n) 
UNION 
MATCH (n) WHERE id(n) = ${neo4jId} 
SET n = ${neo4jProperties} 
RETURN id(n)

The @Node annotation marks a class as a managed domain class. It uses the labels attribute (or its alias value) to define the Neo4j labels used for reading and writing.

• Default Behavior: If no label is specified, the simple class name is used as the primary label.
• Multiple Labels: You can provide an array of labels to the labels property. The first element is treated as the primary label.
• Primary Label: This should be the most concrete label reflecting the domain class. SDN writes at least the primary label to the graph, and all nodes with that primary label are mapped back to this class.

Class Hierarchies and Polymorphism

• Inheritance: @Node is not inherited from super-types or interfaces. You must annotate every level of the hierarchy if you want polymorphic queries.
• Abstract Bases: Annotating an abstract base class with @Node allows its labels to be used as additional labels alongside the concrete implementation's labels.
• Interfaces: To support interfaces in a domain model, you must annotate the interface with @Node and ensure the implementing class uses the exact same primary label name to synchronize them.

@Node("SomeInterface")
public interface SomeInterface {
    String getName();
    SomeInterface getRelated();
}

@Node("SomeInterface") // Must match the interface label
public class SomeInterfaceEntity implements SomeInterface {
    @Id
    @GeneratedValue
    private Long id;
    // ...
}