Merge branch 'dev' into warn-insecure-protocols

antora.yml

@@ -7,5 +7,5 @@ nav:
 asciidoc:
   attributes:
     neo4j-version: '5'
-    neo4j-version-minor: '5.22'
-    neo4j-version-exact: '5.22.0'
+    neo4j-version-minor: '5.23'
+    neo4j-version-exact: '5.23.0'

modules/ROOT/pages/appendix/gql-conformance/index.adoc

@@ -1,8 +1,8 @@
 :description: Overview of Cypher's conformance to GQL.
 = GQL conformance
 
-*Last updated*: 5 July 2024 +
-*Neo4j version*: 5.21
+*Last updated*: 8 August 2024 +
+*Neo4j version*: 5.23
 
 GQL is the new link:https://www.iso.org/home.html[ISO] International Standard query language for graph databases.
 
@@ -42,5 +42,5 @@ Neo4j 5.14 added support for JavaSE 21 and version 15 of the Unicode Standard.
 For more information, see xref:syntax/parsing.adoc##_using_unicodes_in_cypher[Parsing -> Using Unicode in Cypher].
 * Cypher supports the following mandatory GQL property types: `BOOLEAN` (`BOOL`), `FLOAT` footnote:[The `FLOAT` type in Cypher always represents a 64-bit double-precision floating point number.], `INTEGER` (`SIGNED INTEGER`, or `INT`)footnote:[The `INTEGER` type in Cypher always represents a 64-bit `INTEGER`.], and `STRING` (`VARCHAR`).
 +
-Cypher also supports the following optional GQL property types: `DATE`, `DURATION`, `LIST<INNER_TYPE NOT NULL>` (`ARRAY<INNER_TYPE NOT NULL>`, `INNER_TYPE LIST`, or `INNER_TYPE ARRAY`)footnote:[The `INNER_TYPE` cannot be a `LIST` type.], `LOCAL DATETIME` (`TIMESTAMP WITHOUT TIMEZONE`), `LOCAL TIME` (`TIME WITHOUT TIME ZONE`), `POINT`, `ZONED DATETIME` (`TIME WITH TIMEZONE`), and `ZONED TIME` (`TIMESTAMP WITH TIMEZONE`).
+Cypher also supports the following optional GQL property types: `DATE`, `DURATION`, `LIST<INNER_TYPE NOT NULL>` (`ARRAY<INNER_TYPE NOT NULL>`, `INNER_TYPE LIST`, or `INNER_TYPE ARRAY`)footnote:[The `INNER_TYPE` cannot be a `LIST` type.], `LOCAL DATETIME` (`TIMESTAMP WITHOUT TIME ZONE`), `LOCAL TIME` (`TIME WITHOUT TIME ZONE`), `POINT`, `ZONED DATETIME` (`TIME WITH TIME ZONE`), and `ZONED TIME` (`TIMESTAMP WITH TIME ZONE`).
 For more information, see xref:values-and-types/property-structural-constructed.adoc#_property_types[Values and types -> property types].

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

@@ -81,7 +81,7 @@ This is not available in Cypher.
 | <inline procedure call>
 | xref:subqueries/call-subquery.adoc[`CALL` subqueries].
 | GQL either imports variables implicitly, or explicitly using a variable scope clause.
-In Cypher, `CALL` subqueries require an explicit importing `WITH` clause.
+In Cypher, it is currently not possible to implicitly import variables.
 
 | 15.3
 | <named procedure call>

modules/ROOT/pages/appendix/gql-conformance/supported-optional.adoc

@@ -129,6 +129,14 @@ In Cypher, `trim()` removes any whitespace character.
 |
 |
 
+| GP01
+| xref:subqueries/call-subquery.adoc[Inline procedure]
+|
+
+| GP03
+| xref:subqueries/call-subquery.adoc#variable-scope-clause[Inline procedure with explicit nested variable scope]
+|
+
 | GQ01
 | `USE` graph clause
 | xref:clauses/use.adoc[`USE`]

modules/ROOT/pages/clauses/load-csv.adoc

@@ -608,12 +608,15 @@ person_tmdbId,bio,born,bornIn,died,person_imdbId,name,person_poster,person_url
 ...
 ----
 
+[NOTE]
+The below query uses a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause] (introduced in Neo4j 5.23) to import variables into the `CALL` subquery.
+If you are using an older version of Neo4j, use an xref:subqueries/call-subquery.adoc#importing-with[importing `WITH` clause] instead.
+
 .Query
 [source, cypher]
 ----
 LOAD CSV WITH HEADERS FROM 'https://data.neo4j.com/importing-cypher/persons.csv' AS row
-CALL {
-  WITH row
+CALL (row) {
   MERGE (p:Person {tmdbId: row.person_tmdbId})
   SET p.name = row.name, p.born = row.born
 } IN TRANSACTIONS OF 200 ROWS

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

@@ -16,6 +16,77 @@ New features are added to the language continuously, and occasionally, some feat
 This section lists all of the features that have been removed, deprecated, added, or extended in different Cypher versions.
 Replacement syntax for deprecated and removed features are also indicated.
 
+[[cypher-deprecations-additions-removals-5.23]]
+== Neo4j 5.23
+
+=== Deprecated features
+
+[cols="2", options="header"]
+|===
+| Feature
+| Details
+
+a|
+label:functionality[]
+label:deprecated[]
+[source, cypher, role="noheader"]
+----
+UNWIND [0, 1, 2] AS x
+CALL {
+  WITH x
+  RETURN x * 10 AS y
+}
+RETURN x, y
+----
+
+| Using the xref:subqueries/call-subquery.adoc#importing-with[`WITH` clause to import variables] to `CALL` subqueries is deprecated, and replaced with a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause].
+It is also deprecated to use naked subqueries without a variable scope clause.
+|===
+
+=== Updated features
+
+
+[cols="2", options="header"]
+|===
+| Feature
+| Details
+
+a|
+label:functionality[]
+label:updated[]
+[source, cypher, role="noheader"]
+----
+RETURN datetime.statement() IS :: TIMESTAMP WITH TIME ZONE
+----
+a|
+Introduced new GQL conformant aliases to duration types: `TIMESTAMP WITHOUT TIME ZONE` (alias to `LOCAL DATETIME`), `TIME WITHOUT TIME ZONE` (alias to `LOCAL TIME`), `TIMESTAMP WITH TIME ZONE` (alias to `ZONED DATETIME`), and `TIME WITH TIME ZONE` (alias to `ZONED TIME`).
+
+See xref::values-and-types/property-structural-constructed.adoc#types-synonyms[types and their synonyms] for more.
+|===
+
+=== New features
+
+[cols="2", options="header"]
+|===
+| Feature
+| Details
+
+a|
+label:functionality[]
+label:new[]
+[source, cypher, role="noheader"]
+----
+UNWIND [0, 1, 2] AS x
+CALL (x) {
+   RETURN x * 10 AS y
+}
+RETURN x, y
+----
+
+| Introduced a new xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause] to import variables in `CALL` subqueries.
+
+|===
+
 [[cypher-deprecations-additions-removals-5.21]]
 == Neo4j 5.21
 

modules/ROOT/pages/functions/list.adoc

@@ -424,8 +424,8 @@ A `LIST<RELATIONSHIP>` containing all the `RELATIONSHIP` values in the `PATH` `p
 [role="queryresult",options="header,footer",cols="1*<m"]
 |===
 
-| +relationships(p)+
-| +[:KNOWS[0]{},:MARRIED[4]{}]+
+| relationships(p)
+| [[:KNOWS], [:MARRIED]]
 1+d|Rows: 1
 
 |===

modules/ROOT/pages/genai-integrations.adoc

@@ -180,9 +180,8 @@ WITH collect(m) AS moviesList // <1>
      count(*) AS total,
      100 AS batchSize // <2>
 UNWIND range(0, total, batchSize) AS batchStart // <3>
-CALL { // <4>
-    WITH moviesList, batchStart, batchSize
-    WITH moviesList, batchStart, [movie IN moviesList[batchStart .. batchStart + batchSize] | movie.title || ': ' || movie.plot] AS resources // <5>
+CALL (moviesList, batchStart, batchSize) { // <4>
+    WITH [movie IN moviesList[batchStart .. batchStart + batchSize] | movie.title || ': ' || movie.plot] AS resources // <5>
     CALL genai.vector.encodeBatch(batch, 'OpenAI', { token: $token }) YIELD index, vector
     CALL db.create.setNodeVectorProperty(moviesList[batchStart + index], 'embedding', vector) // <6>
 } IN TRANSACTIONS OF 1 ROW <7>
@@ -194,6 +193,8 @@ Because vector embeddings can be very large, a larger batch size may require sig
 Too large a batch size may also exceed the provider's threshold.
 <3> Process `Movie` nodes in increments of `batchSize`.
 <4> A xref:subqueries/subqueries-in-transactions.adoc[`CALL` subquery] executes a separate transaction for each batch.
+Note that this `CALL` subquery uses a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause] (introduced in Neo4j 5.23) to import variables.
+If you are using an older version of Neo4j, use an  xref:subqueries/call-subquery.adoc#importing-with[importing `WITH` clause] instead.
 <5> `resources` is a list of strings, each being the concatenation of `title` and `plot` of one movie.
 <6> The procedure sets `vector` as value for the property named `embedding` for the node at position `batchStart + index` in the `moviesList`.
 <7> Set to `1` the amount of batches to be processed at once.

modules/ROOT/pages/patterns/reference.adoc

@@ -779,7 +779,7 @@ Matches one or more relationships with type `R` and of any direction, and any no
 ()-[:R]-+()
 ----
 
-Matches paths consisting of two inbound subpaths, one with relationships of type `A` and one with relationships of type `B`, meeting at a node with label `A`:
+Matches paths consisting of two inbound subpaths, one with relationships of type `R` and one with relationships of type `S`, meeting at a node with label `A`:
 [source, role=noheader]
 ----
 ()-[:R]->+(:A)<-[:S]-+()

modules/ROOT/pages/patterns/shortest-paths.adoc

@@ -552,15 +552,18 @@ To have the planner choose the `StatefulShortestPath(Into)` instead, rewrite the
 
 For example, in the below query, using a `CALL` subquery ensures that the planner binds `a` and `b` to exactly one `Station` node respectively for each executed row, and this forces it to use `StatefulShortestPath(Into)` for each invocation of the `CALL` subquery, since a precondition of using this operator is that both boundary nodes match exactly one node each.
 
+[NOTE]
+The below query uses a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause] (introduced in Neo4j 5.23) to import variables into the `CALL` subquery.
+If you are using an older version of Neo4j, use an xref:subqueries/call-subquery.adoc#importing-with[importing `WITH` clause] instead.
+
 .Query rewritten to use `StatefulShortestPath(Into)`
 [source,cypher]
 ----
 PROFILE
 MATCH
   (a:Station {name: "Worcestershire Parkway"}),
   (b:Station)
-CALL {
-  WITH a, b
+CALL (a, b) {
   MATCH
     p = SHORTEST 1 (a)(()-[]-()-[]-()){1,}(b)
   RETURN p

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

@@ -2811,13 +2811,16 @@ Total database accesses: 166, total allocated memory: 976
 .TransactionApply
 ======
 
+[NOTE]
+The below query uses a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause] (introduced in Neo4j 5.23) to import variables into the `CALL` subquery.
+If you are using an older version of Neo4j, use an xref:subqueries/call-subquery.adoc#importing-with[importing `WITH` clause] instead.
+
 .Query
 [source, cypher]
 ----
 PROFILE
 LOAD CSV FROM 'https://neo4j.com/docs/cypher-refcard/3.3/csv/artists.csv' AS line
-CALL {
-  WITH line
+CALL (line) {
   CREATE (a: Artist {name: line[0]})
   RETURN a
 } IN TRANSACTIONS OF 100 ROWS
@@ -3512,13 +3515,16 @@ This restricts the xref:planning-and-tuning/runtimes/index.adoc[Cypher runtime]
 .ArgumentTracker
 ======
 
+[NOTE]
+The below query uses a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause] (introduced in Neo4j 5.23) to import variables into the `CALL` subquery.
+If you are using an older version of Neo4j, use an xref:subqueries/call-subquery.adoc#importing-with[importing `WITH` clause] instead.
+
 .Query
 [source, cypher]
 ----
 PROFILE
 MATCH (s:Person {name: 'me'})
-CALL {
-   WITH s
+CALL (s) {
    SET s.seen = coalesce(s.seen + 1,1)
    RETURN s.seen AS result
 }
@@ -4787,13 +4793,16 @@ Total database accesses: 9, total allocated memory: 64
 .TransactionForeach
 ======
 
+[NOTE]
+The below query uses a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause] (introduced in Neo4j 5.23) to import variables into the `CALL` subquery.
+If you are using an older version of Neo4j, use an xref:subqueries/call-subquery.adoc#importing-with[importing `WITH` clause] instead.
+
 .Query
 [source, cypher]
 ----
 PROFILE
 LOAD CSV FROM 'https://neo4j.com/docs/cypher-refcard/3.3/csv/artists.csv' AS line
-CALL {
-  WITH line
+CALL (line) {
   CREATE (a: Artist {name: line[0]})
 } IN TRANSACTIONS OF 100 ROWS
 ----
@@ -4839,13 +4848,16 @@ Batch size 128
 .SubqueryForeach
 ======
 
+[NOTE]
+The below query uses a xref:subqueries/call-subquery.adoc#variable-scope-clause[variable scope clause] (introduced in Neo4j 5.23) to import variables into the `CALL` subquery.
+If you are using an older version of Neo4j, use an xref:subqueries/call-subquery.adoc#importing-with[importing `WITH` clause] instead.
+
 .Query
 [source, cypher]
 ----
 PROFILE
 LOAD CSV FROM 'https://neo4j.com/docs/cypher-refcard/3.3/csv/artists.csv' AS line
-CALL {
-  WITH line
+CALL (line) {
   CREATE (a: Artist {name: line[0]})
 }
 ----

modules/ROOT/pages/queries/case.adoc

@@ -323,3 +323,29 @@ RETURN n.name, n.colorCode
 |===
 
 For more information about using the `SET` clause, see xref::clauses/set.adoc[SET].
+
+== Further considerations
+
+`CASE` result branches are statically checked prior to execution. 
+This means that if a branch is not semantically correct, it will still throw an exception, even if that branch may never be executed during runtime.
+
+In the following example, `date` is statically known to be a `STRING` value, and therefore would fail if treated as a `DATE` value. 
+
+.Not allowed
+[source, cypher, role=test-fail]
+----
+WITH "2024-08-05" AS date, "string" AS type
+RETURN CASE type
+    WHEN "string" THEN datetime(date)
+    WHEN "date" THEN datetime({year: date.year, month: date.month, day: date.day})
+    ELSE datetime(date)
+END AS dateTime
+----
+
+.Error message
+[source, error]
+----
+Type mismatch: expected Map, Node, Relationship, Point, Duration, Date, Time, LocalTime, LocalDateTime or DateTime but was String (line 4, column 38 (offset: 136))
+"    WHEN 'date' THEN datetime({year: date.year, month: date.month, day: date.day})"
+                                      ^
+----