New operators for Dynamic values

modules/ROOT/pages/clauses/match.adoc

@@ -639,10 +639,26 @@ RETURN relationshipType, count(r) AS relationshipCount
 [[dynamic-match-caveats]]
 === Performance caveats
 
-`MATCH` queries using dynamic values may not be as performant as those using static values.
-This is because the xref:planning-and-tuning/execution-plans.adoc[Cypher planner] uses statically available information when planning queries to determine whether to use an xref:indexes/search-performance-indexes/index.adoc[index] or not, and this is not possible when using dynamic values.
+`MATCH` queries that use dynamic values may not perform as well as those with static values.
+Neo4j is actively working to improve the performance of these queries.
+The table below outlines performance caveats for specific Neo4j versions.
 
-As a result, `MATCH` queries using dynamic values cannot leverage xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead use 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.
+.Neo4j versions and performance caveats
+[%header,cols="a,5a"]
+|===
+| 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. 
+
+| 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.
+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`.
+
+|===
 
 [[further-reading]]
 === Further reading

modules/ROOT/pages/clauses/merge.adoc

@@ -740,12 +740,28 @@ RETURN greta.name AS name, labels(greta) AS labels, type(rel) AS relType, collec
 [[dynamic-merge-caveats]]
 === Performance caveats
 
-`MERGE` queries that use dynamic values may not be as performant as those using static values.
-This is because the xref:planning-and-tuning/execution-plans.adoc[Cypher planner] uses statically available information when planning queries to determine whether to use an xref:indexes/search-performance-indexes/index.adoc[index] or not, and this is not possible when using dynamic values.
+`MERGE` queries that use dynamic values may not perform as well as those with static values.
+Neo4j is actively working to improve the performance of these queries.
+The table below outlines performance caveats for specific Neo4j versions.
 
-As a result, `MERGE` queries with dynamic values cannot leverage xref:planning-and-tuning/operators/operators-detail.adoc#leaf-operators[index scans or seeks] and must instead use 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.
+.Neo4j versions and performance caveats
+[%header,cols="a,5a"]
+|===
+| 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. 
+
+| 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.
+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`.
+
+|===
 
-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.
 
 .Parameters
 [source, parameters]

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

@@ -22,6 +22,33 @@ Cypher 25 was introduced in Neo4j 2025.06 and can only be used on Neo4j 2025.06+
 Features removed in Cypher 25 are still available on Neo4j 2025.06+ databases either by prepending a query with `CYPHER 5` or by having Cypher 5 as the default language for the database.
 For more information, see xref:queries/select-version.adoc[].
 
+[[cypher-deprecations-additions-removals-2025.08]]
+== Neo4j 2025.08
+
+=== Updated in Cypher 25
+
+[cols="2", options="header"]
+|===
+| Feature
+| Details
+
+a|
+label:functionality[]
+label:updated[]
+[source, cypher]
+----
+PROFILE 
+WITH "Person" AS label
+MATCH (people:$(label))
+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].
+This is enables 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`].
+
+|===
+
+
 [[cypher-deprecations-additions-removals-2025.07]]
 == Neo4j 2025.07
 

modules/ROOT/pages/planning-and-tuning/operators/operators-detail.adoc

@@ -2576,6 +2576,142 @@ Total database accesses: 106
 
 ======
 
+[role=label--new-2025.08]
+[[query-plan-dynamic-node-label-lookup]]
+=== Dynamic Node Label Lookup
+
+Allows Cypher to use xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when planning queries using xref:clauses/match.adoc#dynamic-match[dynamic node labels].
+
+.DynamicNodeLabelLookup
+======
+
+.Query
+[source, cypher]
+----
+PROFILE 
+WITH "Person" AS label
+MATCH (people:$(label))
+RETURN people.name
+----
+
+.Query Plan
+[role="queryplan", subs="attributes+"]
+----
+Planner COST
+
+Runtime PIPELINED
+
+Runtime version {neo4j-version}
+
+Batch size 128
+
+
++---------------------------+----+------------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| Operator                  | Id | Details                      | Estimated Rows | Rows | DB Hits | Memory (Bytes) | Page Cache Hits/Misses | Time (ms) | Pipeline            |
++---------------------------+----+------------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| +ProduceResults           |  0 | `people.name`                |             26 |   14 |       0 |              0 |                        |           |                     |
+| |                         +----+------------------------------+----------------+------+---------+----------------+                        |           |                     |
+| +Projection               |  1 | people.name AS `people.name` |             26 |   14 |      28 |                |                        |           |                     |
+| |                         +----+------------------------------+----------------+------+---------+----------------+                        |           |                     |
+| +Apply                    |  2 |                              |             26 |   14 |       0 |                |                        |           |                     |
+| |\                        +----+------------------------------+----------------+------+---------+----------------+                        |           |                     |
+| | +DynamicLabelNodeLookup |  3 | people:$all(label)           |             26 |   14 |      15 |           1832 |                    2/0 |     0.366 | Fused in Pipeline 1 |
+| |                         +----+------------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| +Projection               |  4 | $autostring_0 AS label       |              1 |    1 |       0 |                |                        |           | Fused in Pipeline 0 |
++---------------------------+----+------------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+----
+======
+
+[role=label--new-2025.08]
+[[query-plan-dynamic-directed-relationship-type-lookup]]
+=== Dynamic Directed Relationship Type Lookup
+
+Allows Cypher to use xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when planning queries using xref:clauses/match.adoc#dynamic-match[dynamic relationship types] in directed relationship patterns.
+
+.DynamicDirectedRelationshipTypeLookup
+======
+
+.Query
+[source, cypher]
+----
+PROFILE 
+WITH "FRIENDS_WITH" AS relType
+MATCH ()-[r:$(relType)]->()
+RETURN count(r) as relCount
+----
+
+.Query Plan
+[role="queryplan", subs="attributes+"]
+----
+Planner COST
+
+Runtime PIPELINED
+
+Runtime version {neo4j-version}
+
+Batch size 128
+
++------------------------------------------+----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| Operator                                 | Id | Details                  | Estimated Rows | Rows | DB Hits | Memory (Bytes) | Page Cache Hits/Misses | Time (ms) | Pipeline            |
++------------------------------------------+----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| +ProduceResults                          |  0 | relCount                 |              1 |    1 |       0 |              0 |                    0/0 |     0.022 | In Pipeline 2       |
+| |                                        +----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| +EagerAggregation                        |  1 | count(r) AS relCount     |              1 |    1 |       0 |             40 |                        |           |                     |
+| |                                        +----+--------------------------+----------------+------+---------+----------------+                        |           |                     |
+| +Apply                                   |  2 |                          |             21 |   12 |       0 |                |                        |           |                     |
+| |\                                       +----+--------------------------+----------------+------+---------+----------------+                        |           |                     |
+| | +DynamicDirectedRelationshipTypeLookup |  3 | ()-[r:$all(relType)]->() |             21 |   12 |      13 |           1968 |                    2/0 |     0.359 | Fused in Pipeline 1 |
+| |                                        +----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| +Projection                              |  4 | $autostring_0 AS relType |              1 |    1 |       0 |                |                        |           | Fused in Pipeline 0 |
++------------------------------------------+----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+----
+======
+
+
+[role=label--new-2025.08]
+[[query-plan-dynamic-undirected-relationship-type-lookup]]
+=== Dynamic Undirected Relationship Type Lookup
+
+Allows Cypher to use xref:indexes/search-performance-indexes/using-indexes.adoc#token-lookup-indexes[token lookup indexes] when planning queries using dynamic relationship types in undirected relationship patterns.
+
+.DynamicUndirectedRelationshipTypeLookup
+======
+
+.Query
+[source, cypher]
+----
+PROFILE 
+WITH "FRIENDS_WITH" AS relType
+MATCH ()-[r:$(relType)]-()
+RETURN count(r) as relCount
+----
+
+.Query Plan
+[role="queryplan", subs="attributes+"]
+----
+Planner COST
+
+Runtime PIPELINED
+
+Runtime version {neo4j-version}
+
+Batch size 128
+
++--------------------------------------------+----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| Operator                                   | Id | Details                  | Estimated Rows | Rows | DB Hits | Memory (Bytes) | Page Cache Hits/Misses | Time (ms) | Pipeline            |
++--------------------------------------------+----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| +ProduceResults                            |  0 | relCount                 |              1 |    1 |       0 |              0 |                    0/0 |     0.011 | In Pipeline 2       |
+| |                                          +----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| +EagerAggregation                          |  1 | count(r) AS relCount     |              1 |    1 |       0 |             40 |                        |           |                     |
+| |                                          +----+--------------------------+----------------+------+---------+----------------+                        |           |                     |
+| +Apply                                     |  2 |                          |             42 |   24 |       0 |                |                        |           |                     |
+| |\                                         +----+--------------------------+----------------+------+---------+----------------+                        |           |                     |
+| | +DynamicUndirectedRelationshipTypeLookup |  3 | ()-[r:$all(relType)]-()  |             42 |   24 |      13 |           1968 |                    2/0 |     0.121 | Fused in Pipeline 1 |
+| |                                          +----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+| +Projection                                |  4 | $autostring_0 AS relType |              1 |    1 |       0 |                |                        |           | Fused in Pipeline 0 |
++--------------------------------------------+----+--------------------------+----------------+------+---------+----------------+------------------------+-----------+---------------------+
+----
+======
 
 [[nested-loops-join-operators]]
 == Nested loops and join operators