Update SELECT documentation to have a more thorough discussion

of LIMIT, and fix a few other glitches too.

diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml
index ed180ac91c1e6d673b33753cd6e307c851257bc7..674234d8e335a90cb2351548110e5c024b99eaa0 100644 (file)
--- a/doc/src/sgml/ref/select.sgml
+++ b/doc/src/sgml/ref/select.sgml
@@ -1,5 +1,5 @@
 
 
@@ -30,9 +30,9 @@ SELECT [ ALL | DISTINCT [ ON ( expression
     [ GROUP BY column [, ...] ]
     [ HAVING condition [, ...] ]
     [ { UNION [ ALL ] | INTERSECT | EXCEPT } select ]
-    [ ORDER BY column [ ASC | DESC ] [, ...] ]
-    [ FOR UPDATE [ OF class_name... ] ]
-    [ LIMIT { count | ALL } [ { OFFSET | , } count ] ]
+    [ ORDER BY column [ ASC | DESC | USING operator ] [, ...] ]
+    [ FOR UPDATE [ OF class_name [, ...] ] ]
+    LIMIT { count | ALL } [ { OFFSET | , } start ]
   
   
   
@@ -59,10 +59,10 @@ SELECT [ ALL | DISTINCT [ ON ( expression
       
        
    Specifies another name for a column or an expression using
-   the AS clause. name
-   cannot be used in the WHERE
-   condition. It can, however, be referenced in associated
-   ORDER BY or GROUP BY clauses.
+   the AS clause.  This name is primarily used to label the output
+   column.  The name
+   cannot be used in the WHERE, GROUP BY, or HAVING clauses.
+   It can, however, be referenced in ORDER BY clauses.
        
       
      
@@ -245,18 +245,19 @@ SELECT [ ALL | DISTINCT [ ON ( expression
   
    
   
-   The UNION clause allows the result to be the collection of rows
+   The UNION operator allows the result to be the collection of rows
    returned by the queries involved.
    (See .)
   
    
   
-   The INTERSECT give you the rows that are common to both queries.
+   The INTERSECT operator gives you the rows that are common to both queries.
    (See .)
   
    
   
-   The EXCEPT give you the rows in the upper query not in the lower query.
+   The EXCEPT operator gives you the rows returned by the first query but
+   not the second query.
    (See .)
   
    
@@ -266,8 +267,9 @@ SELECT [ ALL | DISTINCT [ ON ( expression
   
    
   
-   The LIMIT clause allows control over which rows are
-   returned by the query.
+   The LIMIT clause allows a subset of the rows produced by the query
+   to be returned to the user.
+   (See .)
   
 
   
@@ -395,15 +397,15 @@ ORDER BY column [ ASC | DESC ] [, .
     of the column. This feature makes it possible to define an ordering
     on the basis of a column that does not have a proper name.
     This is never absolutely necessary because it is always possible
-    assign a name
-    to a calculated column using the AS clause, e.g.:
+    to assign a name to a calculated column using the AS clause, e.g.:
     
 SELECT title, date_prod + 1 AS newlen FROM films ORDER BY newlen;
     
     
    
-    From release 6.4 of PostgreSQL, the columns in the ORDER BY clause
-    do not need to appear in the SELECT clause.
+    From release 6.4 of PostgreSQL, it is also possible to ORDER BY
+    arbitrary expressions, including fields that do not appear in the
+    SELECT result list.
     Thus the following statement is now legal:
     
 SELECT name FROM distributors ORDER BY code;
@@ -413,7 +415,9 @@ SELECT name FROM distributors ORDER BY code;
    
     Optionally one may add the keyword DESC (descending)
     or ASC (ascending) after each column name in the ORDER BY clause.
-    If not specified, ASC is assumed by default.
+    If not specified, ASC is assumed by default.  Alternatively, a
+    specific ordering operator name may be specified.  ASC is equivalent
+    to USING '<' and DESC is equivalent to USING '>'.
    
   
   
@@ -436,10 +440,10 @@ SELECT name FROM distributors ORDER BY code;
    
     
    
-    The UNION clause allows the result to be the collection of rows
-    returned by the queries involved. (See UNION clause).
-    The two tables that represent the direct operands of the UNION must
-    have the same number of columns, and corresponding columns must be
+    The UNION operator allows the result to be the collection of rows
+    returned by the queries involved.
+    The two SELECTs that represent the direct operands of the UNION must
+    produce the same number of columns, and corresponding columns must be
     of compatible data types.
    
     
@@ -476,16 +480,15 @@ SELECT name FROM distributors ORDER BY code;
    
 
    
-    The INTERSECT clause allows the result to be all rows that are 
-    common to the involved queries.
-    The two tables that represent the direct operands of the INTERSECT must
-    have the same number of columns, and corresponding columns must be
+    The INTERSECT operator gives you the rows that are common to both queries.
+    The two SELECTs that represent the direct operands of the INTERSECT must
+    produce the same number of columns, and corresponding columns must be
     of compatible data types.
    
     
    
     Multiple INTERSECT operators in the same SELECT statement are
-    evaluated left to right.
+    evaluated left to right, unless parentheses dictate otherwise.
    
   
 
@@ -508,16 +511,65 @@ SELECT name FROM distributors ORDER BY code;
    
 
    
-    The EXCEPT clause allows the result to be rows from the upper query
-    that are not in the lower query.  (See EXCEPT clause).
-    The two tables that represent the direct operands of the EXCEPT must
-    have the same number of columns, and corresponding columns must be
+    The EXCEPT operator gives you the rows returned by the first query but
+    not the second query.
+    The two SELECTs that represent the direct operands of the EXCEPT must
+    produce the same number of columns, and corresponding columns must be
     of compatible data types.
    
 
    
     Multiple EXCEPT operators in the same SELECT statement are
-    evaluated left to right.
+    evaluated left to right, unless parentheses dictate otherwise.
+   
+  
+
+  
+   
+    2000-02-20
+   
+   
+    LIMIT Clause
+   
+   
+    
+    LIMIT { count | ALL } [ { OFFSET | , } start ]
+    OFFSET start
+    
+    
+    where
+    count specifies the
+    maximum number of rows to return, and
+    start specifies the
+    number of rows to skip before starting to return rows.
+   
+
+   
+    LIMIT allows you to retrieve just a portion of the rows that are generated
+    by the rest of the query.  If a limit count is given, no more than that
+    many rows will be returned.  If an offset is given, that many rows will
+    be skipped before starting to return rows.
+   
+
+   
+    When using LIMIT, it is a good idea to use an ORDER BY clause that
+    constrains the result rows into a unique order.  Otherwise you will get
+    an unpredictable subset of the query's rows --- you may be asking for
+    the tenth through twentieth rows, but tenth through twentieth in what
+    ordering?  You don't know what ordering, unless you specified ORDER BY.
+   
+
+   
+    As of Postgres 7.0, the
+    query optimizer takes LIMIT into account when generating a query plan,
+    so you are very likely to get different plans (yielding different row
+    orders) depending on what you give for LIMIT and OFFSET.  Thus, using
+    different LIMIT/OFFSET values to select different subsets of a query
+    result will give inconsistent results unless
+    you enforce a predictable result ordering with ORDER BY.  This is not
+    a bug; it is an inherent consequence of the fact that SQL does not
+    promise to deliver the results of a query in any particular order
+    unless ORDER BY is used to constrain the order.
    
   
  
@@ -624,7 +676,7 @@ SELECT * FROM distributors ORDER BY 2;
    This example shows how to obtain the union of the tables
    distributors and
    actors, restricting the results to those that begin
-   with letter W in each table.  Only distinct rows are to be used, so the
+   with letter W in each table.  Only distinct rows are wanted, so the
    ALL keyword is omitted:
 
    
@@ -709,16 +761,9 @@ SELECT distributors.* WHERE name = 'Westwood';
      parsing ambiguities
      in this context.
      
-    
-     In the SQL92 standard, the new column name 
-     specified in an
-     "AS" clause may be referenced in GROUP BY and HAVING clauses.
-     This is not currently
-     allowed in Postgres.
-    
-     
     
      The DISTINCT ON phrase is not part of SQL92.
+     Nor are LIMIT and OFFSET.
     
    
 

diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml
index 6617d07e5a6024a77d9a94cdb5044a9c64f7a433..277b2058740cbdff6f1ab88de94d250a86bde16d 100644 (file)
--- a/doc/src/sgml/ref/select_into.sgml
+++ b/doc/src/sgml/ref/select_into.sgml
@@ -1,5 +1,5 @@
 
 
@@ -22,16 +22,17 @@ Postgres documentation
    1999-07-20
   
   
-SELECT [ ALL | DISTINCT ] expression [ AS name ] [, ...]
-    INTO [TEMP] [ TABLE ] new_table ]
-    [ FROM table [alias] [, ...] ]
+SELECT [ ALL | DISTINCT [ ON ( expression [, ...] ) ] ]
+    expression [ AS name ] [, ...]
+    [ INTO [ TEMPORARY | TEMP ] [ TABLE ] new_table ]
+    [ FROM table [ alias ] [, ...] ]
     [ WHERE condition ]
     [ GROUP BY column [, ...] ]
     [ HAVING condition [, ...] ]
-    [ { UNION [ALL] | INTERSECT | EXCEPT } select]
-    [ ORDER BY column [ ASC | DESC ] [, ...] ]
-    [ FOR UPDATE [OF class_name...]]
-    [ LIMIT count [OFFSET|, count]]
+    [ { UNION [ ALL ] | INTERSECT | EXCEPT } select ]
+    [ ORDER BY column [ ASC | DESC | USING operator ] [, ...] ]
+    [ FOR UPDATE [ OF class_name [, ...] ] ]
+    LIMIT { count | ALL } [ { OFFSET | , } start ]