Conditional queries (WHEN)
#1175
Conversation
JPryce-Aklundh
changed the title
WHEN)
| In Cypher, an expression is any combination of components that evaluates to a result. | ||
| Expressions are used to perform operations like calculations, comparisons, and data transformations within a query. | ||
|
|
||
| This section includes: | ||
|
|
||
| * xref:expressions/expressions-overview.adoc[] | ||
| * xref:expressions/conditional-expressions.adoc[] |
There was a problem hiding this comment.
For future consideration, EXISTS/COUNT/COLLECT might make more sense under here and moving CALL and CALL in transactions into the Clauses section.
| = Composed queries | ||
| :description: Overview about how to use `UNION` and `WHEN` to construct combined or conditional queries in Cypher. | ||
|
|
||
| `UNION` and `WHEN` enable the composition of multiple separate query branches within a single query. | ||
| `UNION` allows for combining the results of different queries, while `WHEN` enables conditional queries, where different query branches can be made to execute depending on a set of criteria. | ||
| As such, `UNION` and `WHEN` manage in different ways the execution flow and logic of queries and cannot be used in queries as regular clauses. | ||
|
|
||
| For more information, see: | ||
|
|
||
| * xref:queries/composed-queries/combined-queries.adoc[] | ||
| * xref:queries/composed-queries/conditional-queries.adoc[] label:new[Introduced in Neo4j 2025.02] |
| [}]] | ||
| ---- | ||
|
|
||
| The first predicate that evaluates to `true` will be executed. |
There was a problem hiding this comment.
| The first predicate that evaluates to `true` will be executed. | |
| The first branch with a predicate that evaluates to `true` will be executed. |
| WHEN false THEN RETURN 1 AS x | ||
| WHEN true THEN RETURN 2 AS x | ||
| ELSE RETURN 3 AS x |
There was a problem hiding this comment.
| WHEN false THEN RETURN 1 AS x | |
| WHEN true THEN RETURN 2 AS x | |
| ELSE RETURN 3 AS x | |
| WHEN false THEN RETURN 1 AS x | |
| WHEN true THEN RETURN 2 AS x | |
| WHEN true THEN RETURN 3 AS x | |
| ELSE RETURN 3 AS x |
| ELSE RETURN 3 AS x | ||
| ---- | ||
|
|
||
| Since the second `WHEN` branch is `true`, it will execute, while the preceding branch (which is `false`) and the succeeding `ELSE` branch will be skipped. |
There was a problem hiding this comment.
| Since the second `WHEN` branch is `true`, it will execute, while the preceding branch (which is `false`) and the succeeding `ELSE` branch will be skipped. | |
| Since the second `WHEN` branch is `true`, it will execute, while the preceding branch (which is `false`) and the succeeding `WHEN` branch (which is `true`) and the `ELSE` branch will be skipped. |
| ELSE { MATCH (n:Person) | ||
| RETURN n.name AS name | ||
| } |
There was a problem hiding this comment.
| ELSE { MATCH (n:Person) | |
| RETURN n.name AS name | |
| } | |
| ELSE { | |
| MATCH (n:Person) | |
| RETURN n.name AS name | |
| } |
There was a problem hiding this comment.
Maybe part of a larger discussion but how does the docs communicate that conditional query is only available in CYPHER 25
There was a problem hiding this comment.
This will be part of the 25 versions of the Manual, and not the 5 version. Together with the version label (which is now probably incorrect) and the page about selecting Cypher versions (see PR: #1123) I hope it will be clear to our readers.
|
|
||
| This page contains examples of allowed expressions in Cypher. | ||
| This page contains an overview of the allowed expressions in Cypher. | ||
|
|
||
| [[general]] | ||
| == General |
There was a problem hiding this comment.
Not really this PR, but I see the below list mentions dynamic properties, it could also now mention dynamic labels/types 😼
There was a problem hiding this comment.
Good call - will add at some point in the ongoing expressions work
| CALL (*) { | ||
| WHEN m.age > n.age THEN { | ||
| RETURN collect([m.name, m.ageGroup]) AS manager | ||
| } | ||
| ELSE { | ||
| RETURN collect([m.name, m.ageGroup]) AS manager | ||
| } |
There was a problem hiding this comment.
Is this query wrong? It doesn't make sense, I assume the second collect wanted to use n in the collect instead?
| n.age AS age | ||
| ---- | ||
|
|
||
| `Alice` and `Charlie` are both older than 40, so they are returned by the `WHEN` branch, while `Bob` is returned by the `ELSE` branch. |
There was a problem hiding this comment.
Maybe mention that some aren't matched in either branch, and are therefore left out?
| 1+d| Rows: 2 | ||
| |=== | ||
|
|
||
| If the queries combined by the `UNION` does not begin with a `WHEN` branch, then enclosing curly braces are not necessary. |
There was a problem hiding this comment.
| If the queries combined by the `UNION` does not begin with a `WHEN` branch, then enclosing curly braces are not necessary. | |
| If the queries combined by the `UNION` do not begin with a `WHEN` branch, then enclosing curly braces are not necessary. |
| RETURN person, message | ||
| UNION | ||
| CALL (*) { | ||
| WHEN n.age < 40 THEN { |
There was a problem hiding this comment.
Hahahah everyone over 40 are gonna be sad 😂
There was a problem hiding this comment.
"Older" is at least better than "Old" :)
| *Last updated*: 23 January October 2025 + | ||
| *Neo4j version*: 2025.02 |
There was a problem hiding this comment.
I guess this will be updated before merge :)
There was a problem hiding this comment.
Ah, I missed that - yep.
|
Thanks for the documentation updates. The preview documentation has now been torn down - reopening this PR will republish it. |
Builds on work in this PR: #1175 This PR does the following: - New "Predicate expressions" section including: -- "Predicate operators" (inclucing boolean, string, comparison, and list operators - content taken from syntax/operators.adoc, and several examples taken from clauses/where.adoc). **Redirect required** -- "Path pattern expressions "(content taken from clauses/where.adoc) -- "Type predicate expressions" (page moved from Values and types chapter) **Redirect required** - New page: "Equality, ordering, and comparison of value types" (content taken from syntax/operators.adoc) - Rewrite of WHERE page (significantly shorter due to several examples moved to new pages listed above)
This PR also moves Queries/Expressions/*.adoc to a new "Expressions" section.
This PR also subsumes #1109 (and therefore makes it redundant)