Spring Data Neo4j relationships: save only the graph you own

A loaded subgraph is not the whole graph

A shipment node links to checkpoints and drivers. A detail view loads only checkpoints, edits one property, then saves the root. Depending on its mapping and save path, missing relationships can be interpreted as removed. Use a write model that loads the relationship set it owns, or issue a focused Cypher update for a scalar change. Document saves have a similar stale-copy hazard, though the graph mapping rules differ.

Separate relationship direction from authority

A relationship's direction describes storage and traversal; it does not authorize a caller. Scope every lookup to tenantId and the authenticated principal. Put a database constraint on the tenant-scoped business key so two concurrent creates cannot produce duplicate shipment nodes.

Make deletion visible in tests

Persist a shipment with two drivers, load a projection containing one, save it, then assert both database relationships still exist if the command promised a property-only edit. Use a real Neo4j instance; mocks cannot show graph reconciliation.

Implementation sketch

MATCH (shipment:Shipment {tenantId: $tenantId, shipmentId: $shipmentId})
SET shipment.status = $newStatus
RETURN shipment.shipmentId AS shipmentId, shipment.status AS status

Cost and verification

A narrow update avoids loading and mapping an unrelated relationship graph. Add an index or constraint for the tenant and business ID predicate, then inspect its query plan.

Common Mistakes

• Do not save a partial graph as though it represented every relationship.
• Do not treat relationship direction as an authorization check.
• Do not use an internal node ID as the only public business identifier.

Read next

Spring Data Neo4j transaction: keep the command inside one managed unit, Spring Data Neo4j version conflicts: reject a stale graph update, Spring JWT tenant claims: reject missing or malformed ownership before conversion.

Related boundary

Spring Data Neo4j custom query: return one coherent root record

Check your understanding

Spring Neo4j graph mapping and query contracts quiz