feat: Use label expressions for dynamic labels when available.

This uses the new features of Cypher-DSL to express lists of labels during
- match
- creation
- modification (setting / removing) labels

of entities with dynamic labels. On older Neo4j lists of labels will still be expressed as static lists, on Neo4j 5.26 and later, they will use expressions.

This change has been tested on

- latest 4.4
- latest 5.26
- latest 2025.x

It turned out that in the case of 4.4 there are still edge cases in which elementId is called and tests will fail. Those will be addressed in as separate commit.
Also, several tests for vector properties and indexes have now been disabled on early databases, so that the build succeeds.

Using the correct Cypher DSL dialect is paramount for this feature to work proper, some integration tests had not been configured properly.

This closes #3043.

Signed-off-by: Michael Simons <michael@simons.ac>

Author: michael-simons

ci/test.sh

@@ -22,7 +22,7 @@ mkdir -p /tmp/jenkins-home
 
 export JENKINS_USER=${JENKINS_USER_NAME}
 export SDN_FORCE_REUSE_OF_CONTAINERS=true
-export SDN_NEO4J_VERSION=5.26.2
+export SDN_NEO4J_VERSION=5.26.12
 
 MAVEN_OPTS="-Duser.name=${JENKINS_USER} -Duser.home=/tmp/jenkins-home -Dscan=false" \
   ./mvnw -s settings.xml -P${PROFILE} clean dependency:list verify -Dsort -U -B -Dmaven.repo.local=/tmp/jenkins-home/.m2/spring-data-neo4j -Ddevelocity.storage.directory=/tmp/jenkins-home/.develocity-root

pom.xml

@@ -77,7 +77,7 @@
 		<blockhound.version>1.0.8.RELEASE</blockhound.version>
 		<checkstyle.skip>${skipTests}</checkstyle.skip>
 		<checkstyle.version>10.20.1</checkstyle.version>
-		<cypher-dsl.version>2025.0.0</cypher-dsl.version>
+		<cypher-dsl.version>2025.0.2</cypher-dsl.version>
 		<dist.id>spring-data-neo4j</dist.id>
 		<dist.key>SDNEO4J</dist.key>
 		<flatten-maven-plugin.version>1.7.0</flatten-maven-plugin.version>
@@ -99,7 +99,7 @@
 		<maven.compiler.release>${java.version}</maven.compiler.release>
 		<neo4j-java-driver.version>5.28.9</neo4j-java-driver.version>
 		<neo4j-migrations.version>2.17.3</neo4j-migrations.version>
-		<neo4j.version>4.4.41</neo4j.version>
+		<neo4j.version>5.26.12</neo4j.version>
 		<objenesis.version>3.0.1</objenesis.version>
 		<org.osgi.core.version>6.0.0</org.osgi.core.version>
 		<project.build.docs>${project.build.directory}/docs</project.build.docs>

src/main/java/org/springframework/data/neo4j/core/DynamicLabels.java

@@ -54,14 +54,14 @@ final class DynamicLabels implements UnaryOperator<OngoingMatchAndUpdate> {
 
 	@Override
 	public OngoingMatchAndUpdate apply(OngoingMatchAndUpdate ongoingMatchAndUpdate) {
-
 		OngoingMatchAndUpdate decoratedMatchAndUpdate = ongoingMatchAndUpdate;
 		if (!this.oldLabels.isEmpty()) {
 			decoratedMatchAndUpdate = decoratedMatchAndUpdate.remove(this.rootNode,
-					this.oldLabels.toArray(new String[0]));
+					Cypher.allLabels(Cypher.anonParameter(this.oldLabels)));
 		}
 		if (!this.newLabels.isEmpty()) {
-			decoratedMatchAndUpdate = decoratedMatchAndUpdate.set(this.rootNode, this.newLabels.toArray(new String[0]));
+			decoratedMatchAndUpdate = decoratedMatchAndUpdate.set(this.rootNode,
+					Cypher.allLabels(Cypher.anonParameter(this.newLabels)));
 		}
 		return decoratedMatchAndUpdate;
 	}

src/main/java/org/springframework/data/neo4j/core/Neo4jTemplate.java

@@ -468,11 +468,12 @@ private <T> T saveImpl(T instance, @Nullable Collection<PropertyFilter.Projected
 		TemplateSupport.FilteredBinderFunction<T> binderFunction = TemplateSupport.createAndApplyPropertyFilter(
 				includedProperties, entityMetaData,
 				this.neo4jMappingContext.getRequiredBinderFunctionFor((Class<T>) entityToBeSaved.getClass()));
-		Optional<Entity> newOrUpdatedNode = this.neo4jClient
-			.query(() -> this.renderer.render(this.cypherGenerator.prepareSaveOf(entityMetaData, dynamicLabels,
-					TemplateSupport.rendererRendersElementId(this.renderer))))
+		var statement = this.cypherGenerator.prepareSaveOf(entityMetaData, dynamicLabels,
+				TemplateSupport.rendererRendersElementId(this.renderer));
+		Optional<Entity> newOrUpdatedNode = this.neo4jClient.query(() -> this.renderer.render(statement))
 			.bind(entityToBeSaved)
 			.with(binderFunction)
+			.bindAll(statement.getCatalog().getParameters())
 			.fetchAs(Entity.class)
 			.one();
 
@@ -516,14 +517,16 @@ private <T> DynamicLabels determineDynamicLabels(T entityToBeSaved, Neo4jPersist
 
 			PersistentPropertyAccessor<T> propertyAccessor = entityMetaData.getPropertyAccessor(entityToBeSaved);
 			Neo4jPersistentProperty idProperty = entityMetaData.getRequiredIdProperty();
+			var statementReturningDynamicLabels = this.cypherGenerator
+				.createStatementReturningDynamicLabels(entityMetaData);
 			Neo4jClient.RunnableSpec runnableQuery = this.neo4jClient
-				.query(() -> this.renderer
-					.render(this.cypherGenerator.createStatementReturningDynamicLabels(entityMetaData)))
+				.query(() -> this.renderer.render(statementReturningDynamicLabels))
 				.bind(TemplateSupport.convertIdValues(this.neo4jMappingContext, idProperty,
 						propertyAccessor.getProperty(idProperty)))
 				.to(Constants.NAME_OF_ID)
 				.bind(entityMetaData.getStaticLabels())
-				.to(Constants.NAME_OF_STATIC_LABELS_PARAM);
+				.to(Constants.NAME_OF_STATIC_LABELS_PARAM)
+				.bindAll(statementReturningDynamicLabels.getCatalog().getParameters());
 
 			if (entityMetaData.hasVersionProperty()) {
 				runnableQuery = runnableQuery
@@ -620,10 +623,11 @@ class Tuple3<T> {
 			.map(h -> h.modifiedInstance)
 			.map(binderFunction)
 			.collect(Collectors.toList());
-		Map<Value, String> idToInternalIdMapping = this.neo4jClient
-			.query(() -> this.renderer.render(this.cypherGenerator.prepareSaveOfMultipleInstancesOf(entityMetaData)))
+		var statement = this.cypherGenerator.prepareSaveOfMultipleInstancesOf(entityMetaData);
+		Map<Value, String> idToInternalIdMapping = this.neo4jClient.query(() -> this.renderer.render(statement))
 			.bind(entityList)
 			.to(Constants.NAME_OF_ENTITY_LIST_PARAM)
+			.bindAll(statement.getCatalog().getParameters())
 			.fetchAs(Map.Entry.class)
 			.mappedBy((t, r) -> new AbstractMap.SimpleEntry<>(r.get(Constants.NAME_OF_ID),
 					TemplateSupport.convertIdOrElementIdToString(r.get(Constants.NAME_OF_ELEMENT_ID))))
@@ -726,6 +730,7 @@ public <T> void deleteById(Object id, Class<T> domainType) {
 				.bind(TemplateSupport.convertIdValues(this.neo4jMappingContext, entityMetaData.getRequiredIdProperty(),
 						id))
 				.to(nameOfParameter)
+				.bindAll(statement.getCatalog().getParameters())
 				.run();
 
 			log.debug(() -> String.format("Deleted %d nodes and %d relationships.", summary.counters().nodesDeleted(),
@@ -786,6 +791,7 @@ public <T> void deleteAllById(Iterable<?> ids, Class<T> domainType) {
 				.bind(TemplateSupport.convertIdValues(this.neo4jMappingContext, entityMetaData.getRequiredIdProperty(),
 						ids))
 				.to(nameOfParameter)
+				.bindAll(statement.getCatalog().getParameters())
 				.run();
 
 			log.debug(() -> String.format("Deleted %d nodes and %d relationships.", summary.counters().nodesDeleted(),
@@ -944,6 +950,7 @@ private <T> T processNestedRelations(Neo4jPersistentEntity<?> sourceEntity,
 					.to(Constants.FROM_ID_PARAMETER_NAME) //
 					.bind(knownRelationshipsIds) //
 					.to(Constants.NAME_OF_KNOWN_RELATIONSHIPS_PARAM) //
+					.bindAll(relationshipRemoveQuery.getCatalog().getParameters())
 					.run();
 			}
 
@@ -1132,6 +1139,7 @@ else if (relationshipDescription.hasRelationshipProperties() && fromId != null)
 						plainRelationshipRows);
 				this.neo4jClient.query(this.renderer.render(statementHolder.getStatement()))
 					.bindAll(statementHolder.getProperties())
+					.bindAll(statementHolder.getStatement().getCatalog().getParameters())
 					.run();
 			}
 			else if (relationshipDescription.hasRelationshipProperties()) {
@@ -1145,6 +1153,7 @@ else if (relationshipDescription.hasRelationshipProperties()) {
 
 					this.neo4jClient.query(this.renderer.render(statementHolder.getStatement()))
 						.bindAll(statementHolder.getProperties())
+						.bindAll(statementHolder.getStatement().getCatalog().getParameters())
 						.run();
 				}
 				if (!(newRelationshipPropertiesToStore.isEmpty() || idProperty == null)) {
@@ -1155,6 +1164,7 @@ else if (relationshipDescription.hasRelationshipProperties()) {
 					List<Object> all = new ArrayList<>(
 							this.neo4jClient.query(this.renderer.render(statementHolder.getStatement()))
 								.bindAll(statementHolder.getProperties())
+								.bindAll(statementHolder.getStatement().getCatalog().getParameters())
 								.fetchAs(Object.class)
 								.mappedBy((t, r) -> IdentitySupport.mapperForRelatedIdValues(idProperty).apply(r))
 								.all());
@@ -1187,6 +1197,7 @@ private Optional<Object> getRelationshipId(Statement statement, @Nullable Neo4jP
 			.to(Constants.FROM_ID_PARAMETER_NAME) //
 			.bind(toId) //
 			.to(Constants.TO_ID_PARAMETER_NAME) //
+			.bindAll(statement.getCatalog().getParameters())
 			.fetchAs(Object.class)
 			.mappedBy((t, r) -> IdentitySupport.mapperForRelatedIdValues(idProperty).apply(r))
 			.one();
@@ -1255,11 +1266,12 @@ private Entity saveRelatedNode(Object entity, NodeDescription<?> targetNodeDescr
 			}
 			return tree;
 		});
-		Optional<Entity> optionalSavedNode = this.neo4jClient
-			.query(() -> this.renderer.render(this.cypherGenerator.prepareSaveOf(targetNodeDescription, dynamicLabels,
-					TemplateSupport.rendererRendersElementId(this.renderer))))
+		var statement = this.cypherGenerator.prepareSaveOf(targetNodeDescription, dynamicLabels,
+				TemplateSupport.rendererRendersElementId(this.renderer));
+		Optional<Entity> optionalSavedNode = this.neo4jClient.query(() -> this.renderer.render(statement))
 			.bind(entity)
 			.with(binderFunction)
+			.bindAll(statement.getCatalog().getParameters())
 			.fetchAs(Entity.class)
 			.one();
 
@@ -1605,6 +1617,7 @@ private void iterateNextLevel(Collection<String> nodeIds, RelationshipDescriptio
 				Neo4jTemplate.this.neo4jClient.query(Neo4jTemplate.this.renderer.render(statement))
 					.bindAll(Collections.singletonMap(Constants.NAME_OF_IDS,
 							TemplateSupport.convertToLongIdOrStringElementId(nodeIds)))
+					.bindAll(statement.getCatalog().getParameters())
 					.fetch()
 					.one()
 					.ifPresent(

src/main/java/org/springframework/data/neo4j/core/ReactiveNeo4jTemplate.java

@@ -508,11 +508,11 @@ private <T> Mono<T> saveImpl(T instance, @Nullable Collection<PropertyFilter.Pro
 						this.neo4jMappingContext.getRequiredBinderFunctionFor((Class<T>) entityToBeSaved.getClass()));
 
 				boolean canUseElementId = TemplateSupport.rendererRendersElementId(this.renderer);
-				Mono<Entity> idMono = this.neo4jClient
-					.query(() -> this.renderer
-						.render(this.cypherGenerator.prepareSaveOf(entityMetaData, dynamicLabels, canUseElementId)))
+				var statement = this.cypherGenerator.prepareSaveOf(entityMetaData, dynamicLabels, canUseElementId);
+				Mono<Entity> idMono = this.neo4jClient.query(() -> this.renderer.render(statement))
 					.bind(entityToBeSaved)
 					.with(binderFunction)
+					.bindAll(statement.getCatalog().getParameters())
 					.fetchAs(Entity.class)
 					.one()
 					.switchIfEmpty(Mono.defer(() -> {
@@ -545,14 +545,16 @@ private <T> Mono<Tuple2<T, DynamicLabels>> determineDynamicLabels(T entityToBeSa
 
 			PersistentPropertyAccessor<?> propertyAccessor = entityMetaData.getPropertyAccessor(entityToBeSaved);
 			Neo4jPersistentProperty idProperty = entityMetaData.getRequiredIdProperty();
+			var statementReturningDynamicLabels = this.cypherGenerator
+				.createStatementReturningDynamicLabels(entityMetaData);
 			ReactiveNeo4jClient.RunnableSpec runnableQuery = this.neo4jClient
-				.query(() -> this.renderer
-					.render(this.cypherGenerator.createStatementReturningDynamicLabels(entityMetaData)))
+				.query(() -> this.renderer.render(statementReturningDynamicLabels))
 				.bind(TemplateSupport.convertIdValues(this.neo4jMappingContext, idProperty,
 						propertyAccessor.getProperty(idProperty)))
 				.to(Constants.NAME_OF_ID)
 				.bind(entityMetaData.getStaticLabels())
-				.to(Constants.NAME_OF_STATIC_LABELS_PARAM);
+				.to(Constants.NAME_OF_STATIC_LABELS_PARAM)
+				.bindAll(statementReturningDynamicLabels.getCatalog().getParameters());
 
 			if (entityMetaData.hasVersionProperty()) {
 				runnableQuery = runnableQuery
@@ -683,19 +685,18 @@ private <T> Flux<T> saveAllImpl(Iterable<T> instances,
 					.map(Tuple3::getT3) // extract PotentiallyModified
 					.map(binderFunction)
 					.collect(Collectors.toList());
-				return this.neo4jClient
-					.query(() -> this.renderer
-						.render(this.cypherGenerator.prepareSaveOfMultipleInstancesOf(entityMetaData)))
+				var statement = this.cypherGenerator.prepareSaveOfMultipleInstancesOf(entityMetaData);
+				return this.neo4jClient.query(() -> this.renderer.render(statement))
 					.bind(boundedEntityList)
 					.to(Constants.NAME_OF_ENTITY_LIST_PARAM)
+					.bindAll(statement.getCatalog().getParameters())
 					.fetchAs(Tuple2.class)
 					.mappedBy((t, r) -> Tuples.of(r.get(Constants.NAME_OF_ID),
 							TemplateSupport.convertIdOrElementIdToString(r.get(Constants.NAME_OF_ELEMENT_ID))))
 					.all()
 					.collectMap(m -> (Value) m.getT1(), m -> (String) m.getT2());
 			}).flatMapMany(idToInternalIdMapping -> Flux.fromIterable(entitiesToBeSaved).concatMap(t -> {
 				PersistentPropertyAccessor<T> propertyAccessor = entityMetaData.getPropertyAccessor(t.getT3());
-				Neo4jPersistentProperty idProperty = entityMetaData.getRequiredIdProperty();
 				return processRelations(entityMetaData, propertyAccessor, t.getT2(), ctx.get("stateMachine"),
 						ctx.get("knownRelIds"),
 						TemplateSupport
@@ -722,6 +723,7 @@ public <T> Mono<Void> deleteAllById(Iterable<?> ids, Class<T> domainType) {
 			.bind(TemplateSupport.convertIdValues(this.neo4jMappingContext, entityMetaData.getRequiredIdProperty(),
 					ids))
 			.to(nameOfParameter)
+			.bindAll(statement.getCatalog().getParameters())
 			.run()
 			.then()));
 	}
@@ -739,6 +741,7 @@ public <T> Mono<Void> deleteById(Object id, Class<T> domainType) {
 		return execute(Mono.defer(() -> this.neo4jClient.query(() -> this.renderer.render(statement))
 			.bind(TemplateSupport.convertIdValues(this.neo4jMappingContext, entityMetaData.getRequiredIdProperty(), id))
 			.to(nameOfParameter)
+			.bindAll(statement.getCatalog().getParameters())
 			.run()
 			.then()));
 	}
@@ -1089,6 +1092,7 @@ private <T> Mono<T> processNestedRelations(Neo4jPersistentEntity<?> sourceEntity
 					.to(Constants.FROM_ID_PARAMETER_NAME) //
 					.bind(knownRelationshipsIds) //
 					.to(Constants.NAME_OF_KNOWN_RELATIONSHIPS_PARAM) //
+					.bindAll(relationshipRemoveQuery.getCatalog().getParameters())
 					.run()
 					.checkpoint("delete relationships")
 					.then());
@@ -1227,6 +1231,7 @@ private <T> Mono<T> processNestedRelations(Neo4jPersistentEntity<?> sourceEntity
 									.bind(idValue) //
 									.to(Constants.NAME_OF_KNOWN_RELATIONSHIP_PARAM) //
 									.bindAll(statementHolder.getProperties())
+									.bindAll(statementHolder.getStatement().getCatalog().getParameters())
 									.fetchAs(Object.class)
 									.mappedBy((t, r) -> IdentitySupport.mapperForRelatedIdValues(idProperty).apply(r))
 									.one()
@@ -1298,6 +1303,7 @@ private Mono<Object> getRelationshipId(Statement statement, @Nullable Neo4jPersi
 			.to(Constants.FROM_ID_PARAMETER_NAME) //
 			.bind(toId) //
 			.to(Constants.TO_ID_PARAMETER_NAME) //
+			.bindAll(statement.getCatalog().getParameters())
 			.fetchAs(Object.class)
 			.mappedBy((t, r) -> IdentitySupport.mapperForRelatedIdValues(idProperty).apply(r))
 			.one();
@@ -1358,11 +1364,12 @@ private Mono<Entity> saveRelatedNode(Object relatedNode, Neo4jPersistentEntity<?
 				}
 				return tree;
 			});
-			return this.neo4jClient
-				.query(() -> this.renderer.render(this.cypherGenerator.prepareSaveOf(targetNodeDescription,
-						dynamicLabels, TemplateSupport.rendererRendersElementId(this.renderer))))
+			var statement = this.cypherGenerator.prepareSaveOf(targetNodeDescription, dynamicLabels,
+					TemplateSupport.rendererRendersElementId(this.renderer));
+			return this.neo4jClient.query(() -> this.renderer.render(statement))
 				.bind(entity)
 				.with(binderFunction)
+				.bindAll(statement.getCatalog().getParameters())
 				.fetchAs(Entity.class)
 				.one();
 		}).switchIfEmpty(Mono.defer(() -> {

src/main/java/org/springframework/data/neo4j/core/mapping/CypherGenerator.java

@@ -65,7 +65,6 @@
 import static org.neo4j.cypherdsl.core.Cypher.listBasedOn;
 import static org.neo4j.cypherdsl.core.Cypher.literalOf;
 import static org.neo4j.cypherdsl.core.Cypher.match;
-import static org.neo4j.cypherdsl.core.Cypher.node;
 import static org.neo4j.cypherdsl.core.Cypher.optionalMatch;
 import static org.neo4j.cypherdsl.core.Cypher.parameter;
 
@@ -166,6 +165,14 @@ private static Function<Relationship, Expression> getRelationshipIdFunction(
 		return result;
 	}
 
+	private static Node node(String primaryLabel, List<String> additionalLabels) {
+		var labels = Cypher.exactlyLabel(primaryLabel);
+		if (!additionalLabels.isEmpty()) {
+			labels = labels.conjunctionWith(Cypher.allLabels(Cypher.anonParameter(additionalLabels)));
+		}
+		return Cypher.node(labels);
+	}
+
 	private static Condition conditionOrNoCondition(@Nullable Condition condition) {
 		return (condition != null) ? condition : Cypher.noCondition();
 	}

src/test/java/org/springframework/data/neo4j/core/mapping/CypherGeneratorTests.java

@@ -21,13 +21,15 @@
 import java.util.regex.Pattern;
 import java.util.stream.Stream;
 
+import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.CsvSource;
 import org.junit.jupiter.params.provider.MethodSource;
 import org.mockito.Mockito;
 import org.neo4j.cypherdsl.core.Cypher;
+import org.neo4j.cypherdsl.core.FunctionInvocation;
 import org.neo4j.cypherdsl.core.Statement;
 import org.neo4j.cypherdsl.core.renderer.Configuration;
 import org.neo4j.cypherdsl.core.renderer.Dialect;
@@ -57,6 +59,12 @@ private static Stream<Arguments> pageables() {
 				Arguments.of(Sort.by("n.a").ascending(), Optional.of("ORDER BY n.a ASC")));
 	}
 
+	@BeforeAll
+	static void fixTheAbusOfASingleton() {
+		CypherGenerator.INSTANCE
+			.setElementIdOrIdFunction(n -> FunctionInvocation.create(() -> "elementId", n.getRequiredSymbolicName()));
+	}
+
 	@Test
 	void shouldCreateRelationshipCreationQueryWithLabelIfPresent() {
 		Neo4jPersistentEntity<?> persistentEntity = new Neo4jMappingContext().getPersistentEntity(Entity1.class);

src/test/java/org/springframework/data/neo4j/integration/cascading/AbstractCascadingTestBase.java

@@ -20,13 +20,16 @@
 import java.util.Map;
 
 import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Tag;
 import org.neo4j.driver.Driver;
 import org.neo4j.driver.types.TypeSystem;
 
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.data.neo4j.test.Neo4jExtension;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+@Tag(Neo4jExtension.NEEDS_VERSION_SUPPORTING_ELEMENT_ID)
 abstract class AbstractCascadingTestBase {
 
 	static Map<Class<? extends Parent>, String> EXISTING_IDS = new HashMap<>();

src/test/java/org/springframework/data/neo4j/integration/conversion_imperative/TypeConversionIT.java

@@ -36,6 +36,7 @@
 import org.junit.jupiter.api.DynamicContainer;
 import org.junit.jupiter.api.DynamicNode;
 import org.junit.jupiter.api.DynamicTest;
+import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestFactory;
 import org.neo4j.driver.Driver;
@@ -68,6 +69,7 @@
 import org.springframework.data.neo4j.repository.Neo4jRepository;
 import org.springframework.data.neo4j.repository.config.EnableNeo4jRepositories;
 import org.springframework.data.neo4j.test.BookmarkCapture;
+import org.springframework.data.neo4j.test.Neo4jExtension;
 import org.springframework.data.neo4j.test.Neo4jImperativeTestConfiguration;
 import org.springframework.data.neo4j.test.Neo4jIntegrationTest;
 import org.springframework.test.util.ReflectionTestUtils;
@@ -78,10 +80,13 @@
 import static org.assertj.core.api.Assertions.assertThatExceptionOfType;
 
 /**
+ * Tag due to the requirements on db.create.setNodeVectorProperty
+ *
  * @author Michael J. Simons
  * @author Dennis Crissman
  */
 @Neo4jIntegrationTest
+@Tag(Neo4jExtension.NEEDS_VECTOR_INDEX)
 class TypeConversionIT extends Neo4jConversionsITBase {
 
 	private final CypherTypesRepository cypherTypesRepository;