update

Author: JPryce-Aklundh

modules/ROOT/pages/clauses/order-by.adoc

@@ -1,7 +1,6 @@
-:description: Information about Cypher's `ORDER BY` subclause.
-
-[[query-order]]
 = ORDER BY
+:description: Information about Cypher's `ORDER BY` subclause.
+:table-caption!:
 
 `ORDER BY` is a subclause that determines how the results of a xref:clauses/return.adoc[`RETURN`] or xref:clauses/with.adoc[`WITH`] clause are ordered.
 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`.
@@ -51,7 +50,10 @@ CREATE (o1:Order {id: 'ORD-001', orderDate: datetime('2024-05-01T10:00:00'), tot
 
 
 [[order-by-property]]
-== Order by property values
+== Basic examples
+
+.Order by property values
+=====
 
 `ORDER BY` can be used to sort the result by property values.
 
@@ -82,8 +84,10 @@ The nodes are returned, sorted by the value of the `total` properties in an asce
 2+d|Rows: 5
 |===
 
-[[order-by-multiple-properties]]
-== Order by multiple property values
+=====
+
+.Order by multiple property values
+=====
 
 Order by multiple property values by listing two or more properties in the `ORDER BY` subclause.
 Cypher sorts by the first property, and if values are equal, it moves to the next property, and so on.
@@ -116,9 +120,10 @@ This returns the nodes, sorted first by their `total` property, and then, for eq
 3+d|Rows: 5
 |===
 
+=====
 
-[[order-by-id]]
-== Order by ID
+.Order by ID
+=====
 
 `ORDER BY` can be used to sort nodes or relationships by their ID (retrieved by either the xref:functions/scalar.adoc#functions-elementid[`elementId()`] or xref:functions/scalar.adoc#functions-id[`id()`] functions).
 
@@ -150,8 +155,10 @@ Neo4j reuses its internal IDs when nodes and relationships are deleted.
 Applications relying on internal Neo4j IDs are, as a result, brittle and can be inaccurate.
 It is recommended to use application-generated IDs instead.
 
-[[order-by-expression]]
-== Order by expressions
+=====
+
+.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.
@@ -179,7 +186,7 @@ RETURN o.id AS order,
 2+d|Rows: 5
 |===
 
-This next example xref:subqueries/count.adoc[counts] the number of items contained in each order and then orders the results by the item count.
+This next query xref:subqueries/count.adoc[counts] the number of items contained in each order and then orders the results by the item count.
 
 .Order by an expression result
 [source, cypher]
@@ -204,6 +211,36 @@ RETURN o.id AS order,
 2+d|Rows: 5
 |===
 
+=====
+
+[[order-by-values-not-in-result]]
+== Order by values not in the result
+
+`ORDER BY` can sort by values that are not included in the result set.
+That is, the sort key does not need to be part of the preceding `RETURN` or `WITH` clause.
+For example, the query below sorts orders based on how many items they contain, even though that count is not returned.
+
+.Order by values not in the returned results
+[source, cypher]
+----
+MATCH (o:Order)
+RETURN o.id AS order
+  ORDER BY COUNT { (o)-[:CONTAINS]->(:Item) }
+----
+
+.Result
+[role="queryresult",options="header,footer",cols="1*<m"]
+|===
+| order
+
+| "ORD-002"
+| "ORD-004"
+| "ORD-001"
+| "ORD-003"
+| "ORD-005"
+
+1+d|Rows: 5
+|===
 
 [[ascending-descending-order]]
 == Ascending and descending order
@@ -265,13 +302,14 @@ RETURN o.id AS order,
 
 `ORDER BY` can be used to sort results before continuing with additional pattern matching.
 In the example below, it is combined with the xref:clauses/limit.adoc[`LIMIT`] subclause to first sort `Order` nodes by their `orderDate` property values, limit the result to the most recent `Order`, and then match any connected `Item` nodes.
+Also note that `ORDER BY` and `LIMIT` are used as xref:clauses/order-by.adoc#order-standalone-clause[standalone clauses] and not as subclauses in this example.
 
 .Find the items contained in the most recently placed order
 [source, cypher]
 ----
 MATCH (o:Order)
-  ORDER BY o.orderDate DESC
-  LIMIT 1
+ORDER BY o.orderDate DESC
+LIMIT 1
 MATCH (o)-[:CONTAINS]->(i:Item)
 RETURN o.id AS order,
        o.total,
@@ -321,7 +359,7 @@ RETURN o.id AS order,
 == 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.
-The ordering guarantee can be useful to exploit by operations which depend on the order in which they consume values.
+This guaranteed order is useful for operations that rely on the sequence in which values are processed.
 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.