From d3aafdc58ee2f3367d11e6b1f09d848c13d66afc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Wed, 26 Mar 2025 09:21:55 +0100
Subject: [PATCH 01/10] initial structure

---
 modules/ROOT/content-nav.adoc                 |  1 +
 modules/ROOT/pages/expressions/index.adoc     |  1 +
 .../pages/expressions/list-expressions.adoc   | 20 +++++++++++++++++++
 3 files changed, 22 insertions(+)
 create mode 100644 modules/ROOT/pages/expressions/list-expressions.adoc

diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc
index 5bc92b6e8..b1bf4a547 100644
--- a/modules/ROOT/content-nav.adoc
+++ b/modules/ROOT/content-nav.adoc
@@ -76,6 +76,7 @@
 ** xref:expressions/mathematical-operators.adoc[]
 ** xref:expressions/string-operators.adoc[]
 ** xref:expressions/temporal-operators.adoc[]
+** xref:expressions/list-expressions.adoc[]
 ** xref:expressions/conditional-expressions.adoc[]
 
 * xref:functions/index.adoc[]
diff --git a/modules/ROOT/pages/expressions/index.adoc b/modules/ROOT/pages/expressions/index.adoc
index 3dbcd364e..a02658a8f 100644
--- a/modules/ROOT/pages/expressions/index.adoc
+++ b/modules/ROOT/pages/expressions/index.adoc
@@ -14,5 +14,6 @@ For details and examples of specific expressions, see the following sections:
 * xref:expressions/mathematical-operators.adoc[]: `+`, `-`, `*`, `/`, `%`, `^`.
 * xref:expressions/string-operators.adoc[]: `+`, `||`
 * xref:expressions/temporal-operators.adoc[]: `+`, `-`, `*`, `/`
+* xref:expressions/list-expressions.adoc[]: information about list concatenation operators, list element access, list slicing, and list as well as pattern comprehensions.
 * xref:expressions/conditional-expressions.adoc[]
 
diff --git a/modules/ROOT/pages/expressions/list-expressions.adoc b/modules/ROOT/pages/expressions/list-expressions.adoc
new file mode 100644
index 000000000..20018a39b
--- /dev/null
+++ b/modules/ROOT/pages/expressions/list-expressions.adoc
@@ -0,0 +1,20 @@
+= List expressions
+:description: Information about Cypher's list expressions.
+:table-caption!:
+
+List expressions are a way to manipulate and query lists in Cypher.
+They allow for operations like concatenation, element access, slicing, and transformations using comprehensions. 
+
+For more expressions that evaluate to a xref:values-and-types/lists.adoc[`LIST`] value, see xref:functions/list.adoc[List functions].
+
+== List operators
+
+== List element access
+
+== List slicing
+
+== List comprehension
+
+== Pattern comprehension
+
+

From 88271da8a3c17e8a33b21967b6386981fcc1f57b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Fri, 28 Mar 2025 09:17:23 +0100
Subject: [PATCH 02/10] list element access

---
 modules/ROOT/pages/expressions/index.adoc     |   2 +-
 .../pages/expressions/list-expressions.adoc   | 211 +++++++++++++++++-
 modules/ROOT/pages/syntax/operators.adoc      | 210 -----------------
 3 files changed, 206 insertions(+), 217 deletions(-)

diff --git a/modules/ROOT/pages/expressions/index.adoc b/modules/ROOT/pages/expressions/index.adoc
index a02658a8f..f2b0fc0ec 100644
--- a/modules/ROOT/pages/expressions/index.adoc
+++ b/modules/ROOT/pages/expressions/index.adoc
@@ -14,6 +14,6 @@ For details and examples of specific expressions, see the following sections:
 * xref:expressions/mathematical-operators.adoc[]: `+`, `-`, `*`, `/`, `%`, `^`.
 * xref:expressions/string-operators.adoc[]: `+`, `||`
 * xref:expressions/temporal-operators.adoc[]: `+`, `-`, `*`, `/`
-* xref:expressions/list-expressions.adoc[]: information about list concatenation operators, list element access, list slicing, and list as well as pattern comprehensions.
+* xref:expressions/list-expressions.adoc[]: information about list concatenation operators (`||`, `+`), list element access, list slicing, and list as well as pattern comprehensions.
 * xref:expressions/conditional-expressions.adoc[]
 
diff --git a/modules/ROOT/pages/expressions/list-expressions.adoc b/modules/ROOT/pages/expressions/list-expressions.adoc
index 20018a39b..b9d7494c3 100644
--- a/modules/ROOT/pages/expressions/list-expressions.adoc
+++ b/modules/ROOT/pages/expressions/list-expressions.adoc
@@ -2,19 +2,218 @@
 :description: Information about Cypher's list expressions.
 :table-caption!:
 
-List expressions are a way to manipulate and query lists in Cypher.
+List expressions are a way to manipulate and query xref:values-and-types/lists.adoc[`LIST`] values in Cypher.
 They allow for operations like concatenation, element access, slicing, and transformations using comprehensions. 
 
-For more expressions that evaluate to a xref:values-and-types/lists.adoc[`LIST`] value, see xref:functions/list.adoc[List functions].
+For more expressions that evaluate to a `LIST` value, see xref:functions/list.adoc[List functions]. +
+For information about how to check membership in a `LIST` using the `IN` operator, see xref:expressions/predicates/list-operators.adoc[Predicates -> List operators].
 
-== List operators
+== Example graph
+
+[source, cypher]
+----
+CREATE (alice:Person {name:'Alice', age: 65, role: 'Project manager', skills: ['Java', 'Python']}),
+       (cecil:Person {name: 'Cecil', age: 25, role: 'Software developer', skills: ['Java', 'Python']}),
+       (cecilia:Person {name: 'Cecilia', age: 31, role: 'Software developer', skills: ['JavaScript', 'TypeScript']}),  
+       (charlie:Person {name: 'Charlie', age: 61, role: 'Security engineer', skills: ['C++', 'Python']}),
+       (daniel:Person {name: 'Daniel', age: 39, role: 'Director', skills: ['Ruby', 'Go']}),  
+       (eskil:Person {name: 'Eskil', age: 39, role: 'CEO'}),  
+
+       (alice)-[:WORKS_FOR]->(daniel),
+       (cecil)-[:WORKS_FOR]->(alice),
+       (cecilia)-[:WORKS_FOR]->(alice),
+       (charlie)-[:WORKS_FOR]->(daniel),
+       (daniel)-[:WORKS_FOR]->(eskil)
+----
+
+== List concatenation
+
+Cypher contains two list concatenation operators: `||` and `+`.
+`||` is xref:appendix/gql-conformance/index.adoc[GQL conformant], while `+` is not.
+
+.List concatenation using `||` and `+`
+[source, cypher]
+----
+RETURN [1,2] || [3,4] AS list1,
+       [1,2] + [3,4] AS list2
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| list1 | list2
+
+| [1, 2, 3, 4] | [1, 2, 3, 4]
+
+2+d|Rows: 1
+|===
+
+.Concatenating two `LIST` properties
+[source, cypher]
+----
+MATCH (cecil:Person {name: 'Cecil'}), (cecilia:Person {name: 'Cecilia'})
+RETURN cecil.skills || cecilia.skills AS combinedSkills
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| combinedSkills
+
+| ["Java", "Python", "JavaScript", "TypeScript"]
+
+1+d|Rows: 1
+|===
+
+The `+` operator can add elements to the beginning of a `LIST` value.
+This is not possible using the `||` operator.
+
+.Adding elements to the beginning of a `LIST` with `+`
+[source, cypher]
+----
+MATCH (cecil:Person {name: 'Cecil'})
+SET cecil.skills = "Cypher" + cecil.skills
+RETURN cecil.skills AS skillsList
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| skillsList
+
+| ["Cypher", "Java", "Python"] 
+
+1+d|Rows: 1
+|===
+
+If `NULL` is part of a concatenated `LIST`, `NULL` will be a part of the new `LIST`.
+
+.Concatenating `LIST` including `NULL`
+[source, cypher]
+----
+RETURN [1, 2] || [3, null] AS listWithNull
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| listWithNull
+
+| [1, 2, 3, NULL]
+
+1+d|Rows: 1
+|===
 
 == List element access
 
-== List slicing
+The subscript operator, `[]`, can be used to access specific elements in a `LIST`.
+`[0]` refers to the first element in a `LIST`, `[1]` to the second, and so on.
+`[-1]` refers to the last element in a `LIST`, `[-2]` to the penultimate element, and so on.
+
+.Accessing individual elements in a `LIST`
+[source, cypher]
+----
+WITH [1, 2, 3, 4] AS list
+RETURN list[0] AS firstElement
+       list[2] AS thirdElement
+       list[-1] AS finalElement
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="3*<m"]
+|===
+| firstElement | thirdElement | finalElement
+
+| 1 | 3 | 4
+
+3+d|Rows: 1
+|===
+
+The index of the element in the `LIST` can be parameterized.
+
+.Parameters
+[source, parameters]
+----
+{
+  "myIndex" : 1
+}
+----
+
+.Accessing `LIST` elements with a parameter
+[source, cypher]
+----
+WITH [1, 2, 3, 4] AS list
+RETURN list[$myIndex] AS secondElement
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| secondElement
+
+| 2
+
+1+d|Rows: 1
+|===
+
+The xref:expressions/predicates/list-operators.adoc[`IN`] operator, which checks for `LIST` membership, can be used together with `[]` to test whether an element exists in a nested `LIST`.
+
+.Checking for membership in nested `LIST`
+[source, cypher]
+----
+WITH [[1, 2, 3], [4, 5, 6]] AS nestedList
+RETURN 3 IN nestedList[0] AS elementPresent
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| elementPresent
+
+| TRUE
+
+1+d|Rows: 1
+|===
+
+Attempting to reference an element outside the bounds of the `LIST` will return `NULL`, as will attempting to access elements from an empty `LIST`.
+
+.Out-of-bounds and empty list access
+[source, cypher]
+----
+WITH [1, 2, 3, 4] AS list, [] AS emptyList
+RETURN list[5] AS outOfBound, emptyList[0] AS emptyAccess
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| outOfBound | emptyAccess
+
+| NULL | NULL
+
+2+d|Rows: 1
+|===
+
+
+
+=== NULL and LIST comprehension
 
-== List comprehension
 
-== Pattern comprehension
 
+If you want to remove all null values from the concatenated lists, you can use a list comprehension to filter them out. This way, you're not even concerned with their positions, and it's much cleaner and easier.
 
+Example:
+cypher
+Copy
+Edit
+RETURN [1, null, 3] || [null, 5, null] AS combinedList,
+       [x IN ([1, null, 3] || [null, 5, null]) WHERE x IS NOT NULL] AS filteredList;
+Result:
+sql
+Copy
+Edit
++---------------------------------------------+
+| combinedList           | filteredList      |
++---------------------------------------------+
+| [1, NULL, 3, NULL, 5, NULL] | [1, 3, 5]        |
++---------------------------------------------+
diff --git a/modules/ROOT/pages/syntax/operators.adoc b/modules/ROOT/pages/syntax/operators.adoc
index 0766800d8..3a65403d5 100644
--- a/modules/ROOT/pages/syntax/operators.adoc
+++ b/modules/ROOT/pages/syntax/operators.adoc
@@ -251,213 +251,3 @@ RETURN a[$myKey] AS result
 |===
 
 More information can be found in the xref::values-and-types/maps.adoc[Maps chapter].
-
-[[query-operators-list]]
-== List operators
-
-The list operators comprise:
-
-* concatenating lists `l~1~` and `l~2~`: `[l~1~] + [l~2~]` and `[l~1~] || [l~2~]`
-* checking if an element `e` exists in a list `l`: `e IN [l]`
-* dynamically accessing an element(s) in a list using the subscript operator: `[]`
-
-[NOTE]
-====
-The behavior of the `IN` and `[]` operators with respect to `null` is detailed xref::values-and-types/working-with-null.adoc[here].
-====
-
-
-[[syntax-concatenating-two-lists]]
-=== Concatenating two lists using `+`
-
-.Query
-[source, cypher]
-----
-RETURN [1,2,3,4,5] + [6,7] AS myList
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +myList+
-| +[1,2,3,4,5,6,7]+
-
-1+d|Rows: 1
-|===
-
-
-[[syntax-concatenating-two-lists-with-doublebar]]
-=== Concatenating two lists using `||`
-
-.Query
-[source, cypher]
-----
-RETURN [1,2,3,4,5] || [6,7] AS myList
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| myList
-| [1,2,3,4,5,6,7]
-
-1+d|Rows: 1
-|===
-
-
-[[syntax-using-in-to-check-if-a-number-is-in-a-list]]
-=== Using `IN` to check if a number is in a list
-
-.Query
-[source, cypher]
-----
-WITH [2, 3, 4, 5] AS numberlist
-UNWIND numberlist AS number
-WITH number
-WHERE number IN [2, 3, 8]
-RETURN number
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +number+
-| +2+
-| +3+
-
-1+d|Rows: 2
-|===
-
-
-[[syntax-using-in-for-more-complex-list-membership-operations]]
-=== Using `IN` for more complex list membership operations
-
-The general rule is that the `IN` operator will evaluate to `true` if the list given as the right-hand operand contains an element which has the same _type and contents (or value)_ as the left-hand operand.
-Lists are only comparable to other lists, and elements of a list `innerList` are compared pairwise in ascending order from the first element in `innerList` to the last element in `innerList`.
-
-The following query checks whether or not the list `[2, 1]` is an element of the list `[1, [2, 1], 3]`:
-
-.Query
-[source, cypher]
-----
-RETURN [2, 1] IN [1, [2, 1], 3] AS inList
-----
-
-The query evaluates to `true` as the right-hand list contains, as an element, the list `[1, 2]` which is of the same type (a list) and contains the same contents (the numbers `2` and `1` in the given order) as the left-hand operand.
-If the left-hand operator had been `[1, 2]` instead of `[2, 1]`, the query would have returned `false`.
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +inList+
-| +true+
-
-1+d|Rows: 1
-|===
-
-At first glance, the contents of the left-hand operand and the right-hand operand _appear_ to be the same in the following query:
-
-.Query
-[source, cypher]
-----
-RETURN [1, 2] IN [1, 2] AS inList
-----
-
-However, `IN` evaluates to `false` as the right-hand operand does not contain an element that is of the same _type_ -- i.e. a _list_ -- as the left-hand-operand.
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +inList+
-| +false+
-
-1+d|Rows: 1
-|===
-
-The following query can be used to ascertain whether or not a list -- obtained from, say, the xref::functions/list.adoc#functions-labels[labels()] function -- contains at least one element that is also present in another list:
-
-[source, cypher]
-----
-MATCH (n)
-WHERE size([label IN labels(n) WHERE label IN ['Person', 'Employee'] | 1]) > 0
-RETURN count(n)
-----
-
-As long as `labels(n)` returns either `Person` or `Employee` (or both), the query will return a value greater than zero.
-
-
-[[syntax-accessing-elements-in-a-list]]
-=== Accessing elements in a list using the `[]` operator
-
-.Query
-[source, cypher]
-----
-WITH ['Anne', 'John', 'Bill', 'Diane', 'Eve'] AS names
-RETURN names[1..3] AS result
-----
-
-The square brackets will extract the elements from the start index `1`, and up to (but excluding) the end index `3`.
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +result+
-| +["John","Bill"]+
-
-1+d|Rows: 1
-|===
-
-
-[[syntax-accessing-element-in-a-list-parameter]]
-=== Dynamically accessing an element in a list using the `[]` operator and a parameter
-
-A parameter may be used to specify the index of the element to access:
-
-.Parameters
-[source, parameters]
-----
-{
-  "myIndex" : 1
-}
-----
-
-.Query
-[source, cypher]
-----
-WITH ['Anne', 'John', 'Bill', 'Diane', 'Eve'] AS names
-RETURN names[$myIndex] AS result
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +result+
-| +"John"+
-
-1+d|Rows: 1
-|===
-
-
-[[syntax-using-in-with-nested-list-subscripting]]
-=== Using `IN` with `[]` on a nested list
-
-`IN` can be used in conjunction with `[]` to test whether an element exists in a nested list:
-
-.Query
-[source, cypher]
-----
-WITH [[1, 2, 3]] AS l
-RETURN 3 IN l[0] AS result
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +result+
-| +true+
-
-1+d|Rows: 1
-|===
-
-More details on lists can be found in xref::values-and-types/lists.adoc#cypher-lists-general[Lists in general].
-

From 40c463bc7a3231c93d1b3758a6a88366cf38741f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Mon, 31 Mar 2025 11:07:06 +0200
Subject: [PATCH 03/10] add graph, fix list values page

---
 .../ROOT/images/list_expressions_graph.svg    |   1 +
 .../pages/expressions/list-expressions.adoc   | 364 ++++++++++++++++--
 .../ROOT/pages/values-and-types/lists.adoc    | 166 +-------
 3 files changed, 360 insertions(+), 171 deletions(-)
 create mode 100644 modules/ROOT/images/list_expressions_graph.svg

diff --git a/modules/ROOT/images/list_expressions_graph.svg b/modules/ROOT/images/list_expressions_graph.svg
new file mode 100644
index 000000000..3fdbc2779
--- /dev/null
+++ b/modules/ROOT/images/list_expressions_graph.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1046" height="417" viewBox="0 0 1046 417"><defs><style type="text/css"/></defs><g transform="translate(-199.44276565549808 194.86687123888817) scale(1)"><g class="relationship"><g transform="translate(303.6087812804981 -140.86687123888817) rotate(21.654233935053426)" stroke-width="2" stroke="#000000"><path d="M 59 0 L 191.19752627483626 0"/><polygon points="-14.155129855222071,0 -15.727922061357857,5.242640687119286 0,0 -15.727922061357857,-5.242640687119286" fill="#000000" transform="translate(205.35265613005834 0) rotate(0)" stroke="none"/></g><g transform="translate(419.87902661354957 -94.70486750525603) rotate(21.654233935053426) translate(0 -13)"><g transform="translate(0 0)"><g transform="translate(-56.55859375 0)" fill="#ffffff" stroke="#000000" stroke-width="0"><rect x="0" y="0" width="113.1171875" height="26" rx="5" ry="5" stroke="none"/><text xml:space="preserve" x="5" y="17.45703125" stroke="none" text-anchor="left" font-family="sans-serif" font-size="16" font-weight="normal" fill="#000000">WORKS_FOR</text></g></g></g></g><g class="relationship"><g transform="translate(303.6087812804981 98.53347489845157) rotate(-30.000000000000025)" stroke-width="2" stroke="#000000"><path d="M 59 0 L 210.550934891181 0"/><polygon points="-14.155129855222071,0 -15.727922061357857,5.242640687119286 0,0 -15.727922061357857,-5.242640687119286" fill="#000000" transform="translate(224.70606474640306 0) rotate(0)" stroke="none"/></g><g transform="translate(420.32775989530205 31.145741175656283) rotate(-30.000000000000025) translate(0 -13)"><g transform="translate(0 0)"><g transform="translate(-56.55859375 0)" fill="#ffffff" stroke="#000000" stroke-width="0"><rect x="0" y="0" width="113.1171875" height="26" rx="5" ry="5" stroke="none"/><text xml:space="preserve" x="5" y="17.45703125" stroke="none" text-anchor="left" font-family="sans-serif" font-size="16" font-weight="normal" fill="#000000">WORKS_FOR</text></g></g></g></g><g class="relationship"><g transform="translate(549.3054405585958 -43.31955747475005) rotate(0)" stroke-width="2" stroke="#000000"><path d="M 59 0 L 227.3828188106305 0"/><polygon points="-14.155129855222071,0 -15.727922061357857,5.242640687119286 0,0 -15.727922061357857,-5.242640687119286" fill="#000000" transform="translate(241.53794866585258 0) rotate(0)" stroke="none"/></g><g transform="translate(692.496849963911 -43.31955747475005) rotate(0) translate(0 -13)"><g transform="translate(0 0)"><g transform="translate(-56.55859375 0)" fill="#ffffff" stroke="#000000" stroke-width="0"><rect x="0" y="0" width="113.1171875" height="26" rx="5" ry="5" stroke="none"/><text xml:space="preserve" x="5" y="17.45703125" stroke="none" text-anchor="left" font-family="sans-serif" font-size="16" font-weight="normal" fill="#000000">WORKS_FOR</text></g></g></g></g><g class="relationship"><g transform="translate(549.3054405585958 98.53347489845157) rotate(-25.26717339351291)" stroke-width="2" stroke="#000000"><path d="M 59 0 L 259.1780484188576 0"/><polygon points="-14.155129855222071,0 -15.727922061357857,5.242640687119286 0,0 -15.727922061357857,-5.242640687119286" fill="#000000" transform="translate(273.33317827407967 0) rotate(0)" stroke="none"/></g><g transform="translate(693.173980075052 30.62794521706168) rotate(-25.26717339351291) translate(0 -13)"><g transform="translate(0 0)"><g transform="translate(-56.55859375 0)" fill="#ffffff" stroke="#000000" stroke-width="0"><rect x="0" y="0" width="113.1171875" height="26" rx="5" ry="5" stroke="none"/><text xml:space="preserve" x="5" y="17.45703125" stroke="none" text-anchor="left" font-family="sans-serif" font-size="16" font-weight="normal" fill="#000000">WORKS_FOR</text></g></g></g></g><g class="relationship"><g transform="translate(849.8433892244484 -43.31955747475005) rotate(-6.773038164307976e-15)" stroke-width="2" stroke="#000000"><path d="M 59 0 L 227.3828188106305 0"/><polygon points="-14.155129855222071,0 -15.727922061357857,5.242640687119286 0,0 -15.727922061357857,-5.242640687119286" fill="#000000" transform="translate(241.53794866585258 0) rotate(0)" stroke="none"/></g><g transform="translate(993.0347986297636 -43.31955747475006) rotate(-6.773038164307976e-15) translate(0 -13)"><g transform="translate(0 0)"><g transform="translate(-56.55859375 0)" fill="#ffffff" stroke="#000000" stroke-width="0"><rect x="0" y="0" width="113.1171875" height="26" rx="5" ry="5" stroke="none"/><text xml:space="preserve" x="5" y="17.45703125" stroke="none" text-anchor="left" font-family="sans-serif" font-size="16" font-weight="normal" fill="#000000">WORKS_FOR</text></g></g></g></g><g class="node"><g fill="#ffffff" stroke="#006FD6" stroke-width="4"><circle cx="549.3054405585958" cy="-43.31955747475005" r="52"/></g><g transform="translate(549.3054405585958 -43.31955747475005)"><g transform="scale(0.5592606884691831) translate(0 -30.5)"><g transform="translate(0 0)"><g transform="translate(-74.458740234375 0)"><g fill="#000000" stroke="#000000" stroke-width="4" font-family="sans-serif" font-size="47" font-weight="normal"><text xml:space="preserve" x="0" y="43.592529296875" stroke="none">Person</text></g></g></g></g><g transform="translate(3.429011037612589e-15 -123.2)"><g transform="translate(0 0)"><g transform="translate(-79.32080078125 0)" fill="white"><rect x="0" y="0" width="158.6416015625" height="67.2" rx="0" ry="0" stroke="none"/><g font-family="sans-serif" font-size="14" font-weight="normal" fill="#535B66" text-anchor="end"><text xml:space="preserve" x="42.7998046875" y="12.29990234375" stroke="none">name:</text><text xml:space="preserve" x="46.689453125" y="12.29990234375" stroke="none" text-anchor="start">'Alice'</text><text xml:space="preserve" x="42.7998046875" y="29.099902343750003" stroke="none" text-anchor="end">age:</text><text xml:space="preserve" x="46.689453125" y="29.099902343750003" stroke="none" text-anchor="start">65</text><text xml:space="preserve" x="42.7998046875" y="45.89990234375" stroke="none" text-anchor="end">role:</text><text xml:space="preserve" x="46.689453125" y="45.89990234375" stroke="none" text-anchor="start">'Project manager'</text><text xml:space="preserve" x="42.7998046875" y="62.699902343750004" stroke="none" text-anchor="end">skills:</text><text xml:space="preserve" x="46.689453125" y="62.699902343750004" stroke="none" text-anchor="start">['Java', 'Python']</text></g></g></g></g></g></g><g class="node"><g fill="#ffffff" stroke="#006FD6" stroke-width="4"><circle cx="303.6087812804981" cy="-140.86687123888817" r="52"/></g><g transform="translate(303.6087812804981 -140.86687123888817)"><g transform="scale(0.5592606884691831) translate(0 -30.5)"><g transform="translate(0 0)"><g transform="translate(-74.458740234375 0)"><g fill="#000000" stroke="#000000" stroke-width="4" font-family="sans-serif" font-size="47" font-weight="normal"><text xml:space="preserve" x="0" y="43.592529296875" stroke="none">Person</text></g></g></g></g><g transform="translate(3.429011037612589e-15 56)"><g transform="translate(0 0)"><g transform="translate(-88.27587890625 0)" fill="white"><rect x="0" y="0" width="176.5517578125" height="67.2" rx="0" ry="0" stroke="none"/><g font-family="sans-serif" font-size="14" font-weight="normal" fill="#535B66" text-anchor="end"><text xml:space="preserve" x="42.7998046875" y="12.29990234375" stroke="none">name:</text><text xml:space="preserve" x="46.689453125" y="12.29990234375" stroke="none" text-anchor="start">'Cecil'</text><text xml:space="preserve" x="42.7998046875" y="29.099902343750003" stroke="none" text-anchor="end">age:</text><text xml:space="preserve" x="46.689453125" y="29.099902343750003" stroke="none" text-anchor="start">25</text><text xml:space="preserve" x="42.7998046875" y="45.89990234375" stroke="none" text-anchor="end">role:</text><text xml:space="preserve" x="46.689453125" y="45.89990234375" stroke="none" text-anchor="start">'Software developer'</text><text xml:space="preserve" x="42.7998046875" y="62.699902343750004" stroke="none" text-anchor="end">skills:</text><text xml:space="preserve" x="46.689453125" y="62.699902343750004" stroke="none" text-anchor="start">['Java', 'Python']</text></g></g></g></g></g></g><g class="node"><g fill="#ffffff" stroke="#006FD6" stroke-width="4"><circle cx="303.6087812804981" cy="98.53347489845157" r="52"/></g><g transform="translate(303.6087812804981 98.53347489845157)"><g transform="scale(0.5592606884691831) translate(0 -30.5)"><g transform="translate(0 0)"><g transform="translate(-74.458740234375 0)"><g fill="#000000" stroke="#000000" stroke-width="4" font-family="sans-serif" font-size="47" font-weight="normal"><text xml:space="preserve" x="0" y="43.592529296875" stroke="none">Person</text></g></g></g></g><g transform="translate(3.429011037612589e-15 56)"><g transform="translate(0 0)"><g transform="translate(-104.166015625 0)" fill="white"><rect x="0" y="0" width="208.33203125" height="67.2" rx="0" ry="0" stroke="none"/><g font-family="sans-serif" font-size="14" font-weight="normal" fill="#535B66" text-anchor="end"><text xml:space="preserve" x="42.7998046875" y="12.29990234375" stroke="none">name:</text><text xml:space="preserve" x="46.689453125" y="12.29990234375" stroke="none" text-anchor="start">'Cecilia'</text><text xml:space="preserve" x="42.7998046875" y="29.099902343750003" stroke="none" text-anchor="end">age:</text><text xml:space="preserve" x="46.689453125" y="29.099902343750003" stroke="none" text-anchor="start">31</text><text xml:space="preserve" x="42.7998046875" y="45.89990234375" stroke="none" text-anchor="end">role:</text><text xml:space="preserve" x="46.689453125" y="45.89990234375" stroke="none" text-anchor="start">'Software developer'</text><text xml:space="preserve" x="42.7998046875" y="62.699902343750004" stroke="none" text-anchor="end">skills:</text><text xml:space="preserve" x="46.689453125" y="62.699902343750004" stroke="none" text-anchor="start">['JavaScript', 'TypeScript']</text></g></g></g></g></g></g><g class="node"><g fill="#ffffff" stroke="#006FD6" stroke-width="4"><circle cx="549.3054405585958" cy="98.53347489845157" r="52"/></g><g transform="translate(549.3054405585958 98.53347489845157)"><g transform="scale(0.5592606884691831) translate(0 -30.5)"><g transform="translate(0 0)"><g transform="translate(-74.458740234375 0)"><g fill="#000000" stroke="#000000" stroke-width="4" font-family="sans-serif" font-size="47" font-weight="normal"><text xml:space="preserve" x="0" y="43.592529296875" stroke="none">Person</text></g></g></g></g><g transform="translate(3.429011037612589e-15 56)"><g transform="translate(0 0)"><g transform="translate(-82.43798828125 0)" fill="white"><rect x="0" y="0" width="164.8759765625" height="67.2" rx="0" ry="0" stroke="none"/><g font-family="sans-serif" font-size="14" font-weight="normal" fill="#535B66" text-anchor="end"><text xml:space="preserve" x="42.7998046875" y="12.29990234375" stroke="none">name:</text><text xml:space="preserve" x="46.689453125" y="12.29990234375" stroke="none" text-anchor="start">'Charlie'</text><text xml:space="preserve" x="42.7998046875" y="29.099902343750003" stroke="none" text-anchor="end">age:</text><text xml:space="preserve" x="46.689453125" y="29.099902343750003" stroke="none" text-anchor="start">61</text><text xml:space="preserve" x="42.7998046875" y="45.89990234375" stroke="none" text-anchor="end">role:</text><text xml:space="preserve" x="46.689453125" y="45.89990234375" stroke="none" text-anchor="start">'Security engineer'</text><text xml:space="preserve" x="42.7998046875" y="62.699902343750004" stroke="none" text-anchor="end">skills:</text><text xml:space="preserve" x="46.689453125" y="62.699902343750004" stroke="none" text-anchor="start">['C++', 'Python']</text></g></g></g></g></g></g><g class="node"><g fill="#ffffff" stroke="#006FD6" stroke-width="4"><circle cx="849.8433892244484" cy="-43.31955747475005" r="52"/></g><g transform="translate(849.8433892244484 -43.31955747475005)"><g transform="scale(0.5592606884691831) translate(0 -30.5)"><g transform="translate(0 0)"><g transform="translate(-74.458740234375 0)"><g fill="#000000" stroke="#000000" stroke-width="4" font-family="sans-serif" font-size="47" font-weight="normal"><text xml:space="preserve" x="0" y="43.592529296875" stroke="none">Person</text></g></g></g></g><g transform="translate(3.429011037612589e-15 56)"><g transform="translate(0 0)"><g transform="translate(-64.09375 0)" fill="white"><rect x="0" y="0" width="128.1875" height="67.2" rx="0" ry="0" stroke="none"/><g font-family="sans-serif" font-size="14" font-weight="normal" fill="#535B66" text-anchor="end"><text xml:space="preserve" x="42.7998046875" y="12.29990234375" stroke="none">name:</text><text xml:space="preserve" x="46.689453125" y="12.29990234375" stroke="none" text-anchor="start">'Daniel'</text><text xml:space="preserve" x="42.7998046875" y="29.099902343750003" stroke="none" text-anchor="end">age:</text><text xml:space="preserve" x="46.689453125" y="29.099902343750003" stroke="none" text-anchor="start">39</text><text xml:space="preserve" x="42.7998046875" y="45.89990234375" stroke="none" text-anchor="end">role:</text><text xml:space="preserve" x="46.689453125" y="45.89990234375" stroke="none" text-anchor="start">'Director'</text><text xml:space="preserve" x="42.7998046875" y="62.699902343750004" stroke="none" text-anchor="end">skills:</text><text xml:space="preserve" x="46.689453125" y="62.699902343750004" stroke="none" text-anchor="start">['Ruby', 'Go']</text></g></g></g></g></g></g><g class="node"><g fill="#ffffff" stroke="#006FD6" stroke-width="4"><circle cx="1150.381337890301" cy="-43.319557474750084" r="52"/></g><g transform="translate(1150.381337890301 -43.319557474750084)"><g transform="scale(0.5592606884691831) translate(0 -30.5)"><g transform="translate(0 0)"><g transform="translate(-74.458740234375 0)"><g fill="#000000" stroke="#000000" stroke-width="4" font-family="sans-serif" font-size="47" font-weight="normal"><text xml:space="preserve" x="0" y="43.592529296875" stroke="none">Person</text></g></g></g></g><g transform="translate(3.429011037612589e-15 56)"><g transform="translate(0 0)"><g transform="translate(-94.787109375 0)" fill="white"><rect x="0" y="0" width="189.57421875" height="67.2" rx="0" ry="0" stroke="none"/><g font-family="sans-serif" font-size="14" font-weight="normal" fill="#535B66" text-anchor="end"><text xml:space="preserve" x="42.7998046875" y="12.29990234375" stroke="none">name:</text><text xml:space="preserve" x="46.689453125" y="12.29990234375" stroke="none" text-anchor="start">'Eskil'</text><text xml:space="preserve" x="42.7998046875" y="29.099902343750003" stroke="none" text-anchor="end">age:</text><text xml:space="preserve" x="46.689453125" y="29.099902343750003" stroke="none" text-anchor="start">39</text><text xml:space="preserve" x="42.7998046875" y="45.89990234375" stroke="none" text-anchor="end">role:</text><text xml:space="preserve" x="46.689453125" y="45.89990234375" stroke="none" text-anchor="start">'CEO'</text><text xml:space="preserve" x="42.7998046875" y="62.699902343750004" stroke="none" text-anchor="end">skills:</text><text xml:space="preserve" x="46.689453125" y="62.699902343750004" stroke="none" text-anchor="start">['Java', 'C++', 'Python']</text></g></g></g></g></g></g></g></svg>
\ No newline at end of file
diff --git a/modules/ROOT/pages/expressions/list-expressions.adoc b/modules/ROOT/pages/expressions/list-expressions.adoc
index b9d7494c3..4f81d848d 100644
--- a/modules/ROOT/pages/expressions/list-expressions.adoc
+++ b/modules/ROOT/pages/expressions/list-expressions.adoc
@@ -3,13 +3,19 @@
 :table-caption!:
 
 List expressions are a way to manipulate and query xref:values-and-types/lists.adoc[`LIST`] values in Cypher.
-They allow for operations like concatenation, element access, slicing, and transformations using comprehensions. 
 
 For more expressions that evaluate to a `LIST` value, see xref:functions/list.adoc[List functions]. +
 For information about how to check membership in a `LIST` using the `IN` operator, see xref:expressions/predicates/list-operators.adoc[Predicates -> List operators].
 
+[[example-graph]]
 == Example graph
 
+The following graph is used for the examples below:
+
+image::list_expressions_graph.svg[width="700",role="middle"]
+
+To recreate the graph, run the following query against an empty Neo4j database:
+
 [source, cypher]
 ----
 CREATE (alice:Person {name:'Alice', age: 65, role: 'Project manager', skills: ['Java', 'Python']}),
@@ -17,15 +23,16 @@ CREATE (alice:Person {name:'Alice', age: 65, role: 'Project manager', skills: ['
        (cecilia:Person {name: 'Cecilia', age: 31, role: 'Software developer', skills: ['JavaScript', 'TypeScript']}),  
        (charlie:Person {name: 'Charlie', age: 61, role: 'Security engineer', skills: ['C++', 'Python']}),
        (daniel:Person {name: 'Daniel', age: 39, role: 'Director', skills: ['Ruby', 'Go']}),  
-       (eskil:Person {name: 'Eskil', age: 39, role: 'CEO'}),  
+       (eskil:Person {name: 'Eskil', age: 39, role: 'CEO', skills: ['Java', 'C++', 'Python']}),  
 
-       (alice)-[:WORKS_FOR]->(daniel),
        (cecil)-[:WORKS_FOR]->(alice),
        (cecilia)-[:WORKS_FOR]->(alice),
        (charlie)-[:WORKS_FOR]->(daniel),
+       (alice)-[:WORKS_FOR]->(daniel),
        (daniel)-[:WORKS_FOR]->(eskil)
 ----
 
+[[list-concatenation]]
 == List concatenation
 
 Cypher contains two list concatenation operators: `||` and `+`.
@@ -65,10 +72,29 @@ RETURN cecil.skills || cecilia.skills AS combinedSkills
 1+d|Rows: 1
 |===
 
-The `+` operator can add elements to the beginning of a `LIST` value.
+The `+` operator can add elements to the beginning or end of a `LIST` value.
 This is not possible using the `||` operator.
 
-.Adding elements to the beginning of a `LIST` with `+`
+.Adding elements to the beginning of a `LIST`
+[source, cypher]
+----
+WITH [1, 2, 3, 4] AS list
+RETURN 0 + list AS newBeginning,
+       list + 5 AS newEnd
+----
+
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| newBeginning | newEnd
+
+| [0, 1, 2, 3, 4] | [1, 2, 3, 4, 5] 
+
+2+d|Rows: 1
+|===
+
+.Adding elements to the beginning of a `LIST` property `+`
 [source, cypher]
 ----
 MATCH (cecil:Person {name: 'Cecil'})
@@ -104,6 +130,9 @@ RETURN [1, 2] || [3, null] AS listWithNull
 1+d|Rows: 1
 |===
 
+For removing `NULL` values when concatenating `LIST` values, see xref:expressions/list-expressions.adoc#null-list-concatenation-list-comprehension[`NULL`, list concatenation, and list comprehension].
+
+[[list-element-access]]
 == List element access
 
 The subscript operator, `[]`, can be used to access specific elements in a `LIST`.
@@ -156,6 +185,23 @@ RETURN list[$myIndex] AS secondElement
 1+d|Rows: 1
 |===
 
+.Accessing a `LIST` within a nested `LIST`
+[source, cypher]
+----
+WITH [[1, 2], [3, 4], [5, 6]] AS nestedList
+RETURN nestedList[1] AS secondList
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| secondList
+
+| [3, 4]
+
+1+d|Rows: 1
+|===
+
 The xref:expressions/predicates/list-operators.adoc[`IN`] operator, which checks for `LIST` membership, can be used together with `[]` to test whether an element exists in a nested `LIST`.
 
 .Checking for membership in nested `LIST`
@@ -194,26 +240,300 @@ RETURN list[5] AS outOfBound, emptyList[0] AS emptyAccess
 2+d|Rows: 1
 |===
 
+[[list-slicing]]
+== List slicing
+
+`LIST` values can be sliced if a range is provided within the subscript operator.
+The bounds of the range are separated using two dots (`..`).
+This allows for extracting a subset of a `LIST` rather than a single element.
+List slicing is inclusive at the start of the range, but exclusive at the end (e.g. `list[start..end]` includes `start`, but excludes `end`).
+
+.Slice operations on a `LIST`
+[source, cypher]
+----
+WITH [1, 2, 3, 4, 5, 6] AS list
+RETURN list[2..4] AS middleElements,
+       list[..2] AS noLowerBound,
+       list[2..] AS noUpperBound
+----
 
+.Result
+[role="queryresult",options="header,footer",cols="3*<m"]
+|===
+| middleElements | noLowerBound | noUpperBound
 
-=== NULL and LIST comprehension
+| [3, 4] | [1, 2] | [3, 4, 5, 6]
 
+3+d|Rows: 1
+|===
+
+When slicing nested `LIST` values, it is important to specify which level is sliced.
+The below example slices the outer `LIST` and returns the first two nested `LIST` values.
+
+.Slice outer `LIST`
+[source, cypher]
+----
+WITH [[1, 2, 3], [4, 5, 6], [7, 8, 9]] AS nestedList
+RETURN nestedList[0..2] AS slicedNestedList
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| slicedNestedList
+
+| [[1, 2, 3], [4, 5, 6]]
+
+1+d|Rows: 1
+|===
+
+Slicing inner `LIST` values require two `[]` operators; the first `[]` accesses elements from the outer `LIST`, while the second slices or accesses elements from the inner `LIST`.
+
+.Slice inner `LIST`
+[source, cypher]
+----
+WITH [[1, 2, 3], [4, 5, 6], [7, 8, 9]] AS nestedList
+RETURN nestedList[1][0..2] AS slicedInnerList
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| slicedInnerList
+
+| [4, 5]
+
+1+d|Rows: 1
+|===
+
+Accessing specific elements or a range of elements can also be used in combination with the `+` operator to create a new `LIST` with values inserted into specific sections of an existing `LIST` value.
+
+.Inserting elements into specific positions of a `LIST`
+[source, cypher]
+----
+WITH [1, 3, 4] AS list
+RETURN list[0] + [2] + list[1..] AS newList
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| newList
+
+| [1, 2, 3, 4]
+
+1+d|Rows: 1
+|===
+
+[[list-comprehension]]
+== List comprehension
+
+List comprehension is used to create new `LIST` values by iterating over existing `LIST` values and transforming the elements based on certain conditions or operations.
+
+.Syntax
+[source, syntax]
+----
+[item IN list [WHERE predicate] | [expression]]
+----
+
+The iteration step (`item IN list`) ensures that each element of a `list` is accessed one by one, while the `expression` optionally applies a transformation to each `item`, creating new `LIST` values containing the modified elements.
+
+.List comprehension without an expression
+[source, cypher]
+----
+RETURN [x IN range(0,10) WHERE x % 2 = 0] AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
+
+| [0, 2, 4, 6, 8, 10] 
+
+1+d|Rows: 1
+|===
+
+.List comprehension without filtering
+[source, cypher]
+----
+RETURN [x IN range(0,5) | x * 10] AS result
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| result
 
+| [0, 10, 20, 30, 40, 50]
 
-If you want to remove all null values from the concatenated lists, you can use a list comprehension to filter them out. This way, you're not even concerned with their positions, and it's much cleaner and easier.
+1+d|Rows: 1
+|===
+
+
+.List comprehension with both an expression and filtering
+[source, cypher]
+----
+WITH [1, 2, 3, 4, 5] AS list
+RETURN [n IN list WHERE n > 2 | n] AS filteredList
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| filteredList
+
+| [3, 4, 5]
+
+1+d|Rows: 1
+|===
+
+This below query iterates over the `skills` property of each Person node and creates a new `LIST` by xref:expressions/string-operators.adoc[concatenating the `STRING`] `" expert"` to each element in `skills`.
+
+.Modify `LIST` properties
+[source, cypher]
+----
+MATCH (p:Person) WHERE p.skills IS NOT NULL
+ORDER BY p.name
+RETURN p.name AS name,
+      [skill IN p.skills | skill + " expert"] AS modifiedSkills
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| name | modifiedSkills
+
+| "Alice"   | ["Java expert", "Python expert"]
+| "Cecil"   | ["Cypher expert", "Java expert", "Python expert"]
+| "Cecilia" | ["JavaScript expert", "TypeScript expert"]
+| "Charlie" | ["C++ expert", "Python expert"]
+| "Daniel"  | ["Ruby expert", "Go expert"]
+| "Eskil"   | ["Java expert", "C++ expert", "Python expert"]
+
+2+d|Rows: 6
+|===
+
+The next query uses the xref:functions/aggregating.adoc#functions-collect[`collect()`] function to gather all `Person` nodes into a `LIST`, and the `WHERE 'Python' IN person.skills` predicate filters that list to include only those nodes whose `skills` property contains `Python`.
+
+.List comprehension with a `WHERE` predicate
+[source, cypher]
+----
+MATCH (p:Person)
+RETURN [person IN collect(p) WHERE 'Python' IN person.skills | person.name] AS pythonExperts
+----
+
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| pythonExperts
+
+| ["Alice", "Cecil", "Charlie", "Eskil"]
+
+1+d|Rows: 1
+|===
+
+
+List comprehension can be used to remove any unknown `NULL` values when concatenating `LIST` values.
+
+.Use a list comprehension to remove `NULL` values during list concatenation
+[source, cypher]
+----
+RETURN [x IN ([1, null, 3] || [null, 5, null]) WHERE x IS NOT NULL] AS listWithoutNull
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| listWithoutNull
+
+| [1, 3, 5]
+
+1+d|Rows: 1
+|===
+
+[[pattern-comprehension]]
+== Pattern comprehension
+
+Pattern comprehension is used to create new `LIST` values by matching graph patterns and applying conditions to the matched elements, returning custom projections.
+
+.Syntax
+[source, syntax]
+----
+[pattern [WHERE predicate] | expression]
+----
+
+The below query retrieves a list of names of people who work for `Alice` by using pattern comprehension extract the names of `employees` into a `LIST`.
+
+.Pattern comprehension on a fixed-length relationship
+[source, cypher]
+----
+MATCH (alice:Person {name: 'Alice'})
+RETURN [(alice)<-[:WORKS_FOR]-(employee) | employee.name] AS employees
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| employees
+
+| ["Cecil", "Cecilia"]
+
+1+d|Rows: 1
+|===
+
+Pattern comprehensions can include `WHERE` predicates.
+
+
+.Pattern comprehension including a `WHERE` predicate
+[source, cypher]
+----
+MATCH (alice:Person {name: 'Alice'})
+RETURN [(alice)<-[:WORKS_FOR]-(employee:Person) WHERE employee.age > 30 | employee.name || ', ' || toString(employee.age)] AS employeesAbove30
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| employeesAbove30
+
+| ["Cecilia, 31"]
+
+1+d|Rows: 1
+|===
+
+Pattern comprehension can also match for xref:patterns/variable-length-patterns.adoc[variable-length patterns].
+However, pattern comprehension does not support the xref:patterns/reference.adoc#quantifiers[GQL conformant quantifier syntax].
+
+.Not allowed - pattern comprehension to match patterns of a variable length using GQL quantifier syntax
+[source, cypher, role=test-fail]
+----
+MATCH (cecil:Person {name: 'Cecil'})
+RETURN [(cecil)-[:WORKS_FOR]->+(superior:Person) | superior.skills] AS superiorsSkills
+----
+
+Pattern comprehension only supports only the xref:patterns/reference.adoc#variable-length-relationships[variable-length relationships] syntax.
+The belowquery uses a pattern comprehension to collect the skills of all superiors in the chain above `Cecil`.
+The xref:functions/list.adoc#functions-reduce[`reduce()`] function concatenates these skills into a single `LIST`, and xref:clauses/unwind.adoc[`UNWIND`] is used to flatten this `LIST` before returning the distinct skills in a new `LIST`.
+
+.Allowed - pattern comprehension to match patterns of a variable length using variable-length relationship syntax
+[source, cypher]
+----
+MATCH (cecil:Person {name: 'Cecil'})
+WITH [(cecil)-[:WORKS_FOR*]->(superior:Person) | superior.skills] AS allSuperiorsSkills
+WITH reduce(accumulatedSkills = [], superiorSkills IN allSuperiorsSkills | accumulatedSkills || superiorSkills) AS allSkills
+UNWIND allSkills AS superiorsSkills
+RETURN collect(DISTINCT superiorsSkills) AS distinctSuperiorsSkills
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| distinctSuperiorsSkills
+
+| ["Java", "Python", "Ruby", "Go", "C++"]
+
+1+d|Rows: 1
+|===
 
-Example:
-cypher
-Copy
-Edit
-RETURN [1, null, 3] || [null, 5, null] AS combinedList,
-       [x IN ([1, null, 3] || [null, 5, null]) WHERE x IS NOT NULL] AS filteredList;
-Result:
-sql
-Copy
-Edit
-+---------------------------------------------+
-| combinedList           | filteredList      |
-+---------------------------------------------+
-| [1, NULL, 3, NULL, 5, NULL] | [1, 3, 5]        |
-+---------------------------------------------+
diff --git a/modules/ROOT/pages/values-and-types/lists.adoc b/modules/ROOT/pages/values-and-types/lists.adoc
index 0a94f3b38..449ccce30 100644
--- a/modules/ROOT/pages/values-and-types/lists.adoc
+++ b/modules/ROOT/pages/values-and-types/lists.adoc
@@ -8,11 +8,8 @@ Cypher includes comprehensive support for lists.
 This section first describes lists in general, and then discusses how to use list comprehension and pattern comprehension in lists.
 
 [NOTE]
-====
-Information regarding operators, such as list concatenation (`+`), element existence checking (`IN`), and access (`[]`) can be found xref::syntax/operators.adoc#query-operators-list[here].
-The behavior of the `IN` and `[]` operators with respect to `null` is detailed xref::values-and-types/working-with-null.adoc[here].
-====
-
+For information about the list predicate operator `IN`, which checks for list membership, see xref:expressions/predicates/list-operators.adoc[Expressions -> Predicates -> List operators].
+For information list concatenation (`+` and `||`), list element access and slicing (`[]`), as well as list and pattern comprehensions, see xref:expressions/list-expressions.adoc[List expressions].
 
 [[cypher-lists-general]]
 == Lists in general
@@ -70,7 +67,7 @@ RETURN list[2]
 1+d|Rows: 1
 |===
 
-=== List range and size
+== List range and size
 
 The below examples use the xref::functions/list.adoc#functions-range[`range`] function to create lists.
 This function returns a list containing all numbers between given start and end numbers.
@@ -212,169 +209,40 @@ RETURN size(range(0, 10)[0..3]) AS list
 |===
 
 
-[[cypher-pattern-comprehension]]
-== Pattern comprehension
-
-Pattern comprehension is a syntactic construct available in Cypher for creating a list based on matchings of a pattern.
-A pattern comprehension matches the specified pattern like a normal `MATCH` clause, with predicates like a normal `WHERE` clause, but yields a custom projection as specified.
-
-=== Example graph
-
-The following graph is used for examples below:
-
-image::values_and_types_lists_graph.svg[]
-
-To recreate the graph, run the following query against an empty Neo4j database:
-
-[source, cypher, role=test-setup]
-----
-CREATE
-  (keanu:Person {name: 'Keanu Reeves'}),
-  (johnnyMnemonic:Movie {title: 'Johnny Mnemonic', released: 1995}),
-  (theMatrixRevolutions:Movie {title: 'The Matrix Revolutions', released: 2003}),
-  (theMatrixReloaded:Movie {title: 'The Matrix Reloaded', released: 2003}),
-  (theReplacements:Movie {title: 'The Replacements', released: 2000}),
-  (theMatrix:Movie {title: 'The Matrix', released: 1999}),
-  (theDevilsAdvocate:Movie {title: 'The Devils Advocate', released: 1997}),
-  (theMatrixResurrections:Movie {title: 'The Matrix Resurrections', released: 2021}),
-  (keanu)-[:ACTED_IN]->(johnnyMnemonic),
-  (keanu)-[:ACTED_IN]->(theMatrixRevolutions),
-  (keanu)-[:ACTED_IN]->(theMatrixReloaded),
-  (keanu)-[:ACTED_IN]->(theReplacements),
-  (keanu)-[:ACTED_IN]->(theMatrix),
-  (keanu)-[:ACTED_IN]->(theDevilsAdvocate),
-  (keanu)-[:ACTED_IN]->(theMatrixResurrections)
-----
-
-=== Examples
+== Storing lists as properties
 
-This example returns a list that contains the year when the movies were released.
-The pattern matching in the pattern comprehension looks for `Matrix` in the movie title and that the node `keanu` (`Person` node with the name `Keanu Reeves`) has a relationship with the movie.
+It is possible to store homogenous lists of simple values as properties.
 
-.Query
+.Allowed - store homogenous list as a property
 [source, cypher]
 ----
-MATCH (keanu:Person {name: 'Keanu Reeves'})
-RETURN [(keanu)-->(b:Movie) WHERE b.title CONTAINS 'Matrix' | b.released] AS years
+CREATE (n:Label)
+SET n.listProperty = [1, 2, 3]
+RETURN n.listProperty AS homogenousListProperty
 ----
 
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
 |===
-| +years+
-| +[2021,2003,2003,1999]+
-1+d|Rows: 1
-|===
-
-The whole predicate, including the `WHERE` keyword, is optional and may be omitted.
+| homogenousListProperty
 
-==== Storing lists as properties
+| [1, 2, 3]
 
-It is possible to store homogenous lists of simple values as properties.
-For example, the following query creates a list from the `title` properties of the `Movie` nodes connected to `Keanu Reeves`.
-It then sets that list as a `resume` property on `Keanu Reeves`.
-
-.Query
-[source, cypher]
-----
-MATCH (keanu:Person {name: 'Keanu Reeves'})
-WITH keanu,[(keanu)-->(b:Movie) | b.title] AS movieTitles
-SET keanu.resume = movieTitles
-RETURN keanu.resume
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +keanu.resume+
-| +["The Matrix Resurrections", "The Devils Advocate", "The Matrix", "The Replacements", "The Matrix Reloaded", "The Matrix Revolutions", "Johnny Mnemonic"]+
 1+d|Rows: 1
 |===
 
 It is not, however, possible to store heterogeneous lists as properties.
-For example, the following query, which tries to set a list including both the `title` and the `released` properties as the `resume` property of `Keanu Reeves` will fail.
-This is because the `title` property values are stored as `STRING` values, while the `released` property values are stored as `INTEGER` values.
 
-.Query
-[source, cypher, role=test-fail]
+.Not allowed - store heterogenous list as a property
+[source, cypher]
 ----
-MATCH (keanu:Person {name: 'Keanu Reeves'})
-WITH keanu,[(keanu)-->(b:Movie) | b.title]  + [(keanu)-->(b:Movie) | b.released] AS movieTitles
-SET keanu.resume = movieTitles
-RETURN keanu.resume
+CREATE (n:Label)
+SET n.listProperty = [1, "hello", .45, date()]
+RETURN n.listProperty AS heterogenousListProperty
 ----
 
+.Error
 [source,error]
 ----
 Neo4j only supports a subset of Cypher types for storage as singleton or array properties. Please refer to section cypher/syntax/values of the manual for more details.
 ----
-
-
-[[cypher-list-comprehension]]
-== List comprehension
-
-List comprehension is a syntactic construct available in Cypher for creating a list based on existing lists.
-
-For example, the following query returns a new list from the previously created `resume` property (a list of strings) of `Keanu Reeves`:
-
-.Query
-[source, cypher]
-----
-MATCH (keanu:Person {name:'Keanu Reeves'})
-RETURN [x IN keanu.resume WHERE x contains 'The Matrix'] AS matrixList
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +matrixList+
-| +["The Matrix Resurrections", "The Matrix", "The Matrix Reloaded", "The Matrix Revolutions"]+
-1+d|Rows: 1
-|===
-
-List comprehension follows the form of the mathematical set-builder notation (set comprehension) instead of the use of map and filter functions.
-
-.Query
-[source, cypher]
-----
-RETURN [x IN range(0,10) WHERE x % 2 = 0 | x^3 ] AS result
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +result+
-| +[0.0,8.0,64.0,216.0,512.0,1000.0]+
-1+d|Rows: 1
-|===
-
-Either the `WHERE` part, or the expression, can be omitted, if you only want to filter or map respectively.
-
-.Query
-[source, cypher]
-----
-RETURN [x IN range(0,10) WHERE x % 2 = 0 ] AS result
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +result+
-| +[0,2,4,6,8,10]+
-1+d|Rows: 1
-|===
-
-.Query
-[source, cypher]
-----
-RETURN [x IN range(0,10) | x^3 ] AS result
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| +result+
-| +[0.0,1.0,8.0,27.0,64.0,125.0,216.0,343.0,512.0,729.0,1000.0]+
-1+d|Rows: 1
-|===
-

From d0175fa312809daa9ec61526f12cdf225d3ffb40 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Mon, 31 Mar 2025 11:08:53 +0200
Subject: [PATCH 04/10] cleanup

---
 modules/ROOT/pages/syntax/operators.adoc       | 1 -
 modules/ROOT/pages/values-and-types/lists.adoc | 2 +-
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/modules/ROOT/pages/syntax/operators.adoc b/modules/ROOT/pages/syntax/operators.adoc
index 3a65403d5..3c4195f8e 100644
--- a/modules/ROOT/pages/syntax/operators.adoc
+++ b/modules/ROOT/pages/syntax/operators.adoc
@@ -12,7 +12,6 @@ This page contains an overview of the available Cypher operators.
 | xref::syntax/operators.adoc#query-operators-aggregation[Aggregation operators] | `DISTINCT`
 | xref::syntax/operators.adoc#query-operators-property[Property operators] | `.` for static property access, `[]` for dynamic property access, `=` for replacing all properties, `+=` for mutating specific properties
 | xref::syntax/operators.adoc#query-operators-map[Map operators]       |  `.` for static value access by key, `[]` for dynamic value access by key
-| xref::syntax/operators.adoc#query-operators-list[List operators]       | `+` and `\|\|` (list concatenation), `IN` to check existence of an element in a list, `[]` for accessing element(s) dynamically
 |===
 
 
diff --git a/modules/ROOT/pages/values-and-types/lists.adoc b/modules/ROOT/pages/values-and-types/lists.adoc
index 449ccce30..f57fc7a84 100644
--- a/modules/ROOT/pages/values-and-types/lists.adoc
+++ b/modules/ROOT/pages/values-and-types/lists.adoc
@@ -234,7 +234,7 @@ RETURN n.listProperty AS homogenousListProperty
 It is not, however, possible to store heterogeneous lists as properties.
 
 .Not allowed - store heterogenous list as a property
-[source, cypher]
+[source, cypher, role=test-fail]
 ----
 CREATE (n:Label)
 SET n.listProperty = [1, "hello", .45, date()]

From 35e14596010ee6681f102657b6eac5946064d103 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Mon, 31 Mar 2025 12:26:08 +0200
Subject: [PATCH 05/10] more cleanup

---
 .../pages/appendix/gql-conformance/additional-cypher.adoc  | 2 +-
 modules/ROOT/pages/expressions/list-expressions.adoc       | 7 +++----
 modules/ROOT/pages/functions/list.adoc                     | 6 +++++-
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc b/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc
index ae7fe27a0..1dabfe915 100644
--- a/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc
+++ b/modules/ROOT/pages/appendix/gql-conformance/additional-cypher.adoc
@@ -623,7 +623,7 @@ GQL supports `GRAPH TYPES` as a way of constraining a graph schema, but does not
 | xref:syntax/operators.adoc#query-operator-comparison-string-specific[`STARTS WITH`, `CONTAINS`, `ENDS WITH`, and regular expressions].
 | `STRING` comparison operators.
 
-| xref:syntax/operators.adoc#query-operators-list[`IN`]
+| xref:expressions/predicates/list-operators.adoc[`IN`]
 | `IN` predicate for `LIST` values.
 
 |===
diff --git a/modules/ROOT/pages/expressions/list-expressions.adoc b/modules/ROOT/pages/expressions/list-expressions.adoc
index 4f81d848d..cd32d824f 100644
--- a/modules/ROOT/pages/expressions/list-expressions.adoc
+++ b/modules/ROOT/pages/expressions/list-expressions.adoc
@@ -466,11 +466,11 @@ Pattern comprehension is used to create new `LIST` values by matching graph patt
 
 The below query retrieves a list of names of people who work for `Alice` by using pattern comprehension extract the names of `employees` into a `LIST`.
 
-.Pattern comprehension on a fixed-length relationship
+.Pattern comprehension on a fixed-length pattern
 [source, cypher]
 ----
 MATCH (alice:Person {name: 'Alice'})
-RETURN [(alice)<-[:WORKS_FOR]-(employee) | employee.name] AS employees
+RETURN [(employee:Person)-[:WORKS_FOR]->(alice) | employee.name] AS employees
 ----
 
 .Result
@@ -485,12 +485,11 @@ RETURN [(alice)<-[:WORKS_FOR]-(employee) | employee.name] AS employees
 
 Pattern comprehensions can include `WHERE` predicates.
 
-
 .Pattern comprehension including a `WHERE` predicate
 [source, cypher]
 ----
 MATCH (alice:Person {name: 'Alice'})
-RETURN [(alice)<-[:WORKS_FOR]-(employee:Person) WHERE employee.age > 30 | employee.name || ', ' || toString(employee.age)] AS employeesAbove30
+RETURN [(employee:Person)-[:WORKS_FOR]->(alice) WHERE employee.age > 30 | employee.name || ', ' || toString(employee.age)] AS employeesAbove30
 ----
 
 .Result
diff --git a/modules/ROOT/pages/functions/list.adoc b/modules/ROOT/pages/functions/list.adoc
index 86ca9a4a0..e908f844c 100644
--- a/modules/ROOT/pages/functions/list.adoc
+++ b/modules/ROOT/pages/functions/list.adoc
@@ -6,7 +6,11 @@
 
 List functions return lists of different data entities.
 
-Further details and examples of lists may be found in xref::values-and-types/lists.adoc[Lists] and xref::syntax/operators.adoc#query-operators-list[List operators].
+For more information about working with `LIST` values, see:
+
+* xref:values-and-types/lists.adoc[Values and types -> Lists]
+* xref:expressions/predicates/list-operators.adoc[Predicates -> List operators]
+* xref:expressions/list-expressions.adoc[List expressions]
 
 [[example-graph]]
 == Example graph

From 0d384f369d63e535589ddbe615551ea8d5a0e12b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Mon, 31 Mar 2025 12:35:11 +0200
Subject: [PATCH 06/10] a bit more cleanup

---
 .../pages/expressions/list-expressions.adoc   | 27 +++++++++----------
 1 file changed, 13 insertions(+), 14 deletions(-)

diff --git a/modules/ROOT/pages/expressions/list-expressions.adoc b/modules/ROOT/pages/expressions/list-expressions.adoc
index cd32d824f..a35abbfab 100644
--- a/modules/ROOT/pages/expressions/list-expressions.adoc
+++ b/modules/ROOT/pages/expressions/list-expressions.adoc
@@ -55,7 +55,7 @@ RETURN [1,2] || [3,4] AS list1,
 2+d|Rows: 1
 |===
 
-.Concatenating two `LIST` properties
+.Concatenate two `LIST` properties
 [source, cypher]
 ----
 MATCH (cecil:Person {name: 'Cecil'}), (cecilia:Person {name: 'Cecilia'})
@@ -75,7 +75,7 @@ RETURN cecil.skills || cecilia.skills AS combinedSkills
 The `+` operator can add elements to the beginning or end of a `LIST` value.
 This is not possible using the `||` operator.
 
-.Adding elements to the beginning of a `LIST`
+.Add elements to the beginning and end of a `LIST`
 [source, cypher]
 ----
 WITH [1, 2, 3, 4] AS list
@@ -94,7 +94,7 @@ RETURN 0 + list AS newBeginning,
 2+d|Rows: 1
 |===
 
-.Adding elements to the beginning of a `LIST` property `+`
+.Add elements to the beginning of a `LIST` property
 [source, cypher]
 ----
 MATCH (cecil:Person {name: 'Cecil'})
@@ -114,7 +114,7 @@ RETURN cecil.skills AS skillsList
 
 If `NULL` is part of a concatenated `LIST`, `NULL` will be a part of the new `LIST`.
 
-.Concatenating `LIST` including `NULL`
+.Concatenate `LIST` including `NULL`
 [source, cypher]
 ----
 RETURN [1, 2] || [3, null] AS listWithNull
@@ -139,7 +139,7 @@ The subscript operator, `[]`, can be used to access specific elements in a `LIST
 `[0]` refers to the first element in a `LIST`, `[1]` to the second, and so on.
 `[-1]` refers to the last element in a `LIST`, `[-2]` to the penultimate element, and so on.
 
-.Accessing individual elements in a `LIST`
+.Access individual elements in a `LIST`
 [source, cypher]
 ----
 WITH [1, 2, 3, 4] AS list
@@ -168,7 +168,7 @@ The index of the element in the `LIST` can be parameterized.
 }
 ----
 
-.Accessing `LIST` elements with a parameter
+.Access `LIST` elements with a parameter
 [source, cypher]
 ----
 WITH [1, 2, 3, 4] AS list
@@ -185,7 +185,7 @@ RETURN list[$myIndex] AS secondElement
 1+d|Rows: 1
 |===
 
-.Accessing a `LIST` within a nested `LIST`
+.Access a `LIST` within a nested `LIST`
 [source, cypher]
 ----
 WITH [[1, 2], [3, 4], [5, 6]] AS nestedList
@@ -204,7 +204,7 @@ RETURN nestedList[1] AS secondList
 
 The xref:expressions/predicates/list-operators.adoc[`IN`] operator, which checks for `LIST` membership, can be used together with `[]` to test whether an element exists in a nested `LIST`.
 
-.Checking for membership in nested `LIST`
+.Check for membership in a nested `LIST`
 [source, cypher]
 ----
 WITH [[1, 2, 3], [4, 5, 6]] AS nestedList
@@ -223,7 +223,7 @@ RETURN 3 IN nestedList[0] AS elementPresent
 
 Attempting to reference an element outside the bounds of the `LIST` will return `NULL`, as will attempting to access elements from an empty `LIST`.
 
-.Out-of-bounds and empty list access
+.Out-of-bounds and empty `LIST` access
 [source, cypher]
 ----
 WITH [1, 2, 3, 4] AS list, [] AS emptyList
@@ -308,7 +308,7 @@ RETURN nestedList[1][0..2] AS slicedInnerList
 
 Accessing specific elements or a range of elements can also be used in combination with the `+` operator to create a new `LIST` with values inserted into specific sections of an existing `LIST` value.
 
-.Inserting elements into specific positions of a `LIST`
+.Insert elements into specific positions of a `LIST`
 [source, cypher]
 ----
 WITH [1, 3, 4] AS list
@@ -390,7 +390,7 @@ RETURN [n IN list WHERE n > 2 | n] AS filteredList
 
 This below query iterates over the `skills` property of each Person node and creates a new `LIST` by xref:expressions/string-operators.adoc[concatenating the `STRING`] `" expert"` to each element in `skills`.
 
-.Modify `LIST` properties
+.Modify `LIST` properties using list comprehension
 [source, cypher]
 ----
 MATCH (p:Person) WHERE p.skills IS NOT NULL
@@ -434,10 +434,9 @@ RETURN [person IN collect(p) WHERE 'Python' IN person.skills | person.name] AS p
 1+d|Rows: 1
 |===
 
-
 List comprehension can be used to remove any unknown `NULL` values when concatenating `LIST` values.
 
-.Use a list comprehension to remove `NULL` values during list concatenation
+.List comprehension to remove `NULL` values during list concatenation
 [source, cypher]
 ----
 RETURN [x IN ([1, null, 3] || [null, 5, null]) WHERE x IS NOT NULL] AS listWithoutNull
@@ -513,7 +512,7 @@ RETURN [(cecil)-[:WORKS_FOR]->+(superior:Person) | superior.skills] AS superiors
 ----
 
 Pattern comprehension only supports only the xref:patterns/reference.adoc#variable-length-relationships[variable-length relationships] syntax.
-The belowquery uses a pattern comprehension to collect the skills of all superiors in the chain above `Cecil`.
+The below query uses a pattern comprehension to collect the skills of all superiors in the chain above `Cecil`.
 The xref:functions/list.adoc#functions-reduce[`reduce()`] function concatenates these skills into a single `LIST`, and xref:clauses/unwind.adoc[`UNWIND`] is used to flatten this `LIST` before returning the distinct skills in a new `LIST`.
 
 .Allowed - pattern comprehension to match patterns of a variable length using variable-length relationship syntax

From 0b1d7f1a60e56af8ee96335bfef1f19695a2b438 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Mon, 31 Mar 2025 12:44:42 +0200
Subject: [PATCH 07/10] rephrase

---
 modules/ROOT/pages/expressions/list-expressions.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/modules/ROOT/pages/expressions/list-expressions.adoc b/modules/ROOT/pages/expressions/list-expressions.adoc
index a35abbfab..c2c33686a 100644
--- a/modules/ROOT/pages/expressions/list-expressions.adoc
+++ b/modules/ROOT/pages/expressions/list-expressions.adoc
@@ -2,7 +2,7 @@
 :description: Information about Cypher's list expressions.
 :table-caption!:
 
-List expressions are a way to manipulate and query xref:values-and-types/lists.adoc[`LIST`] values in Cypher.
+List expressions allow you to manipulate and query xref:values-and-types/lists.adoc[`LIST`] values in Cypher.
 
 For more expressions that evaluate to a `LIST` value, see xref:functions/list.adoc[List functions]. +
 For information about how to check membership in a `LIST` using the `IN` operator, see xref:expressions/predicates/list-operators.adoc[Predicates -> List operators].

From eea7358c4b70afc6c411607d44a324970b957425 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Tue, 1 Apr 2025 10:46:35 +0200
Subject: [PATCH 08/10] post review corrections 1

---
 .../pages/expressions/list-expressions.adoc   | 291 ++++++++++++------
 1 file changed, 190 insertions(+), 101 deletions(-)

diff --git a/modules/ROOT/pages/expressions/list-expressions.adoc b/modules/ROOT/pages/expressions/list-expressions.adoc
index c2c33686a..70abbc7ae 100644
--- a/modules/ROOT/pages/expressions/list-expressions.adoc
+++ b/modules/ROOT/pages/expressions/list-expressions.adoc
@@ -32,105 +32,6 @@ CREATE (alice:Person {name:'Alice', age: 65, role: 'Project manager', skills: ['
        (daniel)-[:WORKS_FOR]->(eskil)
 ----
 
-[[list-concatenation]]
-== List concatenation
-
-Cypher contains two list concatenation operators: `||` and `+`.
-`||` is xref:appendix/gql-conformance/index.adoc[GQL conformant], while `+` is not.
-
-.List concatenation using `||` and `+`
-[source, cypher]
-----
-RETURN [1,2] || [3,4] AS list1,
-       [1,2] + [3,4] AS list2
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="2*<m"]
-|===
-| list1 | list2
-
-| [1, 2, 3, 4] | [1, 2, 3, 4]
-
-2+d|Rows: 1
-|===
-
-.Concatenate two `LIST` properties
-[source, cypher]
-----
-MATCH (cecil:Person {name: 'Cecil'}), (cecilia:Person {name: 'Cecilia'})
-RETURN cecil.skills || cecilia.skills AS combinedSkills
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| combinedSkills
-
-| ["Java", "Python", "JavaScript", "TypeScript"]
-
-1+d|Rows: 1
-|===
-
-The `+` operator can add elements to the beginning or end of a `LIST` value.
-This is not possible using the `||` operator.
-
-.Add elements to the beginning and end of a `LIST`
-[source, cypher]
-----
-WITH [1, 2, 3, 4] AS list
-RETURN 0 + list AS newBeginning,
-       list + 5 AS newEnd
-----
-
-
-.Result
-[role="queryresult",options="header,footer",cols="2*<m"]
-|===
-| newBeginning | newEnd
-
-| [0, 1, 2, 3, 4] | [1, 2, 3, 4, 5] 
-
-2+d|Rows: 1
-|===
-
-.Add elements to the beginning of a `LIST` property
-[source, cypher]
-----
-MATCH (cecil:Person {name: 'Cecil'})
-SET cecil.skills = "Cypher" + cecil.skills
-RETURN cecil.skills AS skillsList
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| skillsList
-
-| ["Cypher", "Java", "Python"] 
-
-1+d|Rows: 1
-|===
-
-If `NULL` is part of a concatenated `LIST`, `NULL` will be a part of the new `LIST`.
-
-.Concatenate `LIST` including `NULL`
-[source, cypher]
-----
-RETURN [1, 2] || [3, null] AS listWithNull
-----
-
-.Result
-[role="queryresult",options="header,footer",cols="1*<m"]
-|===
-| listWithNull
-
-| [1, 2, 3, NULL]
-
-1+d|Rows: 1
-|===
-
-For removing `NULL` values when concatenating `LIST` values, see xref:expressions/list-expressions.adoc#null-list-concatenation-list-comprehension[`NULL`, list concatenation, and list comprehension].
 
 [[list-element-access]]
 == List element access
@@ -202,6 +103,44 @@ RETURN nestedList[1] AS secondList
 1+d|Rows: 1
 |===
 
+.Access specific elements in a nested `LIST`
+[source, cypher]
+----
+WITH [[1, 2], [3, 4], [5, 6]] AS nestedList 
+RETURN nestedList[1] AS secondList,
+       nestedList[1][0] AS firstElementOfSecondList
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| secondList | firstElementOfSecondList
+
+| [3, 4] | 3
+
+2+d|Rows: 1
+|===
+
+The index in the list element access can be any expression, including a variable.
+
+.Access list elements using a variable as an index
+[source, cypher]
+----
+WITH [[1, 2], [3, 4], [5, 6]] AS nestedList, 2 AS listIndex
+RETURN nestedList[listIndex] AS thirdList, 
+       nestedList[listIndex][listIndex - 1] AS secondElementOfThirdList
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| thirdList | secondElementOfThirdList
+
+| [5, 6] | 6
+
+2+d|Rows: 1
+|===
+
 The xref:expressions/predicates/list-operators.adoc[`IN`] operator, which checks for `LIST` membership, can be used together with `[]` to test whether an element exists in a nested `LIST`.
 
 .Check for membership in a nested `LIST`
@@ -221,6 +160,7 @@ RETURN 3 IN nestedList[0] AS elementPresent
 1+d|Rows: 1
 |===
 
+
 Attempting to reference an element outside the bounds of the `LIST` will return `NULL`, as will attempting to access elements from an empty `LIST`.
 
 .Out-of-bounds and empty `LIST` access
@@ -325,10 +265,138 @@ RETURN list[0] + [2] + list[1..] AS newList
 1+d|Rows: 1
 |===
 
+[[list-concatenation]]
+== List concatenation
+
+Cypher contains two list concatenation operators: `||` and `+`.
+`||` is xref:appendix/gql-conformance/index.adoc[GQL conformant], while `+` is not.
+
+.List concatenation using `||` and `+`
+[source, cypher]
+----
+RETURN [1,2] || [3,4] AS list1,
+       [1,2] + [3,4] AS list2
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| list1 | list2
+
+| [1, 2, 3, 4] | [1, 2, 3, 4]
+
+2+d|Rows: 1
+|===
+
+.Concatenate two `LIST` properties
+[source, cypher]
+----
+MATCH (cecil:Person {name: 'Cecil'}), (cecilia:Person {name: 'Cecilia'})
+RETURN cecil.skills || cecilia.skills AS combinedSkills
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| combinedSkills
+
+| ["Java", "Python", "JavaScript", "TypeScript"]
+
+1+d|Rows: 1
+|===
+
+If `NULL` is part of a concatenated `LIST`, `NULL` will be a part of the new `LIST`.
+
+.Concatenate `LIST` including `NULL`
+[source, cypher]
+----
+RETURN [1, 2] || [3, null] AS listWithNull
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| listWithNull
+
+| [1, 2, 3, NULL]
+
+1+d|Rows: 1
+|===
+
+For removing `NULL` values when concatenating `LIST` values, see xref:expressions/list-expressions.adoc#null-list-concatenation-list-comprehension[`NULL`, list concatenation, and list comprehension].
+
+[[add-elements]]
+=== Add elements to a list 
+
+The `+` operator can add elements to the beginning or end of a `LIST` value.
+This is not possible using the `||` operator.
+
+.Add elements to the beginning and end of a `LIST`
+[source, cypher]
+----
+WITH [1, 2, 3, 4] AS list
+RETURN 0 + list AS newBeginning,
+       list + 5 AS newEnd
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| newBeginning | newEnd
+
+| [0, 1, 2, 3, 4] | [1, 2, 3, 4, 5] 
+
+2+d|Rows: 1
+|===
+
+To insert a `LIST` value into a nested `LIST`, the added `LIST` must itself be nested.
+If the added `LIST` is not nested, its elements are treated as individual elements, whereas if it is nested, it maintains the `LIST` structure within the nested `LIST`.
+
+.Add `LIST` values to a nested `LIST`
+[source, cypher]
+----
+WITH [[1, 2], [3, 4]] AS nestedList
+RETURN nestedList + [5, 6] AS nonNestedAddition
+       nestedList + [[5, 6]] AS nestedAddition
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="2*<m"]
+|===
+| nonNestedAddition | nestedAddition
+
+| [[1, 2], [3, 4], 5, 6] | [[1, 2], [3, 4], [5, 6]]
+
+2+d|Rows: 1
+|===
+
+.Add elements to the beginning of a `LIST` property
+[source, cypher]
+----
+MATCH (cecil:Person {name: 'Cecil'})
+SET cecil.skills = "Cypher" + cecil.skills
+RETURN cecil.skills AS skillsList
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| skillsList
+
+| ["Cypher", "Java", "Python"] 
+
+1+d|Rows: 1
+|===
+
+
+
+
 [[list-comprehension]]
 == List comprehension
 
 List comprehension is used to create new `LIST` values by iterating over existing `LIST` values and transforming the elements based on certain conditions or operations.
+This process effectively maps each element in the original `LIST` to a new value.
+The result is a new `LIST` that consists of the transformed elements.
 
 .Syntax
 [source, syntax]
@@ -388,7 +456,28 @@ RETURN [n IN list WHERE n > 2 | n] AS filteredList
 1+d|Rows: 1
 |===
 
-This below query iterates over the `skills` property of each Person node and creates a new `LIST` by xref:expressions/string-operators.adoc[concatenating the `STRING`] `" expert"` to each element in `skills`.
+The next example shows how to map a `LIST` using its indexes with a list comprehension.
+The xref:functions/list.adoc#functions-range[`range()`] function is used to generate the indexes from `0` to the last valid index of the `LIST`, and then each index is combined with its corresponding `LIST` value into a `STRING` value.
+The result is a `LIST` of `STRING` values formatted as `'index: value'`.
+
+.Map list elements using indexes
+[source, cypher]
+----
+WITH [1,2,3,4] AS list
+RETURN [listIndex IN range(0, size(list)-1) | toString(listIndex) || ': ' || toString(list[listIndex])] AS mappedListElements
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| mappedListElements
+
+| ["0: 1", "1: 2", "2: 3", "3: 4"]
+
+1+d|Rows: 1
+|===
+
+The below query iterates over the `skills` property of each `Person` node and creates a new `LIST` by xref:expressions/string-operators.adoc[concatenating the `STRING`] `" expert"` to each element in `skills`.
 
 .Modify `LIST` properties using list comprehension
 [source, cypher]
@@ -423,7 +512,6 @@ MATCH (p:Person)
 RETURN [person IN collect(p) WHERE 'Python' IN person.skills | person.name] AS pythonExperts
 ----
 
-
 .Result
 [role="queryresult",options="header,footer",cols="1*<m"]
 |===
@@ -535,3 +623,4 @@ RETURN collect(DISTINCT superiorsSkills) AS distinctSuperiorsSkills
 1+d|Rows: 1
 |===
 
+

From d10b4a9e9dca5c4cc249e2ebd529f3b3949f9d34 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Tue, 1 Apr 2025 10:50:44 +0200
Subject: [PATCH 09/10] colons not hyphen

---
 modules/ROOT/pages/expressions/list-expressions.adoc | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/modules/ROOT/pages/expressions/list-expressions.adoc b/modules/ROOT/pages/expressions/list-expressions.adoc
index 70abbc7ae..9fb38692d 100644
--- a/modules/ROOT/pages/expressions/list-expressions.adoc
+++ b/modules/ROOT/pages/expressions/list-expressions.adoc
@@ -388,9 +388,6 @@ RETURN cecil.skills AS skillsList
 1+d|Rows: 1
 |===
 
-
-
-
 [[list-comprehension]]
 == List comprehension
 
@@ -592,7 +589,7 @@ RETURN [(employee:Person)-[:WORKS_FOR]->(alice) WHERE employee.age > 30 | employ
 Pattern comprehension can also match for xref:patterns/variable-length-patterns.adoc[variable-length patterns].
 However, pattern comprehension does not support the xref:patterns/reference.adoc#quantifiers[GQL conformant quantifier syntax].
 
-.Not allowed - pattern comprehension to match patterns of a variable length using GQL quantifier syntax
+.Not allowed: variable-length pattern comprehension using GQL quantifier syntax
 [source, cypher, role=test-fail]
 ----
 MATCH (cecil:Person {name: 'Cecil'})
@@ -603,7 +600,7 @@ Pattern comprehension only supports only the xref:patterns/reference.adoc#variab
 The below query uses a pattern comprehension to collect the skills of all superiors in the chain above `Cecil`.
 The xref:functions/list.adoc#functions-reduce[`reduce()`] function concatenates these skills into a single `LIST`, and xref:clauses/unwind.adoc[`UNWIND`] is used to flatten this `LIST` before returning the distinct skills in a new `LIST`.
 
-.Allowed - pattern comprehension to match patterns of a variable length using variable-length relationship syntax
+.Allowed: variable-length pattern comprehension using variable-length relationship syntax
 [source, cypher]
 ----
 MATCH (cecil:Person {name: 'Cecil'})

From 73b2e804da32af3f03589fa33674701148902a29 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Tue, 1 Apr 2025 13:13:48 +0200
Subject: [PATCH 10/10] negative indexing for list slicing

---
 .../pages/expressions/list-expressions.adoc   | 23 ++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/modules/ROOT/pages/expressions/list-expressions.adoc b/modules/ROOT/pages/expressions/list-expressions.adoc
index 9fb38692d..494fa1c9c 100644
--- a/modules/ROOT/pages/expressions/list-expressions.adoc
+++ b/modules/ROOT/pages/expressions/list-expressions.adoc
@@ -207,6 +207,27 @@ RETURN list[2..4] AS middleElements,
 3+d|Rows: 1
 |===
 
+Negative indexing in list slicing references elements from the end of the `LIST`; `..-1` excludes the last element, `..-2` excludes the last two elements, and so on.
+
+.Negative indexing and list slicing
+[source, cypher]
+----
+WITH [1, 2, 3, 4, 5, 6] AS list
+RETURN list[..-1] AS finalElementRemoved,
+       list[..-2] AS finalTwoElementsRemoved,
+       list[-3..-1] AS removedFirstThreeAndLast
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="3*<m"]
+|===
+| finalElementRemoved | finalTwoElementsRemoved | removedFirstThreeAndLast
+
+| [1, 2, 3, 4, 5] | [1, 2, 3, 4] | [4, 5]
+
+3+d|Rows: 1
+|===
+
 When slicing nested `LIST` values, it is important to specify which level is sliced.
 The below example slices the outer `LIST` and returns the first two nested `LIST` values.
 
@@ -326,7 +347,7 @@ RETURN [1, 2] || [3, null] AS listWithNull
 For removing `NULL` values when concatenating `LIST` values, see xref:expressions/list-expressions.adoc#null-list-concatenation-list-comprehension[`NULL`, list concatenation, and list comprehension].
 
 [[add-elements]]
-=== Add elements to a list 
+== Add elements to a list 
 
 The `+` operator can add elements to the beginning or end of a `LIST` value.
 This is not possible using the `||` operator.