Conditional queries (WHEN) (#1175)

This PR also moves Queries/Expressions/*.adoc to a new "Expressions"
section.

This PR also subsumes #1109
(and therefore makes it redundant)

Author: JPryce-Aklundh

modules/ROOT/content-nav.adoc

@@ -6,8 +6,9 @@
 * xref:queries/index.adoc[]
 ** xref:queries/concepts.adoc[]
 ** xref:queries/basic.adoc[]
-** xref:queries/expressions.adoc[]
-** xref:queries/case.adoc[]
+** xref:queries/composed-queries/index.adoc[]
+*** xref:queries/composed-queries/combined-queries.adoc[]
+*** xref:queries/composed-queries/conditional-queries.adoc[]
 
 * xref:clauses/index.adoc[]
 ** xref:clauses/clause-composition.adoc[]
@@ -31,12 +32,15 @@
 ** xref:clauses/transaction-clauses.adoc#query-listing-transactions[SHOW TRANSACTIONS]
 ** xref:clauses/skip.adoc[]
 ** xref:clauses/transaction-clauses.adoc#query-terminate-transactions[TERMINATE TRANSACTIONS]
-** xref:clauses/union.adoc[]
 ** xref:clauses/unwind.adoc[]
 ** xref:clauses/use.adoc[]
 ** xref:clauses/where.adoc[]
 ** xref:clauses/with.adoc[]
 
+* xref:expressions/index.adoc[]
+** xref:expressions/expressions-overview.adoc[]
+** xref:expressions/conditional-expressions.adoc[]
+
 * xref:subqueries/index.adoc[]
 ** xref:subqueries/call-subquery.adoc[]
 ** xref:subqueries/subqueries-in-transactions.adoc[]

modules/ROOT/images/conditional_query_graph.svg

@@ -1,8 +1,8 @@
 :description: Overview of Cypher's conformance to GQL.
 = GQL conformance
 
-*Last updated*: 24 October 2024 +
-*Neo4j version*: 5.25
+*Last updated*: 21 February 2025 +
+*Neo4j version*: 2025.03
 
 GQL is the new link:https://www.iso.org/home.html[ISO] International Standard query language for graph databases.
 

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

@@ -28,6 +28,11 @@ The below table is instead listed in order of their appearance in the link:https
 
 Cypher supports the boolean type predicate for `TRUE`, `FALSE`, and `NULL` but does not support the GQL keyword `UNKNOWN`.
 
+| 9.1
+| <nested procedure specification>
+| xref:queries/composed-queries/combined-queries.adoc#combining-union-and-union-all[Combining `UNION` and `UNION ALL`]
+|
+
 | 13.2
 | <insert statement>
 | xref:clauses/create.adoc#insert-as-synonym-of-create[`INSERT`]
@@ -71,6 +76,11 @@ The only way to guarantee row order in Neo4j is to use xref:clauses/order-by.ado
 | GQL defines the option to specify `RETURN ALL` (functionally equivalent to using `RETURN` on its own).
 This is currently not available in Cypher.
 
+| 15.4
+| <conditional statement>
+| xref:queries/composed-queries/conditional-queries.adoc[]
+| 
+
 | 16.2
 | <limit clause>
 | xref:clauses/limit.adoc[`LIMIT`]
@@ -148,7 +158,7 @@ This is currently not available in Cypher.
 
 | 20.2
 | <value expression primary>
-| xref:queries/expressions.adoc[]
+| xref:expressions/expressions-overview.adoc[]
 |
 
 | 20.3
@@ -159,7 +169,7 @@ In Cypher, current user details can be seen using the link:{neo4j-docs-base-uri}
 
 | 20.7
 | <case expression>
-| xref:queries/case.adoc[`CASE`], xref:functions/scalar.adoc#functions-nullIf[`nullIf()`], xref:functions/scalar.adoc#functions-coalesce[`coalesce()`]
+| xref:expressions/conditional-expressions.adoc[`CASE`], xref:functions/scalar.adoc#functions-nullIf[`nullIf()`], xref:functions/scalar.adoc#functions-coalesce[`coalesce()`]
 |
 
 | 20.9

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

@@ -170,7 +170,7 @@ For example, GQL’s graph reference values `CURRENT_GRAPH` and `CURRENT_PROPERT
 
 | GQ03
 | Composite query: `UNION`
-| xref:clauses/union.adoc[`UNION`]
+| xref:queries/composed-queries/combined-queries.adoc[`UNION`]
 |
 
 | GQ13

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

@@ -297,7 +297,7 @@ the graph made by the `CREATE`.
 [[cypher-clause-composition-union-queries]]
 == Queries with `UNION`
 
-xref::clauses/union.adoc[`UNION`] queries are slightly different because the results of two or more queries are put together,
+xref::queries/composed-queries/combined-queries.adoc[`UNION`] queries are slightly different because the results of two or more queries are put together,
 but each query starts with an empty table of intermediate results.
 
 In a query with a `UNION` clause, any clause _before_ the `UNION` cannot observe writes made by a clause _after_ the `UNION`.

modules/ROOT/pages/clauses/clause-composition.adoc

@@ -152,12 +152,12 @@ Typically used when modifying or importing large amounts of data.
 |===
 |Clause |Description
 
-m| xref::clauses/union.adoc[UNION]
+m| xref::queries/composed-queries/combined-queries.adoc[UNION]
 a|
 Combines the result of multiple queries into a single result set.
 Duplicates are removed.
 
-m| xref::clauses/union.adoc[UNION ALL]
+m| xref::queries/composed-queries/combined-queries.adoc[UNION ALL]
 a|
 Combines the result of multiple queries into a single result set.
 Duplicates are retained.

modules/ROOT/pages/clauses/index.adoc

@@ -25,7 +25,7 @@ When connected to a composite database, a graph reference may additionally be pa
 
 * The graph function xref:functions/graph.adoc#functions-graph-byname[`graph.byName()`], which allows the graph reference to be resolved dynamically: `USE graph.byName(<string-expression>)`.
 
-A more detailed description of how and when a graph references needs to be quoted and/or escaped is defined xref::queries/expressions.adoc#graphreferences[here].
+A more detailed description of how and when a graph references needs to be quoted and/or escaped is defined xref::expressions/expressions-overview.adoc#graphreferences[here].
 
 == USE clause when connected to a standard or system database
 

modules/ROOT/pages/clauses/use.adoc

@@ -461,7 +461,7 @@ The `name`, `age`, and `email` values for `Peter` are returned because his email
 Note that the regular expression constructs in
 link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html[Java regular expressions]
 are applied only after resolving the escaped character sequences in the given
-xref::queries/expressions#expressions-string-literals[string literal].
+xref::expressions/expressions-overview.adoc#expressions-string-literals[string literal].
 It is sometimes necessary to add additional backslashes to express regular expression
 constructs.
 This list clarifies the combination of these two definitions, containing the original escape sequence and the resulting character in the regular expression:
@@ -532,7 +532,7 @@ In other words, it must contain at least one xref::patterns/reference.adoc#relat
 * Path pattern expressions may not declare new variables.
 They can only reference existing variables.
 
-* Path pattern expressions may only be used in positions where a xref:queries/expressions.adoc#boolean[boolean expression] is expected.
+* Path pattern expressions may only be used in positions where a xref:expressions/expressions-overview.adoc#boolean[boolean expression] is expected.
 The following sections will demonstrate how to use path pattern expressions in a `WHERE` clause.
 
 [[filter-on-patterns]]