This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Data Neo4j 7.3.2! |
Spring Data Neo4j Projections
As stated above, projections come in two flavors: Interface and DTO based projections. In Spring Data Neo4j both types of projections have a direct influence which properties and relationships are transferred over the wire. Therefore, both approaches can reduce the load on your database in case you are dealing with nodes and entities containing lots of properties which might not be needed in all usage scenarios in your application.
For both interface and DTO based projections, Spring Data Neo4j will use the repository’s domain type for building the
query. All annotations on all attributes that might change the query will be taken in consideration.
The domain type is the type that has been defined through the repository declaration
(Given a declaration like interface TestRepository extends CrudRepository<TestEntity, Long>
the domain type would be
TestEntity
).
Interface based projections will always be dynamic proxies to the underlying domain type. The names of the accessors defined
on such interfaces (like getName
) must resolve to properties (here: name
) that are present on the projected entity.
Whether those properties have accessors or not on the domain type is not relevant, as long as they can be accessed through
the common Spring Data infrastructure. The latter is already ensured, as the domain type wouldn’t be a persistent entity in
the first place.
DTO based projections are somewhat more flexible when used with custom queries. While the standard query is derived from the original domain type and therefore only the properties and relationship being defined there can be used, custom queries can add additional properties.
The rules are as follows: first, the properties of the domain type are used to populate the DTO. In case the DTO declares
additional properties - via accessors or fields - Spring Data Neo4j looks in the resulting record for matching properties.
Properties must match exactly by name and can be of simple types (as defined in org.springframework.data.neo4j.core.convert.Neo4jSimpleTypes
)
or of known persistent entities. Collections of those are supported, but maps are not.
Multi-level projections
Spring Data Neo4j also supports multi-level projections.
interface ProjectionWithNestedProjection {
String getName();
List<Subprojection1> getLevel1();
interface Subprojection1 {
String getName();
List<Subprojection2> getLevel2();
}
interface Subprojection2 {
String getName();
}
}
Even though it is possible to model cyclic projections or point towards entities that will create a cycle, the projection logic will not follow those cycles but only create cycle-free queries.
Multi-level projections are bounded to the entities they should project.
RelationshipProperties
fall into the category of entities in this case and needs to get respected if projections get applied.
Data manipulation of projections
If you have fetched the projection as a DTO, you can modify its values. But in case you are using the interface-based projection, you cannot just update the interface. A typical pattern that can be used is to provide a method in your domain entity class that consumes the interface and creates a domain entity with the copied values from the interface. This way, you can then update the entity and persist it again with the projection blueprint/mask as described in the next section.
Persistence of projections
Analogue to the retrieval of data via projections, they can also be used as a blueprint for persistence.
The Neo4jTemplate
offers a fluent API to apply those projections to a save operation.
You could either save a projection for a given domain class
Projection projection = neo4jTemplate.save(DomainClass.class).one(projectionValue);
or you could save a domain object but only respect the fields defined in the projection.
Projection projection = neo4jTemplate.saveAs(domainObject, Projection.class);
In both cases, that also are available for collection based operations, only the fields and relationships defined in the projection will get updated.
To prevent deletion of data (e.g. removal of relationships), you should always load at least all the data that should get persisted later. |
A full example
Given the following entities, projections and the corresponding repository:
@Node
class TestEntity {
@Id @GeneratedValue private Long id;
private String name;
@Property("a_property") (1)
private String aProperty;
}
1 | This property has a different name in the Graph |
TestEntity
@Node
class ExtendedTestEntity extends TestEntity {
private String otherAttribute;
}
TestEntity
interface TestEntityInterfaceProjection {
String getName();
}
TestEntity
, including one additional attributeclass TestEntityDTOProjection {
private String name;
private Long numberOfRelations; (1)
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Long getNumberOfRelations() {
return numberOfRelations;
}
public void setNumberOfRelations(Long numberOfRelations) {
this.numberOfRelations = numberOfRelations;
}
}
1 | This attribute doesn’t exist on the projected entity |
A repository for TestEntity
is shown below and it will behave as explained with the listing.
TestEntity
interface TestRepository extends CrudRepository<TestEntity, Long> { (1)
List<TestEntity> findAll(); (2)
List<ExtendedTestEntity> findAllExtendedEntities(); (3)
List<TestEntityInterfaceProjection> findAllInterfaceProjectionsBy(); (4)
List<TestEntityDTOProjection> findAllDTOProjectionsBy(); (5)
@Query("MATCH (t:TestEntity) - [r:RELATED_TO] -> () RETURN t, COUNT(r) AS numberOfRelations") (6)
List<TestEntityDTOProjection> findAllDTOProjectionsWithCustomQuery();
}
1 | The domain type of the repository is TestEntity |
2 | Methods returning one or more TestEntity will just return instances of it, as it matches the domain type |
3 | Methods returning one or more instances of classes that extend the domain type will just return instances of the extending class. The domain type of the method in question will be the extended class, which still satisfies the domain type of the repository itself |
4 | This method returns an interface projection, the return type of the method is therefore different
from the repository’s domain type. The interface can only access properties defined in the domain type.
The suffix By is needed to make SDN not look for a property called InterfaceProjections in the TestEntity |
5 | This method returns a DTO projection. Executing it will cause SDN to issue a warning, as the DTO defines
numberOfRelations as additional attribute, which is not in the contract of the domain type.
The annotated attribute aProperty in TestEntity will be correctly translated to a_property in the query.
As above, the return type is different from the repositories' domain type.
The suffix By is needed to make SDN not look for a property called DTOProjections in the TestEntity |
6 | This method also returns a DTO projection. However, no warning will be issued, as the query contains a fitting value for the additional attributes defined in the projection |
While the repository in the listing above uses a concrete return type to
define the projection, another variant is the use of dynamic projections as explained in the
parts of the documentation Spring Data Neo4j shares with other Spring Data Projects. A dynamic projection can be
applied to both closed and open interface projections as well as to class based DTO projections:
The key to a dynamic projection is to specify the desired projection type as the last parameter to a query method in a repository like this: <T> Collection<T> findByName(String name, Class<T> type) . This is a declaration that
could be added to the TestRepository above and allow for different projections retrieved by the same method, without
to repeat a possible @Query annotation on several methods.
|