From a7f85783fbfa46ab5abefe6bfeae0b8ff35449d8 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Mon, 21 Feb 2000 01:13:52 +0000 Subject: [PATCH] Update SELECT documentation to have a more thorough discussion of LIMIT, and fix a few other glitches too. --- doc/src/sgml/ref/select.sgml | 127 ++++++++++++++++++++---------- doc/src/sgml/ref/select_into.sgml | 17 ++-- 2 files changed, 95 insertions(+), 49 deletions(-) diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index ed180ac91c..674234d8e3 100644 --- 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 ( expressioncolumn [, ...] ] [ 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 6617d07e5a..277b205874 100644 --- 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 ]