From 581a1e926d4347ad2f5586c3ab5212e67ff98ebc Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Sun, 19 Jan 2020 23:48:00 -0800 Subject: [PATCH 1/7] [SPARK-30579] Document ORDER BY Clause of SELECT statement in SQL Reference --- docs/sql-ref-syntax-qry-select-orderby.md | 118 +++++++++++++++++++++- 1 file changed, 117 insertions(+), 1 deletion(-) diff --git a/docs/sql-ref-syntax-qry-select-orderby.md b/docs/sql-ref-syntax-qry-select-orderby.md index 1f7c031e4aa8..87c56e84124c 100644 --- a/docs/sql-ref-syntax-qry-select-orderby.md +++ b/docs/sql-ref-syntax-qry-select-orderby.md @@ -18,5 +18,121 @@ license: | See the License for the specific language governing permissions and limitations under the License. --- +The ORDER BY clause is used to return the result rows in a sorted manner +in the user specified order. Unlike the SORT BY clause, this clause guarantees +total order in the output. -**This page is under construction** +### Syntax +{% highlight sql %} +ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] } +{% endhighlight %} + +### Parameters +
+
ORDER BY
+
+ Specifies a comma separated list of expressions along with optional parameters sort_direction + and nulls_sort_order which are used to sort the rows. +
+
sort_direction
+
+ Optionally specifies whether to sort the rows in ascending (lowest to highest) or descending + (highest to lowest) order. The valid values for sort direction are ASC for ascending + and DESC for descending. If sort direction is not explicitly specified then by default + rows are sorted in ascending manner.

+ Syntax: + + [ ASC | DESC ] + +
+
nulls_sort_order
+
+ Optionally specifies whether NULL values are returned before/after non-NULL values, based on the + sort direction. In spark, NULL values are considered to be lower than any non-NULL values. Therefore + the ordering of NULL values depend on the sort direction.

+
    +
  1. If the sort order is ASC, NULLS are returned first; to force NULLS to be last, use NULLS LAST
    2. +
  2. If the sort order is DESC, NULLS are returned last; to force NULLS to be first, use NULLS FIRST
    3. +

+ Syntax: + + [ NULLS { FIRST | LAST } ] + +
+
+ +### Examples +{% highlight sql %} +CREATE TABLE person (id INT, name STRING, age INT); +INSERT INTO person VALUES (100, 'John', 30), + (200, 'Mary', NULL), + (300, 'Mike', 80), + (400, 'Jerry', NULL), + (500, 'Dan', 50); + +-- Sort rows by age. By default rows are sorted in ascending manner. +SELECT name, age FROM person ORDER BY age; + + +-----+----+ + |name |age | + +-----+----+ + |Jerry|null| + |Mary |null| + |John |30 | + |Dan |50 | + |Mike |80 | + +-----+----+ + +-- Sort rows in ascending manner keeping null values to be last. +SELECT name, age FROM person ORDER BY age NULLS LAST; + + +-----+----+ + |name |age | + +-----+----+ + |John |30 | + |Dan |50 | + |Mike |80 | + |Mary |null| + |Jerry|null| + +-----+----+ + +-- Sort rows by age in descending manner. +SELECT name, age FROM person ORDER BY age DESC; + + +-----+----+ + |name |age | + +-----+----+ + |Mike |80 | + |Dan |50 | + |John |30 | + |Jerry|null| + |Mary |null| + +-----+----+ + +-- Sort rows in ascending manner keeping null values to be first. +SELECT name, age FROM person ORDER BY age DESC NULLS FIRST; + + +-----+----+ + |name |age | + +-----+----+ + |Jerry|null| + |Mary |null| + |Mike |80 | + |Dan |50 | + |John |30 | + +-----+----+ + +-- Sort rows based on more than one column with each column having different +-- sort direction. +SELECT * FROM person ORDER BY name ASC, age DESC; + + +---+-----+----+ + |id |name |age | + +---+-----+----+ + |500|Dan |50 | + |400|Jerry|null| + |100|John |30 | + |200|Mary |null| + |300|Mike |80 | + +---+-----+----+ +{% endhighlight %} From cb78d8d676568604a26a785f48057c9c4dd7248e Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Mon, 20 Jan 2020 14:08:37 -0800 Subject: [PATCH 2/7] Code review --- docs/sql-ref-syntax-qry-select-orderby.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/sql-ref-syntax-qry-select-orderby.md b/docs/sql-ref-syntax-qry-select-orderby.md index 87c56e84124c..5a50f0f4ced4 100644 --- a/docs/sql-ref-syntax-qry-select-orderby.md +++ b/docs/sql-ref-syntax-qry-select-orderby.md @@ -31,8 +31,8 @@ ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] }
ORDER BY
- Specifies a comma separated list of expressions along with optional parameters sort_direction - and nulls_sort_order which are used to sort the rows. + Specifies a comma separated list of expressions along with optional parameters sort_direction + and nulls_sort_order which are used to sort the rows.
sort_direction
@@ -48,8 +48,8 @@ ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] }
nulls_sort_order
Optionally specifies whether NULL values are returned before/after non-NULL values, based on the - sort direction. In spark, NULL values are considered to be lower than any non-NULL values. Therefore - the ordering of NULL values depend on the sort direction.

+ sort direction. In Spark, NULL values are considered to be lower than any non-NULL values by default. + Therefore the ordering of NULL values depend on the sort direction.

  1. If the sort order is ASC, NULLS are returned first; to force NULLS to be last, use NULLS LAST
  2. If the sort order is DESC, NULLS are returned last; to force NULLS to be first, use NULLS FIRST
    3. From d1fb7bd41c43196b23f51db0f7954df167685022 Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Mon, 20 Jan 2020 22:19:52 -0800 Subject: [PATCH 3/7] code review --- docs/sql-ref-syntax-qry-select-orderby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sql-ref-syntax-qry-select-orderby.md b/docs/sql-ref-syntax-qry-select-orderby.md index 5a50f0f4ced4..6113822166ac 100644 --- a/docs/sql-ref-syntax-qry-select-orderby.md +++ b/docs/sql-ref-syntax-qry-select-orderby.md @@ -31,7 +31,7 @@ ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] }
    ORDER BY
    - Specifies a comma separated list of expressions along with optional parameters sort_direction + Specifies a comma-separated list of expressions along with optional parameters sort_direction and nulls_sort_order which are used to sort the rows.
    sort_direction
    From a9dfbb4ad1acead96d4ebfb9019b34283c6dac99 Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Wed, 22 Jan 2020 15:34:56 -0800 Subject: [PATCH 4/7] Code review --- docs/sql-ref-syntax-qry-select-orderby.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/sql-ref-syntax-qry-select-orderby.md b/docs/sql-ref-syntax-qry-select-orderby.md index 6113822166ac..9db081987029 100644 --- a/docs/sql-ref-syntax-qry-select-orderby.md +++ b/docs/sql-ref-syntax-qry-select-orderby.md @@ -39,7 +39,7 @@ ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] } Optionally specifies whether to sort the rows in ascending (lowest to highest) or descending (highest to lowest) order. The valid values for sort direction are ASC for ascending and DESC for descending. If sort direction is not explicitly specified then by default - rows are sorted in ascending manner.

    + rows are sorted ascending.

    Syntax: [ ASC | DESC ] @@ -49,10 +49,14 @@ ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] }
    Optionally specifies whether NULL values are returned before/after non-NULL values, based on the sort direction. In Spark, NULL values are considered to be lower than any non-NULL values by default. - Therefore the ordering of NULL values depend on the sort direction.

    + Therefore the ordering of NULL values depend on the sort direction. If null_sort_order is + not specified then NULLs sort first if sort order is ASC and NULLS sort last if + sort order is DESC.

      -
    1. If the sort order is ASC, NULLS are returned first; to force NULLS to be last, use NULLS LAST
      2. -
    2. If the sort order is DESC, NULLS are returned last; to force NULLS to be first, use NULLS FIRST
      3. +
    3. If NULLS FIRST (the default) is specified, then NULL values are returned first + regardless of the sort order.
      4. +
    4. If NULLS LAST is specified, then NULL values are returned last regardless of + the sort order.

    Syntax: From ff61fa8c9fc43d762f1835da4d42cd5145af4a3e Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Wed, 22 Jan 2020 21:49:30 -0800 Subject: [PATCH 5/7] Code review --- docs/sql-ref-syntax-qry-select-orderby.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/sql-ref-syntax-qry-select-orderby.md b/docs/sql-ref-syntax-qry-select-orderby.md index 9db081987029..ba421251e596 100644 --- a/docs/sql-ref-syntax-qry-select-orderby.md +++ b/docs/sql-ref-syntax-qry-select-orderby.md @@ -20,7 +20,7 @@ license: | --- The ORDER BY clause is used to return the result rows in a sorted manner in the user specified order. Unlike the SORT BY clause, this clause guarantees -total order in the output. +a total order in the output. ### Syntax {% highlight sql %} @@ -68,11 +68,12 @@ ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] } ### Examples {% highlight sql %} CREATE TABLE person (id INT, name STRING, age INT); -INSERT INTO person VALUES (100, 'John', 30), - (200, 'Mary', NULL), - (300, 'Mike', 80), - (400, 'Jerry', NULL), - (500, 'Dan', 50); +INSERT INTO person VALUES + (100, 'John', 30), + (200, 'Mary', NULL), + (300, 'Mike', 80), + (400, 'Jerry', NULL), + (500, 'Dan', 50); -- Sort rows by age. By default rows are sorted in ascending manner. SELECT name, age FROM person ORDER BY age; From 7e46a5fe1c18e62c119b660f0ff7d3d607b164e9 Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Thu, 23 Jan 2020 00:44:17 -0800 Subject: [PATCH 6/7] review --- docs/sql-ref-syntax-qry-select-orderby.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sql-ref-syntax-qry-select-orderby.md b/docs/sql-ref-syntax-qry-select-orderby.md index ba421251e596..7dba111f5e5a 100644 --- a/docs/sql-ref-syntax-qry-select-orderby.md +++ b/docs/sql-ref-syntax-qry-select-orderby.md @@ -36,8 +36,8 @@ ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] }
    sort_direction
    - Optionally specifies whether to sort the rows in ascending (lowest to highest) or descending - (highest to lowest) order. The valid values for sort direction are ASC for ascending + Optionally specifies whether to sort the rows in ascending or descending + order. The valid values for the sort direction are ASC for ascending and DESC for descending. If sort direction is not explicitly specified then by default rows are sorted ascending.

    Syntax: From c409609017b0e47f278f1568620f9f6343f5b53f Mon Sep 17 00:00:00 2001 From: Dilip Biswal Date: Thu, 23 Jan 2020 01:49:47 -0800 Subject: [PATCH 7/7] minor --- docs/sql-ref-syntax-qry-select-orderby.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sql-ref-syntax-qry-select-orderby.md b/docs/sql-ref-syntax-qry-select-orderby.md index 7dba111f5e5a..1a5d2d404e2c 100644 --- a/docs/sql-ref-syntax-qry-select-orderby.md +++ b/docs/sql-ref-syntax-qry-select-orderby.md @@ -24,7 +24,7 @@ a total order in the output. ### Syntax {% highlight sql %} -ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] } +ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ... ] } {% endhighlight %} ### Parameters @@ -38,7 +38,7 @@ ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] }
    Optionally specifies whether to sort the rows in ascending or descending order. The valid values for the sort direction are ASC for ascending - and DESC for descending. If sort direction is not explicitly specified then by default + and DESC for descending. If sort direction is not explicitly specified, then by default rows are sorted ascending.

    Syntax: @@ -50,7 +50,7 @@ ORDER BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] } Optionally specifies whether NULL values are returned before/after non-NULL values, based on the sort direction. In Spark, NULL values are considered to be lower than any non-NULL values by default. Therefore the ordering of NULL values depend on the sort direction. If null_sort_order is - not specified then NULLs sort first if sort order is ASC and NULLS sort last if + not specified, then NULLs sort first if sort order is ASC and NULLS sort last if sort order is DESC.

    1. If NULLS FIRST (the default) is specified, then NULL values are returned first