Merge branch 'dev' into tags-for-READ-query-section

Author: rsill-neo4j

antora.yml

@@ -1,11 +1,11 @@
 name: cypher-manual
 title: Cypher Manual
-version: '5'
+version: '2025'
 start_page: ROOT:introduction/index.adoc
 nav:
 - modules/ROOT/content-nav.adoc
 asciidoc:
   attributes:
-    neo4j-version: '5'
-    neo4j-version-minor: '5.26'
-    neo4j-version-exact: '5.26.0'
+    neo4j-version: '2025'
+    neo4j-version-minor: '2025.01'
+    neo4j-version-exact: '2025.01'

modules/ROOT/content-nav.adoc

@@ -116,7 +116,7 @@
 ** xref:syntax/parsing.adoc[]
 ** xref:syntax/naming.adoc[]
 ** xref:syntax/variables.adoc[]
-** xref:syntax/reserved.adoc[]
+** xref:syntax/keywords.adoc[]
 ** xref:syntax/parameters.adoc[]
 ** xref:syntax/operators.adoc[]
 ** xref:syntax/comments.adoc[]

modules/ROOT/images/graph_match_clause.svg

@@ -1,4 +1,5 @@
 :description: Information about Cypher features not included in GQL.
+:test-skip: true
 = Additional Cypher features
 
 While the link:https://www.iso.org/standard/76120.html[GQL Standard] incorporates a lot of capabilities in Cypher, Cypher contains additional features that are not part of GQL and no GQL alternatives currently exist for them.
@@ -78,6 +79,93 @@ Either the pattern already exists, or it needs to be created.
 | Syntactic construct for creating a `LIST` based on matchings of a pattern.
 |===
 
+[[dynamic-queries]]
+== Dynamic queries
+
+Node labels, relationship types, properties, and CSV columns can be referenced dynamically using Cypher.
+This allows for more flexible queries and mitigates the risk of Cypher injection.
+(For more information about Cypher injection, see link:https://neo4j.com/developer/kb/protecting-against-cypher-injection/[Neo4j Knowledge Base -> Protecting against Cypher injection]).
+
+[options="header", cols="2a,5a"]
+|===
+| Cypher feature
+| Description
+
+a| 
+[source, cypher, role="noheader"]
+----
+MATCH (n:$($label)),
+      ()-[r:$($type)]->()
+----
+
+| xref:clauses/match.adoc#dynamic-match[`MATCH` nodes and relationships using dynamic node labels and relationship types]
+
+a| 
+[source, cypher, role="noheader"]
+----
+CREATE (n:$($label)),
+       ()-[r:$($type)]->()
+----
+
+| xref:clauses/create.adoc#dynamic-create[`CREATE` nodes and relationships using dynamic node labels and relationship types]
+
+a| 
+[source, cypher, role="noheader"]
+----
+MERGE (n:$($label)),
+       ()-[r:$($type)]->()
+----
+
+| xref:clauses/merge.adoc#dynamic-merge[`MERGE` nodes and relationships using dynamic node labels and relationship types]
+
+a|
+[source, cypher, role="noheader"]
+----
+LOAD CSV WITH HEADERS FROM 'file:///artists-with-headers.csv' AS line
+CREATE (n:$(line.label) {name: line.Name})
+----
+
+| xref:clauses/load-csv.adoc#dynamic-columns[Import CSV files using dynamic columns]
+
+
+a|
+[source, cypher, role="noheader"]
+----
+MATCH (n)
+SET n[$key] = value
+----
+
+| xref:clauses/set.adoc#dynamic-set-property[Dynamically `SET` or update a property]
+
+a|
+[source, cypher, role="noheader"]
+----
+MATCH (n:Label)
+SET n:$(n.property)
+----
+
+| xref:clauses/set.adoc#dynamic-set-node-label[Dynamically `SET` a node label]
+
+a|
+[source, cypher, role="noheader"]
+----
+MATCH (n {name: 'Peter'})
+REMOVE n:$($label)
+----
+
+| xref:clauses/remove.adoc#dynamic-remove-property[Dynamically `REMOVE` a property]
+
+a|
+[source, cypher, role="noheader"]
+----
+MATCH (n {name: 'Peter'})
+REMOVE n:$($label)
+----
+
+| xref:clauses/remove.adoc#dynamic-remove-node-label[Dynamically `REMOVE` a node label]
+
+|===
+
 
 [[functions]]
 == Functions
@@ -118,7 +206,10 @@ Either the pattern already exists, or it needs to be created.
 | Description
 
 | xref:functions/graph.adoc#functions-graph-by-elementid[`graph.byElementId()`]
-| Returns the graph reference with the given element id. It is only supported in the `USE` clause, on composite databases.
+| Returns the graph reference with the given element id. 
+It is only supported in the xref:clauses/use.adoc[`USE`] clause.
+As of Neo4j 5.26, it is supported on both link:{neo4j-docs-base-uri}/operations-manual/{page-version}/database-administration/[standard and composite databases].
+On earlier versions, it is only supported on composite databases.
 
 | xref:functions/graph.adoc#functions-graph-byname[`graph.byName()`]
 | Returns the graph reference of the given name. It is only supported in the `USE` clause, on composite databases.

modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc

@@ -41,5 +41,5 @@ Cypher Shell also offers specific link:{neo4j-docs-base-uri}/operations-manual/{
 | 21.3
 | <token>, <separator>, and <identifier>
 | GQL specifies a list of link:https://standards.iso.org/iso-iec/39075/ed-1/en/ISO_IEC_39075(en).bnf.txt[reserved words] that cannot be used for unquoted variable names, labels, and property names.
-Cypher also specifies a list of xref:syntax/reserved.adoc[reserved keywords], but it differs from GQL's.
+Cypher also specifies a list of xref:syntax/keywords.adoc[reserved keywords], but it differs from GQL's.
 |===

modules/ROOT/pages/appendix/gql-conformance/unsupported-mandatory.adoc

@@ -189,6 +189,8 @@ CALL db.labels() YIELD *
 If the procedure has deprecated return columns, those columns are also returned.
 
 Note that `YIELD *` is only valid in standalone procedure calls.
+Variables must be explicitly named in a `YIELD` clause if other clauses than a single procedure `CALL` are present.
+This restriction simplifies query logic and protects against output variables from the procedure accidentally clashing with other query variables.
 For example, the following is not valid:
 
 .Not allowed
@@ -204,7 +206,7 @@ RETURN count(*) AS results
 ====
 
 `YIELD` can be used to filter for specific results.
-This requires knowing the names of the arguments within a procedure's signature, which can either be found in the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/[Operations Manual -> Procedures] or returned by a `SHOW PROCEDURES` query.
+This requires knowing the names of the arguments within a procedure's signature, which can either be found in the link:{neo4j-docs-base-uri}/operations-manual/{page-version}/reference/procedures/[Operations Manual -> Procedures] or in the `signature` column returned by a `SHOW PROCEDURES` command (see example below).
 
 .Find the argument names of `db.propertyKeys`
 [source, cypher]

modules/ROOT/pages/clauses/call.adoc

@@ -205,10 +205,63 @@ Nodes created: 2 +
 Properties set: 4
 |===
 
+[role=label--new-5.26]
+[[dynamic-create]]
+== CREATE using dynamic node labels and relationship types
+
+Node labels and relationship types can be referenced dynamically in expressions, parameters, and variables when creating nodes and relationships.
+This allows for more flexible queries and mitigates the risk of Cypher injection.
+(For more information about Cypher injection, see link:https://neo4j.com/developer/kb/protecting-against-cypher-injection/[Neo4j Knowledge Base -> Protecting against Cypher injection]).
+
+.Syntax for creating nodes and relationships dynamically
+[source, syntax]
+----
+CREATE (n:$(<expr>))
+CREATE ()-[r:$(<expr>)]->()
+----
+
+The expression must evaluate to a `STRING NOT NULL | LIST<STRING NOT NULL> NOT NULL` value.
+Using a `LIST<STRING>` with more than one item when creating a relationship using dynamic relationship types will fail.
+This is because a relationship can only have exactly one type.
+
+.Parameters
+[source, parameters]
+----
+{
+  "nodeLabels": ["Person", "Director"],
+  "relType": "DIRECTED",
+  "movies": ["Ladybird", "Little Women", "Barbie"]
+}
+----
+
+.Create nodes and relationships using dynamic node labels and relationship types
+// tag::clauses_create_dynamic_create[]
+[source, cypher]
+----
+CREATE (greta:$($nodeLabels) {name: 'Greta Gerwig'})
+WITH greta
+UNWIND $movies AS movieTitle
+CREATE (greta)-[rel:$($relType)]->(m:Movie {title: movieTitle})
+RETURN greta.name AS name, labels(greta) AS labels, type(rel) AS relType, collect(m.title) AS movies
+----
+// end::clauses_create_dynamic_create[]
+
+.Result
+[role="queryresult",options="footer",cols="4*<m"]
+|===
+| name | labels | relType | movies
+
+| "Greta Gerwig"
+| ["Person", "Director"]
+| "DIRECTED"
+| ["Ladybird", "Little Women", "Barbie"]
+4+d|Rows: 1 +
+|===
+
 [role=label--new-5.18]
 [[insert-as-synonym-of-create]]
 == `INSERT` as a synonym of `CREATE`
- 
+
 `INSERT` can be used as a synonym to `CREATE` for creating nodes and relationships, and was introduced as part of Cypher's xref:appendix/gql-conformance/index.adoc[].
 However, `INSERT` requires that multiple labels are separated by an ampersand `&` and not by colon `:`.
 

modules/ROOT/pages/clauses/create.adoc

@@ -299,6 +299,53 @@ Added 4 nodes, Set 8 properties, Added 4 labels
 |===
 ====
 
+[role=label--new-5.26]
+[[dynamic-columns]]
+=== Import CSV files using dynamic columns
+
+CSV columns can be referenced dynamically to map labels to nodes in the graph.
+This enables flexible data handling, allowing labels to be be populated from CSV column values without manually specifying each entry.
+It also mitigates the risk of Cypher injection.
+(For more information about Cypher injection, see link:https://neo4j.com/developer/kb/protecting-against-cypher-injection/[Neo4j Knowledge Base -> Protecting against Cypher injection]).
+
+.bands-with-headers.csv
+[source, csv, filename="bands-with-headers.csv"]
+----
+Id,Label,Name
+1,Band,The Beatles
+2,Band,The Rolling Stones
+3,Band,Pink Floyd
+4,Band,Led Zeppelin
+----
+
+.Query
+// tag::clauses_load_csv_dynamic_columns[]
+[source, cypher]
+----
+LOAD CSV WITH HEADERS FROM 'file:///bands-with-headers.csv' AS line
+MERGE (n:$(line.Label) {name: line.Name})
+RETURN n AS bandNodes
+----
+// end::clauses_load_csv_dynamic_columns[]
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| bandNodes
+
+| (:Band {name: 'The Beatles'})
+| (:Band {name: 'The Rolling Stones'})
+| (:Band {name: 'Pink Floyd'})
+| (:Band {name: 'Led Zeppelin'})
+
+1+d|Rows: 4 +
+Added 4 nodes, Set 4 properties, Added 4 labels
+|===
+
+[NOTE]
+`MERGE` 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/overview.adoc[index] or not, and this is not possible when using dynamic values.
+For more information, see xref:clauses/merge.adoc#dynamic-merge-caveats[`MERGE` using dynamic node labels and relationship types -> Performance caveats].
 
 === Import compressed CSV files