Skip to content

Commit a7f8578

Browse files
tglsfdctglsfdc
committed
Update SELECT documentation to have a more thorough discussion
of LIMIT, and fix a few other glitches too.
1 parent be05edd commit a7f8578

File tree

2 files changed

+95
-49
lines changed

2 files changed

+95
-49
lines changed

‎doc/src/sgml/ref/select.sgml‎

Lines changed: 86 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.24 2000/01/27 18:11:25 tgl Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select.sgml,v 1.25 2000/02/21 01:13:52 tgl Exp $
33
Postgres documentation
44
-->
55

@@ -30,9 +30,9 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
3030
[ GROUP BY <replaceable class="PARAMETER">column</replaceable> [, ...] ]
3131
[ HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ]
3232
[ { UNION [ ALL ] | INTERSECT | EXCEPT } <replaceable class="PARAMETER">select</replaceable> ]
33-
[ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...] ]
34-
[ FOR UPDATE [ OF class_name... ] ]
35-
[ LIMIT { count | ALL } [ { OFFSET | , } count ] ]
33+
[ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
34+
[ FOR UPDATE [ OF <replaceable class="PARAMETER">class_name</replaceable> [, ...] ] ]
35+
LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } [ { OFFSET | , } <replaceable class="PARAMETER">start</replaceable> ]
3636
</synopsis>
3737

3838
<refsect2 id="R2-SQL-SELECT-1">
@@ -59,10 +59,10 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
5959
<listitem>
6060
<para>
6161
Specifies another name for a column or an expression using
62-
the AS clause. <replaceable class="PARAMETER">name</replaceable>
63-
cannot be used in the WHERE
64-
condition. It can, however, be referenced in associated
65-
ORDER BY or GROUP BY clauses.
62+
the AS clause. This name is primarily used to label the output
63+
column. The <replaceable class="PARAMETER">name</replaceable>
64+
cannot be used in the WHERE, GROUP BY, or HAVING clauses.
65+
It can, however, be referenced in ORDER BY clauses.
6666
</para>
6767
</listitem>
6868
</varlistentry>
@@ -245,18 +245,19 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
245245
</para>
246246

247247
<para>
248-
The UNION clause allows the result to be the collection of rows
248+
The UNION operator allows the result to be the collection of rows
249249
returned by the queries involved.
250250
(See <xref linkend="sql-union" endterm="sql-union-title">.)
251251
</para>
252252

253253
<para>
254-
The INTERSECT give you the rows that are common to both queries.
254+
The INTERSECT operator gives you the rows that are common to both queries.
255255
(See <xref linkend="sql-intersect" endterm="sql-intersect-title">.)
256256
</para>
257257

258258
<para>
259-
The EXCEPT give you the rows in the upper query not in the lower query.
259+
The EXCEPT operator gives you the rows returned by the first query but
260+
not the second query.
260261
(See <xref linkend="sql-except" endterm="sql-except-title">.)
261262
</para>
262263

@@ -266,8 +267,9 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
266267
</para>
267268

268269
<para>
269-
The LIMIT clause allows control over which rows are
270-
returned by the query.
270+
The LIMIT clause allows a subset of the rows produced by the query
271+
to be returned to the user.
272+
(See <xref linkend="sql-limit" endterm="sql-limit-title">.)
271273
</para>
272274

273275
<para>
@@ -395,15 +397,15 @@ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, .
395397
of the column. This feature makes it possible to define an ordering
396398
on the basis of a column that does not have a proper name.
397399
This is never absolutely necessary because it is always possible
398-
assign a name
399-
to a calculated column using the AS clause, e.g.:
400+
to assign a name to a calculated column using the AS clause, e.g.:
400401
<programlisting>
401402
SELECT title, date_prod + 1 AS newlen FROM films ORDER BY newlen;
402403
</programlisting></para>
403404

404405
<para>
405-
From release 6.4 of PostgreSQL, the columns in the ORDER BY clause
406-
do not need to appear in the SELECT clause.
406+
From release 6.4 of PostgreSQL, it is also possible to ORDER BY
407+
arbitrary expressions, including fields that do not appear in the
408+
SELECT result list.
407409
Thus the following statement is now legal:
408410
<programlisting>
409411
SELECT name FROM distributors ORDER BY code;
@@ -413,7 +415,9 @@ SELECT name FROM distributors ORDER BY code;
413415
<para>
414416
Optionally one may add the keyword DESC (descending)
415417
or ASC (ascending) after each column name in the ORDER BY clause.
416-
If not specified, ASC is assumed by default.
418+
If not specified, ASC is assumed by default. Alternatively, a
419+
specific ordering operator name may be specified. ASC is equivalent
420+
to USING '&lt;' and DESC is equivalent to USING '&gt;'.
417421
</para>
418422
</refsect2>
419423

@@ -436,10 +440,10 @@ SELECT name FROM distributors ORDER BY code;
436440
</para>
437441

438442
<para>
439-
The UNION clause allows the result to be the collection of rows
440-
returned by the queries involved. (See UNION clause).
441-
The two tables that represent the direct operands of the UNION must
442-
have the same number of columns, and corresponding columns must be
443+
The UNION operator allows the result to be the collection of rows
444+
returned by the queries involved.
445+
The two SELECTs that represent the direct operands of the UNION must
446+
produce the same number of columns, and corresponding columns must be
443447
of compatible data types.
444448
</para>
445449

@@ -476,16 +480,15 @@ SELECT name FROM distributors ORDER BY code;
476480
</para>
477481

478482
<para>
479-
The INTERSECT clause allows the result to be all rows that are
480-
common to the involved queries.
481-
The two tables that represent the direct operands of the INTERSECT must
482-
have the same number of columns, and corresponding columns must be
483+
The INTERSECT operator gives you the rows that are common to both queries.
484+
The two SELECTs that represent the direct operands of the INTERSECT must
485+
produce the same number of columns, and corresponding columns must be
483486
of compatible data types.
484487
</para>
485488

486489
<para>
487490
Multiple INTERSECT operators in the same SELECT statement are
488-
evaluated left to right.
491+
evaluated left to right, unless parentheses dictate otherwise.
489492
</para>
490493
</refsect2>
491494

@@ -508,16 +511,65 @@ SELECT name FROM distributors ORDER BY code;
508511
</para>
509512

510513
<para>
511-
The EXCEPT clause allows the result to be rows from the upper query
512-
that are not in the lower query. (See EXCEPT clause).
513-
The two tables that represent the direct operands of the EXCEPT must
514-
have the same number of columns, and corresponding columns must be
514+
The EXCEPT operator gives you the rows returned by the first query but
515+
not the second query.
516+
The two SELECTs that represent the direct operands of the EXCEPT must
517+
produce the same number of columns, and corresponding columns must be
515518
of compatible data types.
516519
</para>
517520

518521
<para>
519522
Multiple EXCEPT operators in the same SELECT statement are
520-
evaluated left to right.
523+
evaluated left to right, unless parentheses dictate otherwise.
524+
</para>
525+
</refsect2>
526+
527+
<refsect2 id="SQL-LIMIT">
528+
<refsect2info>
529+
<date>2000-02-20</date>
530+
</refsect2info>
531+
<title id="sql-limit-title">
532+
LIMIT Clause
533+
</title>
534+
<para>
535+
<synopsis>
536+
LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } [ { OFFSET | , } <replaceable class="PARAMETER">start</replaceable> ]
537+
OFFSET <replaceable class="PARAMETER">start</replaceable>
538+
</synopsis>
539+
540+
where
541+
<replaceable class="PARAMETER">count</replaceable> specifies the
542+
maximum number of rows to return, and
543+
<replaceable class="PARAMETER">start</replaceable> specifies the
544+
number of rows to skip before starting to return rows.
545+
</para>
546+
547+
<para>
548+
LIMIT allows you to retrieve just a portion of the rows that are generated
549+
by the rest of the query. If a limit count is given, no more than that
550+
many rows will be returned. If an offset is given, that many rows will
551+
be skipped before starting to return rows.
552+
</para>
553+
554+
<para>
555+
When using LIMIT, it is a good idea to use an ORDER BY clause that
556+
constrains the result rows into a unique order. Otherwise you will get
557+
an unpredictable subset of the query's rows --- you may be asking for
558+
the tenth through twentieth rows, but tenth through twentieth in what
559+
ordering? You don't know what ordering, unless you specified ORDER BY.
560+
</para>
561+
562+
<para>
563+
As of Postgres 7.0, the
564+
query optimizer takes LIMIT into account when generating a query plan,
565+
so you are very likely to get different plans (yielding different row
566+
orders) depending on what you give for LIMIT and OFFSET. Thus, using
567+
different LIMIT/OFFSET values to select different subsets of a query
568+
result <emphasis>will give inconsistent results</emphasis> unless
569+
you enforce a predictable result ordering with ORDER BY. This is not
570+
a bug; it is an inherent consequence of the fact that SQL does not
571+
promise to deliver the results of a query in any particular order
572+
unless ORDER BY is used to constrain the order.
521573
</para>
522574
</refsect2>
523575
</refsect1>
@@ -624,7 +676,7 @@ SELECT * FROM distributors ORDER BY 2;
624676
This example shows how to obtain the union of the tables
625677
<literal>distributors</literal> and
626678
<literal>actors</literal>, restricting the results to those that begin
627-
with letter W in each table. Only distinct rows are to be used, so the
679+
with letter W in each table. Only distinct rows are wanted, so the
628680
ALL keyword is omitted:
629681

630682
<programlisting>
@@ -709,16 +761,9 @@ SELECT distributors.* WHERE name = 'Westwood';
709761
parsing ambiguities
710762
in this context.</para>
711763

712-
<para>
713-
In the <acronym>SQL92</acronym> standard, the new column name
714-
specified in an
715-
"AS" clause may be referenced in GROUP BY and HAVING clauses.
716-
This is not currently
717-
allowed in <productname>Postgres</productname>.
718-
</para>
719-
720764
<para>
721765
The DISTINCT ON phrase is not part of <acronym>SQL92</acronym>.
766+
Nor are LIMIT and OFFSET.
722767
</para>
723768
</refsect3>
724769

‎doc/src/sgml/ref/select_into.sgml‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.4 1999/07/22 15:09:14 thomas Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/select_into.sgml,v 1.5 2000/02/21 01:13:52 tgl Exp $
33
Postgres documentation
44
-->
55

@@ -22,16 +22,17 @@ Postgres documentation
2222
<date>1999-07-20</date>
2323
</refsynopsisdivinfo>
2424
<synopsis>
25-
SELECT [ ALL | DISTINCT ] <replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">name</replaceable> ] [, ...]
26-
INTO [TEMP] [ TABLE ] <replaceable class="PARAMETER">new_table</replaceable> ]
27-
[ FROM <replaceable class="PARAMETER">table</replaceable> [<replaceable class="PARAMETER">alias</replaceable>] [, ...] ]
25+
SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) ] ]
26+
<replaceable class="PARAMETER">expression</replaceable> [ AS <replaceable class="PARAMETER">name</replaceable> ] [, ...]
27+
[ INTO [ TEMPORARY | TEMP ] [ TABLE ] <replaceable class="PARAMETER">new_table</replaceable> ]
28+
[ FROM <replaceable class="PARAMETER">table</replaceable> [ <replaceable class="PARAMETER">alias</replaceable> ] [, ...] ]
2829
[ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
2930
[ GROUP BY <replaceable class="PARAMETER">column</replaceable> [, ...] ]
3031
[ HAVING <replaceable class="PARAMETER">condition</replaceable> [, ...] ]
31-
[ { UNION [ALL] | INTERSECT | EXCEPT } <replaceable class="PARAMETER">select</replaceable>]
32-
[ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC ] [, ...] ]
33-
[ FOR UPDATE [OF class_name...]]
34-
[ LIMIT count [OFFSET|, count]]
32+
[ { UNION [ ALL ] | INTERSECT | EXCEPT } <replaceable class="PARAMETER">select</replaceable> ]
33+
[ ORDER BY <replaceable class="PARAMETER">column</replaceable> [ ASC | DESC | USING <replaceable class="PARAMETER">operator</replaceable> ] [, ...] ]
34+
[ FOR UPDATE [ OF <replaceable class="PARAMETER">class_name</replaceable> [, ...] ] ]
35+
LIMIT { <replaceable class="PARAMETER">count</replaceable> | ALL } [ { OFFSET | , } <replaceable class="PARAMETER">start</replaceable> ]
3536
</synopsis>
3637

3738
<refsect2 id="R2-SQL-SELECTINTO-1">

0 commit comments

Comments
 (0)