From 980ee14f5704d5d48cf6ac1e3d3095f3c4e3cff6 Mon Sep 17 00:00:00 2001
From: Costin Leau <costin@users.noreply.github.com>
Date: Fri, 22 Mar 2019 10:03:42 +0200
Subject: [PATCH] DOC: Expand section on ORDER BY aggs (#40332)

(cherry picked from commit 99d2f6fc9864ab972259ef5692129ab49e4a7ab8)
---
 .../language/syntax/commands/select.asciidoc  | 33 ++++++++++++++++++-
 .../sql/qa/src/main/resources/docs.csv-spec   | 30 +++++++++++++++--
 2 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/docs/reference/sql/language/syntax/commands/select.asciidoc b/docs/reference/sql/language/syntax/commands/select.asciidoc
index f4035d3122f..1cd5ba28dd1 100644
--- a/docs/reference/sql/language/syntax/commands/select.asciidoc
+++ b/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
 
diff --git a/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec b/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec
index be6c591e1e2..41a82ac0f84 100644
--- a/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec
+++ b/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;