DOC: Expand section on ORDER BY aggs (#40332)

(cherry picked from commit 99d2f6fc9864ab972259ef5692129ab49e4a7ab8)

docs/reference/sql/language/syntax/commands/select.asciidoc

@@ -303,7 +303,7 @@ Represents an input column, an output column or an ordinal number of the positio
 The direction, if not specified, is by default `ASC` (ascending).
 Regardless of the ordering specified, null values are ordered last (at the end).
 
-IMPORTANT: When used along-side, `GROUP BY` expression can point _only_ to the columns used for grouping.
+IMPORTANT: When used along-side, `GROUP BY` expression can point _only_ to the columns used for grouping or aggregate functions.
 
 For example, the following query sorts by an arbitrary input field (`page_count`):
 
@@ -312,6 +312,37 @@ For example, the following query sorts by an arbitrary input field (`page_count`
 include-tagged::{sql-specs}/docs.csv-spec[orderByBasic]
 ----
 
+[[sql-syntax-order-by-grouping]]
+==== Order By and Grouping
+
+For queries that perform grouping, ordering can be applied either on the grouping columns (by default ascending) or on aggregate functions. 
+
+NOTE: With `GROUP BY`, make sure the ordering targets the resulting group - applying it to individual elements inside the group will have no impact on the results since regardless of the order, values inside the group are aggregated.
+
+For example, to order groups simply indicate the grouping key:
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs.csv-spec[orderByGroup]
+----
+
+Multiple keys can be specified of course:
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs.csv-spec[groupByMulti]
+----
+
+Further more, it is possible to order groups based on aggregations of their values:
+
+["source","sql",subs="attributes,callouts,macros"]
+----
+include-tagged::{sql-specs}/docs.csv-spec[orderByAgg]
+----
+
+IMPORTANT: Ordering by aggregation is possible for up to 512 entries for memory consumption reasons.
+In cases where the results pass this threshold, use <<`LIMIT`, sql-syntax-limit>> to reduce the number
+of results.
+
 [[sql-syntax-order-by-score]]
 ==== Order By Score
 

x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec

@@ -898,11 +898,37 @@ Frank Herbert    |Dune                |604            |1965-06-01T00:00:00Z
 Alastair Reynolds|Revelation Space    |585            |2000-03-15T00:00:00Z
 James S.A. Corey |Leviathan Wakes     |561            |2011-06-02T00:00:00Z
 
-
-
 // end::orderByBasic
 ;
 
+orderByGroup
+schema::g:s|c:i
+// tag::orderByGroup
+SELECT gender AS g, COUNT(*) AS c FROM emp GROUP BY gender ORDER BY g DESC;
+
+       g       |       c       
+---------------+---------------
+M              |57
+F              |33             
+null           |10             
+      
+// end::orderByGroup
+;
+
+orderByAgg
+schema::g:s|salary:i
+// tag::orderByAgg
+SELECT gender AS g, MIN(salary) AS salary FROM emp GROUP BY gender ORDER BY salary DESC;
+
+       g       |    salary     
+---------------+---------------
+F              |25976          
+M              |25945          
+null           |25324             
+    
+// end::orderByAgg
+;
+
 orderByScore
 // tag::orderByScore
 SELECT SCORE(), * FROM library WHERE MATCH(name, 'dune') ORDER BY SCORE() DESC;