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;