New operators for Dynamic values #1360

JPryce-Aklundh · 2025-08-14T09:44:28Z

Applies to both Cypher 5 and Cypher 25

arnefischereit

Some syntactical changes. But I guess the most relevant feedback is on the workaround for MERGE which was there even before this change.

arnefischereit · 2025-08-14T10:21:46Z

modules/ROOT/pages/clauses/match.adoc

+| Neo4j versions | Performance caveat
+
+| 5.26 -- 2025.07
+| xref:planning-and-tuning/execution-plans.adoc[Cypher planner] not able to leverage xref:indexes/search-performance-indexes/index.adoc[indexes] with xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead utilize the xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[`AllNodesScan`] operator, which reads all nodes from the node store and is therefore more costly. 


Suggested change

| xref:planning-and-tuning/execution-plans.adoc[Cypher planner] not able to leverage xref:indexes/search-performance-indexes/index.adoc[indexes] with xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead utilize the xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[`AllNodesScan`] operator, which reads all nodes from the node store and is therefore more costly.

| xref:planning-and-tuning/execution-plans.adoc[Cypher planner] is not able to leverage xref:indexes/search-performance-indexes/index.adoc[indexes] with xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead utilize the xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[`AllNodesScan`] operator, which reads all nodes from the node store and is therefore more costly.

arnefischereit · 2025-08-14T10:22:24Z

modules/ROOT/pages/clauses/match.adoc

+| xref:planning-and-tuning/execution-plans.adoc[Cypher planner] not able to leverage xref:indexes/search-performance-indexes/index.adoc[indexes] with xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead utilize the xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[`AllNodesScan`] operator, which reads all nodes from the node store and is therefore more costly. 
+
+| 2025.08 -- current
+| Cypher planner is able to leverage leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.


Suggested change

| Cypher planner is able to leverage leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.

| Cypher planner is able to leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.

arnefischereit · 2025-08-14T10:23:05Z

modules/ROOT/pages/clauses/match.adoc

+| Cypher planner is able to leverage leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.
+This is enabled by the introduction of three new query plan operators: 
+xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-node-label-lookup[`DynamicNodeLabelLookup`], xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-directed-relationship-type-lookup[`DynamicDirectedRelationshipTypeLookup`], and xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-undirected-relationship-type-lookup[`DynamicUndirectedRelationshipTypeLookup`].
+It is not, however, able to indexes on property values.


Suggested change

It is not, however, able to indexes on property values.

It is not, however, able to use indexes on property values.

arnefischereit · 2025-08-14T10:24:04Z

modules/ROOT/pages/clauses/match.adoc

+This is enabled by the introduction of three new query plan operators: 
+xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-node-label-lookup[`DynamicNodeLabelLookup`], xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-directed-relationship-type-lookup[`DynamicDirectedRelationshipTypeLookup`], and xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-undirected-relationship-type-lookup[`DynamicUndirectedRelationshipTypeLookup`].
+It is not, however, able to indexes on property values.
+For example, `MATCH (n:$(Label) {foo: bar})` will not use any indexes on `n.foo`.


Suggested change

For example, `MATCH (n:$(Label) {foo: bar})` will not use any indexes on `n.foo`.

For example, `MATCH (n:$(label) {foo: bar})` will not use any indexes on `n.foo` but might use a `DynamicNodeLabelLookup` on `$(label)`.

arnefischereit · 2025-08-14T11:11:16Z

modules/ROOT/pages/clauses/merge.adoc

+|===

-To circumvent possible performance issues, place the dynamic labels or relationship types within `ON CREATE` or `ON MATCH` subclauses.
+If you are using Neo4j 5.26 -- 2025.07, you can circumvent the inability of the Cypher planner to leverage token lookup indexes by placing the dynamic labels or relationship types within `ON CREATE` or `ON MATCH` subclauses.


I know this "workaround" has been there before but I do not see that particular example helping:

If you have a static label Label, then

MERGE (n:Person:$($dynamicLabels) {name: "Greta Gerwig"})

should plan a label scan on :Person and then add a filter on :$($dynamicLabels) without ON .... But if you want to add other labels depending on MATCH or MERGE behaviour, you will need to use the ON ... anyway.

arnefischereit · 2025-08-14T11:16:30Z

modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc

+RETURN people.name
+----
+
+| xref:clauses/match.adoc#dynamic-match[Dynamic labels and relationship types] can now leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes].


I find it a bit odd from the wording to read that the labels/types are leveraging the indexes. I my mind, the execution engine (or the planner) is leveraging indexes to answer queries with dynamic labels/types. But maybe this is splitting hairs.

No, I think what I wrote is too ambiguous. Will update.

arnefischereit · 2025-08-14T11:17:26Z

modules/ROOT/pages/clauses/merge.adoc

+| Neo4j versions | Performance caveat
+
+| 5.26 -- 2025.07
+| xref:planning-and-tuning/execution-plans.adoc[Cypher planner] not able to leverage xref:indexes/search-performance-indexes/index.adoc[indexes] with xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead utilize the xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[`AllNodesScan`] operator, which reads all nodes from the node store and is therefore more costly. 


Suggested change

| xref:planning-and-tuning/execution-plans.adoc[Cypher planner] not able to leverage xref:indexes/search-performance-indexes/index.adoc[indexes] with xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead utilize the xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[`AllNodesScan`] operator, which reads all nodes from the node store and is therefore more costly.

| xref:planning-and-tuning/execution-plans.adoc[Cypher planner] is not able to leverage xref:indexes/search-performance-indexes/index.adoc[indexes] with xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead utilize the xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[`AllNodesScan`] operator, which reads all nodes from the node store and is therefore more costly.

arnefischereit · 2025-08-14T11:17:33Z

modules/ROOT/pages/clauses/merge.adoc

+| xref:planning-and-tuning/execution-plans.adoc[Cypher planner] not able to leverage xref:indexes/search-performance-indexes/index.adoc[indexes] with xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead utilize the xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-all-nodes-scan[`AllNodesScan`] operator, which reads all nodes from the node store and is therefore more costly. 
+
+| 2025.08 -- current
+| Cypher planner is able to leverage leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.


Suggested change

| Cypher planner is able to leverage leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.

| Cypher planner is able to leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.

arnefischereit · 2025-08-14T11:17:51Z

modules/ROOT/pages/clauses/merge.adoc

+| Cypher planner is able to leverage leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.
+This is enabled by the introduction of three new query plan operators: 
+xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-node-label-lookup[`DynamicNodeLabelLookup`], xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-directed-relationship-type-lookup[`DynamicDirectedRelationshipTypeLookup`], and xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-undirected-relationship-type-lookup[`DynamicUndirectedRelationshipTypeLookup`].
+It is not, however, able to indexes on property values.


Suggested change

It is not, however, able to indexes on property values.

It is not, however, able to use indexes on property values.

arnefischereit · 2025-08-14T11:18:44Z

modules/ROOT/pages/clauses/merge.adoc

+This is enabled by the introduction of three new query plan operators: 
+xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-node-label-lookup[`DynamicNodeLabelLookup`], xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-directed-relationship-type-lookup[`DynamicDirectedRelationshipTypeLookup`], and xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-undirected-relationship-type-lookup[`DynamicUndirectedRelationshipTypeLookup`].
+It is not, however, able to indexes on property values.
+For example, `MERGE (n:$(Label) {foo: bar})` will not use any indexes on `n.foo`.


Suggested change

For example, `MERGE (n:$(Label) {foo: bar})` will not use any indexes on `n.foo`.

For example, `MERGE (n:$(label) {foo: bar})` will not use any indexes on `n.foo` but might use a `DynamicNodeLabelLookup` on `$(label)`.

neo4j-docops-agent · 2025-08-14T13:14:22Z

Thanks for the documentation updates.

The preview documentation has now been torn down - reopening this PR will republish it.

jamthief · 2025-08-18T10:04:39Z

modules/ROOT/pages/clauses/match.adoc

+| 2025.08 -- current
+| The Cypher planner is able to leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.
+This is enabled by the introduction of three new query plan operators: 
+xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-node-label-lookup[`DynamicNodeLabelLookup`], xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-directed-relationship-type-lookup[`DynamicDirectedRelationshipTypeLookup`], and xref:planning-and-tuning/operators/operators-detail.adoc#query-plan-dynamic-undirected-relationship-type-lookup[`DynamicUndirectedRelationshipTypeLookup`].


I'm afraid this is incorrect - the operator is called DynamicLabelNodeLookup!

Applies to both Cypher 5 and Cypher 25

JPryce-Aklundh added 3 commits August 14, 2025 08:57

initial

f84991c

query plan

d8c377e

mistake fix

5aae3d4

JPryce-Aklundh added the 2025.08 label Aug 14, 2025

correct header levels

ca3b3fe

arnefischereit approved these changes Aug 14, 2025

View reviewed changes

JPryce-Aklundh added 2 commits August 14, 2025 14:42

editorial and remove workaround example

14068d2

can not might

e1c1980

arnefischereit approved these changes Aug 14, 2025

View reviewed changes

JPryce-Aklundh added 2 commits August 14, 2025 15:09

Merge branch 'dev' into dynamic_operators

9e6fab9

fix table

6d17ba4

JPryce-Aklundh merged commit 5efacb1 into neo4j:dev Aug 14, 2025
5 checks passed

JPryce-Aklundh deleted the dynamic_operators branch August 14, 2025 13:19

jamthief reviewed Aug 18, 2025

View reviewed changes

JPryce-Aklundh added a commit to JPryce-Aklundh/docs-cypher that referenced this pull request Sep 2, 2025

New operators for Dynamic values (neo4j#1360)

07ff037

Applies to both Cypher 5 and Cypher 25

	\| Cypher planner is able to leverage leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.
	\| Cypher planner is able to leverage xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when matching node labels and relationship types dynamically.

	It is not, however, able to indexes on property values.
	It is not, however, able to use indexes on property values.

	For example, `MATCH (n:$(Label) {foo: bar})` will not use any indexes on `n.foo`.
	For example, `MATCH (n:$(label) {foo: bar})` will not use any indexes on `n.foo` but might use a `DynamicNodeLabelLookup` on `$(label)`.

	For example, `MERGE (n:$(Label) {foo: bar})` will not use any indexes on `n.foo`.
	For example, `MERGE (n:$(label) {foo: bar})` will not use any indexes on `n.foo` but might use a `DynamicNodeLabelLookup` on `$(label)`.

New operators for Dynamic values #1360

New operators for Dynamic values #1360

Uh oh!

Conversation

JPryce-Aklundh commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

arnefischereit left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

neo4j-docops-agent commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

JPryce-Aklundh commented Aug 14, 2025 •

edited

Loading

neo4j-docops-agent commented Aug 14, 2025 •

edited

Loading