Rewrite discussion of ORDER BY to emphasize the SQL99 expression case

instead of the SQL92 output-column-ID case.

diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 15ee5009f85b8770e7e1df255bafbea325efac3d..6fc003bc8300f32598fcedc40ec58246941fe443 100644 (file)
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Queries
@@ -514,8 +514,8 @@ SELECT * FROM my_table AS m WHERE my_table.a > 5;
      is not valid according to the SQL standard.  In
      PostgreSQL this will draw an error if the
       configuration variable is
-     off.  If it is on, an implicit table reference
-     will be added to the
+     off (as it is by default).  If it is on,
+     an implicit table reference will be added to the
      FROM clause, so the query is processed as if
      it were written as
 
@@ -1224,38 +1224,17 @@ SELECT DISTINCT ON (expression , 
 
 SELECT select_list
     FROM table_expression
-    ORDER BY column1 ASC | DESC , column2 ASC | DESC ...
+    ORDER BY sort_expression1 ASC | DESC , sort_expression2 ASC | DESC ...
 
-   column1, etc., refer to select list
-   columns.  These can be either the output name of a column (see
-   ) or the number of a column.  Some
-   examples:
+   The sort expression(s) can be any expression that would be valid in the
+   query's select list.  An example is
 
-SELECT a, b FROM table1 ORDER BY a;
-SELECT a + b AS sum, c FROM table1 ORDER BY sum;
-SELECT a, sum(b) FROM table1 GROUP BY a ORDER BY 1;
-
-  
-
-  
-   As an extension to the SQL standard, PostgreSQL also allows ordering
-   by arbitrary expressions:
-
-SELECT a, b FROM table1 ORDER BY a + b;
-
-   References to column names of the FROM clause that are
-   not present in the select list are also allowed:
-
-SELECT a FROM table1 ORDER BY b;
+SELECT a, b FROM table1 ORDER BY a + b, c;
 
-   But these extensions do not work in queries involving
-   UNION, INTERSECT, or EXCEPT,
-   and are not portable to other SQL databases.
-  
-
-  
-   Each column specification may be followed by an optional
-   ASC or DESC to set the sort direction to
+   When more than one expression is specified,
+   the later values are used to sort rows that are equal according to the
+   earlier values.  Each expression may be followed by an optional
+   ASC or DESC keyword to set the sort direction to
    ascending or descending.  ASC order is the default.
    Ascending order puts smaller values first, where
    smaller is defined in terms of the
@@ -1264,7 +1243,7 @@ SELECT a FROM table1 ORDER BY b;
     
      
       Actually, PostgreSQL uses the default B-tree
-      operator class for the column's data type to determine the sort
+      operator class for the expression's data type to determine the sort
       ordering for ASC and DESC.  Conventionally,
       data types will be set up so that the < and
       > operators correspond to this sort ordering,
@@ -1275,9 +1254,32 @@ SELECT a FROM table1 ORDER BY b;
   
 
   
-   If more than one sort column is specified, the later entries are
-   used to sort rows that are equal under the order imposed by the
-   earlier sort columns.
+   For backwards compatibility with the SQL92 version of the standard,
+   a sort_expression can instead be the name or number
+   of an output column, as in
+
+SELECT a + b AS sum, c FROM table1 ORDER BY sum;
+SELECT a, max(b) FROM table1 GROUP BY a ORDER BY 1;
+
+   both of which sort by the first output column.  Note that an output
+   column name has to stand alone, it's not allowed as part of an expression
+   — for example, this is not correct:
+
+SELECT a + b AS sum, c FROM table1 ORDER BY sum + c;          -- wrong
+
+   This restriction is made to reduce ambiguity.  There is still 
+   ambiguity if an ORDER BY item is a simple name that
+   could match either an output column name or a column from the table
+   expression.  The output column is used in such cases.  This would
+   only cause confusion if you use AS to rename an output
+   column to match some other table column's name.
+  
+
+  
+   ORDER BY can be applied to the result of a
+   UNION, INTERSECT, or EXCEPT
+   combination, but in this case it is only permitted to sort by
+   output column names or numbers, not by expressions.
   
  
 
@@ -1299,6 +1301,7 @@ SELECT a FROM table1 ORDER BY b;
 
 SELECT select_list
     FROM table_expression
+     ORDER BY sort_expression1 ASC | DESC , sort_expression2 ASC | DESC ... 
      LIMIT { number | ALL }   OFFSET number