Spring Data Neo4j relationship properties: preserve edge identity

Last updated: 1 Oct 20264 min read

tutorial

A relationship with its own properties needs a mapped identity so saves can distinguish existing edges from new ones.

The edge carries data

A driver assignment has an assignedAt time and a dispatch reason. Those belong to the ASSIGNED_TO relationship, not necessarily to either node. Spring Data Neo4j maps such data with @RelationshipProperties, a @TargetNode and a @RelationshipId field for the generated relationship identity. Without that field, the mapper cannot safely reconcile an existing property-bearing edge on save. Partial graph saves remain a separate risk.

Keep business identity separate

The internal relationship ID is for mapping continuity, not a public assignment number. Store an assignmentId property for external references and enforce its uniqueness in a command workflow. If history requires more than one assignment to the same driver, define whether old edges remain, are ended in place, or move to event nodes.

Exercise a second save

Create an assignment, load it, change only its reason and save it again. Assert one relationship remains and its original assignedAt value survives. Then try a partial projection that omits assignments; it must not delete the historical edges merely because the projection was incomplete.

Implementation sketch

@RelationshipProperties
class DriverAssignment {
    @RelationshipId Long graphRelationshipId;
    String assignmentId;
    Instant assignedAt;
    String reason;
    @TargetNode Driver driver;
}

Cost and verification

Property-bearing edges add mapping and storage work for each relationship. Large collections can make aggregate saves expensive; use focused commands and read projections when history grows.

Common Mistakes

Do not omit @RelationshipId from a relationship-properties class.
Do not expose the internal relationship ID as a stable public identifier.
Do not save a partial aggregate that silently drops historical edges.