diff --git a/docs/sql-ref-syntax-qry-select-orderby.md b/docs/sql-ref-syntax-qry-select-orderby.md index 1f7c031e4aa88..1a5d2d404e2c0 100644 --- a/docs/sql-ref-syntax-qry-select-orderby.md +++ b/docs/sql-ref-syntax-qry-select-orderby.md @@ -18,5 +18,126 @@ 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 +a 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 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: + + [ 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 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 + sort order is DESC.

+
    +
  1. If NULLS FIRST (the default) is specified, then NULL values are returned first + regardless of the sort order.
  2. +
  3. If NULLS LAST is specified, then NULL values are returned last regardless of + the sort order.
  4. +

+ 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 %}