image and more example

Author: JPryce-Aklundh

modules/ROOT/images/graph_order_by_clause.svg

@@ -6,31 +6,30 @@
 `ORDER BY` is a subclause which specifies the order in which the output of a xref:clauses/return.adoc[`RETURN`] or xref:clauses/with.adoc[`WITH`] clause.
 As of Neo4j 5.24, it can also be used as a standalone clause, either on its own or in combination with `SKIP`/`OFFSET` or `LIMIT`.
 
-`ORDER BY` by default sorts results in an ascending order, though it can be modified to return results in a xref:clauses/order-by.adoc#ascending-descending-order[descending order].
+`ORDER BY` defaults to sorting results in an ascending order, though it can be modified to sort results in a xref:clauses/order-by.adoc#ascending-descending-order[descending order].
 
 `ORDER BY` relies on comparisons to sort the output (see xref:values-and-types/ordering-equality-comparison.adoc[] for more details).
 You can sort on different values, such as node or relationship properties, IDs, or the result of expressions.
 
 [IMPORTANT]
-====
 Unless `ORDER BY` is used, Neo4j does not guarantee the row order of a query result.
-====
+
 
 [[example-graph]]
 == Example graph
 
-The following graph is used for the examples below:
+A graph with the following schema is used for the examples below:
 
-image::list_expressions_graph.svg[width="600", role="middle"]
+image::graph_order_by_clause.svg[width="400", role="middle"]
 
 To recreate it, run the following query against an empty Neo4j database:
 
 [source, cypher, role=test-setup]
 ----
-CREATE (o1:Order {id: 'ORD-001', orderDate: datetime('2024-05-01T10:00:00'), total: 750, status: 'shipped'}),
+CREATE (o1:Order {id: 'ORD-001', orderDate: datetime('2024-05-01T10:00:00'), total: 550, status: 'shipped'}),
        (o2:Order {id: 'ORD-002', orderDate: datetime('2024-05-02T14:30:00'), total: 1000, status: 'pending'}),
-       (o3:Order {id: 'ORD-003', orderDate: datetime('2024-05-03T09:15:00'), total: 750, status: 'pending'}),
-       (o4:Order {id: 'ORD-004', orderDate: datetime('2024-05-04T12:45:00'), total: 500}),
+       (o3:Order {id: 'ORD-003', orderDate: datetime('2024-05-03T09:15:00'), total: 550, status: 'pending'}),
+       (o4:Order {id: 'ORD-004', orderDate: datetime('2024-05-04T12:45:00'), total: 200}),
        (o5:Order {id: 'ORD-005', orderDate: datetime('2024-05-05T15:00:00'), total: 800, status: 'shipped'}),
 
        (i1:Item {name: 'Phone', price: 500}),
@@ -74,11 +73,11 @@ The nodes are returned, sorted by the value of the `total` properties in an asce
 |===
 | order | total
 
-| "ORD-004" | 500
-| "ORD-001" | 750
-| "ORD-003" | 750
+| "ORD-004" | 200
+| "ORD-001" | 550
+| "ORD-003" | 550
 | "ORD-005" | 800
-| "ORD-002" | 1000
+| "ORD-002" | 1000 
 
 2+d|Rows: 5
 |===
@@ -108,9 +107,9 @@ This returns the nodes, sorted first by their `total` property, and then, for eq
 |===
 | order | total | orderDate
 
-| "ORD-004" | 500   | 2024-05-04T12:45Z
-| "ORD-001" | 750   | 2024-05-01T10:00Z
-| "ORD-003" | 750   | 2024-05-03T09:15Z
+| "ORD-004" | 200   | 2024-05-04T12:45Z
+| "ORD-001" | 550   | 2024-05-01T10:00Z
+| "ORD-003" | 550   | 2024-05-03T09:15Z
 | "ORD-005" | 800   | 2024-05-05T15:00Z
 | "ORD-002" | 1000  | 2024-05-02T14:30Z
 
@@ -132,8 +131,6 @@ RETURN o.id AS order,
   ORDER BY elementId
 ----
 
-The nodes are returned, sorted by their internal IDs.
-
 .Result
 [role="queryresult",options="header,footer",cols="2*<m"]
 |===
@@ -154,7 +151,7 @@ Applications relying on internal Neo4j IDs are, as a result, brittle and can be
 It is recommended to use application-generated IDs instead.
 
 [[order-by-expression]]
-== Order by expressions results
+== Order by expressions
 
 `ORDER BY` can be used to sort according to the results of an xref:expressions/index.adoc[expression].
 The below query calculates a 10% discount on each order's `total` property value, and then orders the results by the discounted total.
@@ -173,9 +170,9 @@ RETURN o.id AS order,
 |===
 | order | discountedTotal
 
-| "ORD-004" | 450.0
-| "ORD-001" | 675.0
-| "ORD-003" | 675.0
+| "ORD-004" | 180.0
+| "ORD-001" | 495.0
+| "ORD-003" | 495.0
 | "ORD-005" | 720.0
 | "ORD-002" | 900.0
 
@@ -228,9 +225,9 @@ RETURN o.id AS order,
 |===
 | order | total
 
-| "ORD-004" | 500
-| "ORD-001" | 750
-| "ORD-003" | 750
+| "ORD-004" | 200
+| "ORD-001" | 550
+| "ORD-003" | 550
 | "ORD-005" | 800
 | "ORD-002" | 1000
 
@@ -255,9 +252,9 @@ RETURN o.id AS order,
 
 | "ORD-002" | 1000
 | "ORD-005" | 800
-| "ORD-001" | 750
-| "ORD-003" | 750
-| "ORD-004" | 500
+| "ORD-001" | 550
+| "ORD-003" | 550
+| "ORD-004" | 200
 
 2+d|Rows: 5
 |===
@@ -292,7 +289,7 @@ RETURN o.id AS order,
 |===
 
 [[null]]
-== Ordering `null`
+== Null values
 
 When sorting, `null` values appear last in ascending order and first in descending order.
 
@@ -321,13 +318,12 @@ RETURN o.id AS order,
 
 
 [[order-with]]
-== Ordering in a `WITH` clause
+== ORDER BY and the WITH clause
 
-When `ORDER BY` is present on a `WITH` clause , the immediately following clause will receive records in the specified order.
+When `ORDER BY` is present on a `WITH` clause, the immediately following clause will receive records in the specified order.
 The ordering guarantee can be useful to exploit by operations which depend on the order in which they consume values.
-For example, this can be used to control the order of items in the list produced by the xref:functions/aggregating.adoc#functions-collect[`collect()`] aggregating function.
+For example, appending `ORDER BY` to a `WITH` clause can be used to control the order of items in the list produced by the xref:functions/aggregating.adoc#functions-collect[`collect()`] aggregating function.
 The xref:clauses/merge.adoc[`MERGE`] and xref:clauses/set.adoc[`SET`] clauses also have ordering dependencies which can be controlled this way.
-The order is not guaranteed to be retained after the following clause, unless that also has an `ORDER BY` subclause.
 
 The below example uses `WITH` and `ORDER BY` to sort `Item` nodes by their `price` property, then the `collect()` in the subsequent `RETURN` clause builds an ordered list per order based on that sort.
 
@@ -351,40 +347,48 @@ RETURN o.id AS orderId,
 | "ORD-001" | ["Phone($500)", "Charger($50)"]
 | "ORD-003" | ["Phone($500)", "Charger($50)"]
 | "ORD-005" | ["Phone($500)", "Headphones($250)", "Charger($50)"]
-| "ORD-004" | ["Keyboard($200)"]  
+| "ORD-004" | ["Keyboard($200)"]
 
 2+d|Rows: 5
 |===
 
-The next query uses `ORDER BY` to sort `Item` nodes by order count, then creates a `discount` property with `SET` based on the order count:
+[[aggregation-distinct]]
+== Ordering aggregated or DISTINCT results
 
-.`WITH`, `ORDER BY`, and `SET`
+The variables available to `ORDER BY` depends on whether or not the preceding `RETURN` or `WITH` clause performs an aggregation to combine results or uses `DISTINCT` to remove duplicates.
+
+* If the `RETURN` or `WITH` is not aggregating values or using `DISTINCT`, then `ORDER BY` can reference any variables referenced in the preceding `RETURN` or `WITH` clause.
+
+.`ORDER BY` following a `WITH` clause excluding aggregation or `DISTINCT`
 [source, cypher]
 ----
-MATCH (i:Item)<-[:CONTAINS]-(o:Order)
-WITH i,
-     count(o) AS orderCount
-  ORDER BY orderCount DESC
-SET i.discount = CASE
-                  WHEN orderCount < 2 THEN 0.10
-                  ELSE 0.05
-                END
-RETURN i.name AS item,
-       orderCount,
-       i.price AS originalPrice,
-       (i.price * (1 - i.discount)) AS discountedPrice
+MATCH (o:Order)-[:CONTAINS]->(i:Item)
+WITH o.id AS order,
+     i.name AS item
+  ORDER BY o.orderDate
+RETURN order, item
 ----
 
-== Ordering aggregated or DISTINCT results
+* If the `RETURN` or `WITH` performs an aggregation or uses `DISTINCT` only the projected variables from either operation are available to `ORDER BY`.
+This is because these operations alter the number of rows produced by the clause and any variables not explicitly projected are discarded.
 
-In terms of scope of variables, `ORDER BY` follows special rules, depending on if the projecting `RETURN` or `WITH` clause is either aggregating or `DISTINCT`.
-If it is an aggregating or `DISTINCT` projection, only the variables available in the projection are available.
-If the projection does not alter the output cardinality (which aggregation and `DISTINCT` do), variables available from before the projecting clause are also available.
-When the projection clause shadows already existing variables, only the new variables are available.
+.`ORDER BY` following a `WITH` clause projecting an aggregated value
+[source, cypher, role=test-fail]
+----
+MATCH (o:Order)-[:CONTAINS]->(i:Item)
+WITH collect(o.id) AS orders,
+     i.name AS items
+  ORDER BY o.orderDate
+RETURN orders, items
+----
 
-It is also not allowed to use aggregating expressions in the `ORDER BY` subclause if they are not also listed in the projecting clause.
-This rule is to make sure that `ORDER BY` does not change the results, only the order of them.
+.Error message
+[source, error]
+----
+In a WITH/RETURN with DISTINCT or an aggregation, it is not possible to access variables declared before the WITH/RETURN: o
+----
 
+[[indexes]]
 == ORDER BY and indexes
 
 The performance of Cypher queries using `ORDER BY` on node properties can be influenced by the existence and use of an index for finding the nodes.