~ubuntu-branches/ubuntu/quantal/postgresql-9.1/quantal-proposed

« back to all changes in this revision

Viewing changes to doc/src/sgml/man7/SELECT.7

  • Committer: Package Import Robot
  • Author(s): Martin Pitt
  • Date: 2011-12-02 14:39:18 UTC
  • mfrom: (12.1.1 sid)
  • Revision ID: package-import@ubuntu.com-20111202143918-1ftj0oo87w0y8m8d
* New upstream bug fix release:
  - Fix bugs in information_schema.referential_constraints view.
    This view was being insufficiently careful about matching the
    foreign-key constraint to the depended-on primary or unique key
    constraint. That could result in failure to show a foreign key
    constraint at all, or showing it multiple times, or claiming that
    it depends on a different constraint than the one it really does.
    Since the view definition is installed by initdb, merely upgrading
    will not fix the problem. If you need to fix this in an existing
    installation, you can (as a superuser) drop the information_schema
    schema then re-create it by sourcing
    "SHAREDIR/information_schema.sql". (Run pg_config --sharedir if
    you're uncertain where "SHAREDIR" is.) This must be repeated in
    each database to be fixed.
  - Make "contrib/citext"'s upgrade script fix collations of citext
    columns and indexes.
    Existing citext columns and indexes aren't correctly marked as
    being of a collatable data type during pg_upgrade from a pre-9.1
    server. That leads to operations on them failing with errors such
    as "could not determine which collation to use for string
    comparison". This change allows them to be fixed by the same script
    that upgrades the citext module into a proper 9.1 extension during
    CREATE EXTENSION citext FROM unpackaged.
    If you have a previously-upgraded database that is suffering from
    this problem, and you already ran the "CREATE EXTENSION" command,
    you can manually run (as superuser) the "UPDATE" commands found at
    the end of "SHAREDIR/extension/citext--unpackaged--1.0.sql". (Run
    pg_config --sharedir if you're uncertain where "SHAREDIR" is.)
  - Fix possible crash during "UPDATE" or "DELETE" that joins to the
    output of a scalar-returning function.
  - Fix incorrect replay of WAL records for GIN index updates.
  - Fix TOAST-related data corruption during CREATE TABLE dest AS
    SELECT - FROM src or INSERT INTO dest SELECT * FROM src.
  - Fix possible failures during hot standby startup.
  - Start hot standby faster when initial snapshot is incomplete.
  - Fix race condition during toast table access from stale syscache
    entries. The typical symptom was transient errors like "missing chunk
    number 0 for toast value NNNNN in pg_toast_2619", where the cited toast
    table would always belong to a system catalog.
  - Track dependencies of functions on items used in parameter default
    expressions. Previously, a referenced object could be dropped without
    having dropped or modified the function, leading to misbehavior when
    the function was used. Note that merely installing this update will not
    fix the missing dependency entries; to do that, you'd need to
    "CREATE OR REPLACE" each such function afterwards. If you have
    functions whose defaults depend on non-built-in objects, doing so
    is recommended.
  - Fix incorrect management of placeholder variables in nestloop joins.
    This bug is known to lead to "variable not found in subplan target
    list" planner errors, and could possibly result in wrong query
    output when outer joins are involved.
  - Fix window functions that sort by expressions involving aggregates.
  - Fix "MergeAppend child's targetlist doesn't match MergeAppend"
    planner errors.
  - Fix index matching for operators with both collatable and
    noncollatable inputs. In 9.1.0, an indexable operator that has a
    non-collatable left-hand input type and a collatable right-hand input
    type would not be recognized as matching the left-hand column's index.
    An example is the hstore ? text operator.
  - Allow inlining of set-returning SQL functions with multiple OUT
    parameters.
  - Don't trust deferred-unique indexes for join removal.
  - Make DatumGetInetP() unpack inet datums that have a 1-byte header,
    and add a new macro, DatumGetInetPP(), that does not.
  - Improve locale support in money type's input and output.
    Aside from not supporting all standard lc_monetary formatting
    options, the input and output functions were inconsistent, meaning
    there were locales in which dumped money values could not be
    re-read.
  - Don't let transform_null_equals affect CASE foo WHEN NULL ...
    constructs.  transform_null_equals is only supposed to affect foo =
    NULL expressions written directly by the user, not equality checks
    generated internally by this form of CASE.
  - Change foreign-key trigger creation order to better support
    self-referential foreign keys.
  - Fix IF EXISTS to work correctly in "DROP OPERATOR FAMILY".
  - Disallow dropping of an extension from within its own script.
  - Don't mark auto-generated types as extension members.
  - Cope with invalid pre-existing search_path settings during "CREATE
    EXTENSION".
  - Avoid floating-point underflow while tracking buffer allocation
    rate.
  - Prevent autovacuum transactions from running in serializable mode.
    Autovacuum formerly used the cluster-wide default transaction
    isolation level, but there is no need for it to use anything higher
    than READ COMMITTED, and using SERIALIZABLE could result in
    unnecessary delays for other processes.
  - Ensure walsender processes respond promptly to SIGTERM.
  - Exclude "postmaster.opts" from base backups.
  - Fix incorrect field alignment in ecpg's SQLDA area.
  - Preserve blank lines within commands in psql's command history.
    The former behavior could cause problems if an empty line was
    removed from within a string literal, for example.
  - Avoid platform-specific infinite loop in pg_dump.
  - Fix compression of plain-text output format in pg_dump.
    pg_dump has historically understood -Z with no -F switch to mean
    that it should emit a gzip-compressed version of its plain text
    output. Restore that behavior.
  - Fix pg_dump to dump user-defined casts between auto-generated
    types, such as table rowtypes.
  - Fix missed quoting of foreign server names in pg_dump.
  - Assorted fixes for pg_upgrade. Handle exclusion constraints correctly,
    avoid failures on Windows, don't complain about mismatched toast table
    names in 8.4 databases.
  - In PL/pgSQL, allow foreign tables to define row types.
  - Fix up conversions of PL/Perl functions' results.
    Restore the pre-9.1 behavior that PL/Perl functions returning void
    ignore the result value of their last Perl statement; 9.1.0 would
    throw an error if that statement returned a reference. Also, make
    sure it works to return a string value for a composite type, so
    long as the string meets the type's input format. In addition,
    throw errors for attempts to return Perl arrays or hashes when the
    function's declared result type is not an array or composite type,
    respectively. (Pre-9.1 versions rather uselessly returned strings
    like ARRAY(0x221a9a0) or HASH(0x221aa90) in such cases.)
  - Ensure PL/Perl strings are always correctly UTF8-encoded.
  - Use the preferred version of xsubpp to build PL/Perl, not
    necessarily the operating system's main copy.
  - Correctly propagate SQLSTATE in PL/Python exceptions.
  - Do not install PL/Python extension files for Python major versions
    other than the one built against.
  - Change all the "contrib" extension script files to report a useful
    error message if they are fed to psql. This should help teach people
    about the new method of using "CREATE EXTENSION" to load these files.
    In most cases, sourcing the scripts directly would fail anyway, but
    with harder-to-interpret messages.
  - Fix incorrect coding in "contrib/dict_int" and "contrib/dict_xsyn".
  - Remove "contrib/sepgsql" tests from the regular regression test
    mechanism. Since these tests require root privileges for setup, they're
    impractical to run automatically. Switch over to a manual approach
    instead, and provide a testing script to help with that.
  - Fix assorted errors in "contrib/unaccent"'s configuration file
    parsing.
  - Honor query cancel interrupts promptly in pgstatindex().
  - Revert unintentional enabling of WAL_DEBUG. Fortunately, as debugging
    tools go, this one is pretty cheap; but it's not intended to be enabled
    by default, so revert.
  - Ensure VPATH builds properly install all server header files.
  - Shorten file names reported in verbose error messages.
    Regular builds have always reported just the name of the C file
    containing the error message call, but VPATH builds formerly
    reported an absolute path name.
* debian/rules: Fix build failure for binary-indep-only builds.
  (Closes: #646079)

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
'\" t
2
2
.\"     Title: SELECT
3
3
.\"    Author: The PostgreSQL Global Development Group
4
 
.\" Generator: DocBook XSL Stylesheets v1.75.1 <http://docbook.sf.net/>
5
 
.\"      Date: 2011-09-22
6
 
.\"    Manual: PostgreSQL 9.1.1 Documentation
7
 
.\"    Source: PostgreSQL 9.1.1
 
4
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
 
5
.\"      Date: 2011-12-01
 
6
.\"    Manual: PostgreSQL 9.1.2 Documentation
 
7
.\"    Source: PostgreSQL 9.1.2
8
8
.\"  Language: English
9
9
.\"
10
 
.TH "SELECT" "7" "2011-09-22" "PostgreSQL 9.1.1" "PostgreSQL 9.1.1 Documentation"
 
10
.TH "SELECT" "7" "2011-12-01" "PostgreSQL 9.1.2" "PostgreSQL 9.1.2 Documentation"
 
11
.\" -----------------------------------------------------------------
 
12
.\" * Define some portability stuff
 
13
.\" -----------------------------------------------------------------
 
14
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
15
.\" http://bugs.debian.org/507673
 
16
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
 
17
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
18
.ie \n(.g .ds Aq \(aq
 
19
.el       .ds Aq '
11
20
.\" -----------------------------------------------------------------
12
21
.\" * set default formatting
13
22
.\" -----------------------------------------------------------------
262
271
FOR UPDATE/FOR SHARE Clause
263
272
below\&.)
264
273
.RE
265
 
.sp
266
 
.RE
267
274
.PP
268
275
You must have
269
276
SELECT
410
417
.RS 4
411
418
A
412
419
WITH
413
 
query is referenced by writing its name, just as though the query\(aqs name were a table name\&. (In fact, the
 
420
query is referenced by writing its name, just as though the query\*(Aqs name were a table name\&. (In fact, the
414
421
WITH
415
 
query hides any real table of the same name for the purposes of the primary query\&. If necessary, you can refer to a real table of the same name by schema\-qualifying the table\(aqs name\&.) An alias can be provided in the same way as for a table\&.
 
422
query hides any real table of the same name for the purposes of the primary query\&. If necessary, you can refer to a real table of the same name by schema\-qualifying the table\*(Aqs name\&.) An alias can be provided in the same way as for a table\&.
416
423
.RE
417
424
.PP
418
425
\fIfunction_name\fR
421
428
FROM
422
429
clause\&. (This is especially useful for functions that return result sets, but any function can be used\&.) This acts as though its output were created as a temporary table for the duration of this single
423
430
SELECT
424
 
command\&. An alias can also be used\&. If an alias is written, a column alias list can also be written to provide substitute names for one or more attributes of the function\(aqs composite return type\&. If the function has been defined as returning the
 
431
command\&. An alias can also be used\&. If an alias is written, a column alias list can also be written to provide substitute names for one or more attributes of the function\*(Aqs composite return type\&. If the function has been defined as returning the
425
432
record
426
433
data type, then an alias or the key word
427
434
AS
487
494
.\}
488
495
CROSS JOIN
489
496
.RE
490
 
.RS 4
 
497
.sp
491
498
For the
492
499
INNER
493
500
and
516
523
FROM, but restricted by the join condition (if any)\&.
517
524
CROSS JOIN
518
525
is equivalent to
519
 
INNER JOIN ON (TRUE), that is, no rows are removed by qualification\&. These join types are just a notational convenience, since they do nothing you couldn\(aqt do with plain
 
526
INNER JOIN ON (TRUE), that is, no rows are removed by qualification\&. These join types are just a notational convenience, since they do nothing you couldn\*(Aqt do with plain
520
527
FROM
521
528
and
522
529
WHERE\&.
524
531
LEFT OUTER JOIN
525
532
returns all rows in the qualified Cartesian product (i\&.e\&., all combined rows that pass its join condition), plus one copy of each row in the left\-hand table for which there was no right\-hand row that passed the join condition\&. This left\-hand row is extended to the full width of the joined table by inserting null values for the right\-hand columns\&. Note that only the
526
533
JOIN
527
 
clause\(aqs own condition is considered while deciding which rows have matches\&. Outer conditions are applied afterwards\&.
 
534
clause\*(Aqs own condition is considered while deciding which rows have matches\&. Outer conditions are applied afterwards\&.
528
535
.sp
529
536
Conversely,
530
537
RIGHT OUTER JOIN
787
794
.PP
788
795
The default framing option is
789
796
RANGE UNBOUNDED PRECEDING, which is the same as
790
 
RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW; it sets the frame to be all rows from the partition start up through the current row\(aqs last peer in the
 
797
RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW; it sets the frame to be all rows from the partition start up through the current row\*(Aqs last peer in the
791
798
ORDER BY
792
799
ordering (which means all rows if there is no
793
800
ORDER BY)\&. In general,
804
811
CURRENT ROW
805
812
means that the frame starts or ends with the current row; but in
806
813
RANGE
807
 
mode it means that the frame starts or ends with the current row\(aqs first or last peer in the
 
814
mode it means that the frame starts or ends with the current row\*(Aqs first or last peer in the
808
815
ORDER BY
809
816
ordering\&. The
810
817
\fIvalue\fR
832
839
WINDOW
833
840
clause is to specify the behavior of
834
841
window functions
835
 
appearing in the query\(aqs
 
842
appearing in the query\*(Aqs
836
843
SELECT List
837
844
or
838
845
ORDER BY Clause\&. These functions can reference the
875
882
is a sub\-query of a larger query, the name is seen by the larger query as the column name of the virtual table produced by the sub\-query\&. To specify the name to use for an output column, write
876
883
AS
877
884
\fIoutput_name\fR
878
 
after the column\(aqs expression\&. (You can omit
 
885
after the column\*(Aqs expression\&. (You can omit
879
886
AS, but only if the desired output name does not match any
880
887
PostgreSQL
881
888
keyword (see
882
889
Appendix\ \&C, SQL Key Words)\&. For protection against possible future keyword additions, it is recommended that you always either write
883
890
AS
884
891
or double\-quote the output name\&.) If you do not specify a column name, a name is chosen automatically by
885
 
PostgreSQL\&. If the column\(aqs expression is a simple column reference then the chosen name is the same as that column\(aqs name; in more complex cases a generated name looking like
 
892
PostgreSQL\&. If the column\*(Aqs expression is a simple column reference then the chosen name is the same as that column\*(Aqs name; in more complex cases a generated name looking like
886
893
?column\fIN\fR?
887
894
is usually chosen\&.
888
895
.PP
889
 
An output column\(aqs name can be used to refer to the column\(aqs value in
 
896
An output column\*(Aqs name can be used to refer to the column\*(Aqs value in
890
897
ORDER BY
891
898
and
892
899
GROUP BY
901
908
can be written in the output list as a shorthand for all the columns of the selected rows\&. Also, you can write
902
909
\fItable_name\fR\&.*
903
910
as a shorthand for the columns coming from just that table\&. In these cases it is not possible to specify new names with
904
 
AS; the output column names will be the same as the table columns\(aq names\&.
 
911
AS; the output column names will be the same as the table columns\*(Aq names\&.
905
912
.SS "DISTINCT Clause"
906
913
.PP
907
914
If
936
943
.sp
937
944
retrieves the most recent weather report for each location\&. But if we had not used
938
945
ORDER BY
939
 
to force descending order of time values for each location, we\(aqd have gotten a report from an unpredictable time for each location\&.
 
946
to force descending order of time values for each location, we\*(Aqd have gotten a report from an unpredictable time for each location\&.
940
947
.PP
941
948
The
942
949
DISTINCT ON
1263
1270
.RE
1264
1271
.\}
1265
1272
.sp
 
1273
 
1266
1274
\fIcount\fR
1267
1275
specifies the maximum number of rows to return, while
1268
1276
\fIstart\fR
1296
1304
.\}
1297
1305
.sp
1298
1306
 
1299
 
According to the standard, the
1300
 
OFFSET
1301
 
clause must come before the
 
1307
In this syntax, to write anything except a simple integer constant for
 
1308
\fIstart\fR
 
1309
or
 
1310
\fIcount\fR, you must write parentheses around it\&. If
 
1311
\fIcount\fR
 
1312
is omitted in a
1302
1313
FETCH
1303
 
clause if both are present; but
1304
 
PostgreSQL
1305
 
is laxer and allows either order\&.
 
1314
clause, it defaults to 1\&.
1306
1315
ROW
1307
1316
and
1308
1317
ROWS
1310
1319
FIRST
1311
1320
and
1312
1321
NEXT
1313
 
are noise words that don\(aqt influence the effects of these clauses\&. In this syntax, when using expressions other than simple constants for
1314
 
\fIstart\fR
1315
 
or
1316
 
\fIcount\fR, parentheses will be necessary in most cases\&. If
1317
 
\fIcount\fR
1318
 
is omitted in
1319
 
FETCH, it defaults to 1\&.
 
1322
are noise words that don\*(Aqt influence the effects of these clauses\&. According to the standard, the
 
1323
OFFSET
 
1324
clause must come before the
 
1325
FETCH
 
1326
clause if both are present; but
 
1327
PostgreSQL
 
1328
is laxer and allows either order\&.
1320
1329
.PP
1321
1330
When using
1322
1331
LIMIT, it is a good idea to use an
1323
1332
ORDER BY
1324
 
clause that constrains the result rows into a unique order\&. Otherwise you will get an unpredictable subset of the query\(aqs rows \(em you might be asking for the tenth through twentieth rows, but tenth through twentieth in what ordering? You don\(aqt know what ordering unless you specify
 
1333
clause that constrains the result rows into a unique order\&. Otherwise you will get an unpredictable subset of the query\*(Aqs rows \(em you might be asking for the tenth through twentieth rows, but tenth through twentieth in what ordering? You don\*(Aqt know what ordering unless you specify
1325
1334
ORDER BY\&.
1326
1335
.PP
1327
1336
The query planner takes
1477
1486
FOR UPDATE
1478
1487
or
1479
1488
FOR SHARE
1480
 
is used in a cursor\(aqs query, only rows actually fetched or stepped past by the cursor will be locked\&.
 
1489
is used in a cursor\*(Aqs query, only rows actually fetched or stepped past by the cursor will be locked\&.
1481
1490
.PP
1482
1491
When
1483
1492
FOR UPDATE
1548
1557
.PP
1549
1558
It is possible for a
1550
1559
SELECT
1551
 
command using
 
1560
command running at the
 
1561
READ COMMITTED
 
1562
transaction isolation level and using
1552
1563
ORDER BY
1553
1564
and
1554
1565
FOR UPDATE/SHARE
1578
1589
is combined with
1579
1590
LIMIT
1580
1591
or other restrictions\&. So this technique is recommended only if concurrent updates of the ordering columns are expected and a strictly sorted result is required\&.
 
1592
.PP
 
1593
At the
 
1594
REPEATABLE READ
 
1595
or
 
1596
SERIALIZABLE
 
1597
transaction isolation level this would cause a serialization failure (with a
 
1598
SQLSTATE
 
1599
of
 
1600
\*(Aq40001\*(Aq), so there is no possibility of receiving rows out of order under these isolation levels\&.
1581
1601
.sp .5v
1582
1602
.RE
1583
1603
.SS "TABLE Command"
1668
1688
SELECT kind, sum(len) AS total
1669
1689
    FROM films
1670
1690
    GROUP BY kind
1671
 
    HAVING sum(len) < interval \(aq5 hours\(aq;
 
1691
    HAVING sum(len) < interval \*(Aq5 hours\*(Aq;
1672
1692
 
1673
1693
   kind   | total
1674
1694
\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-
1729
1749
 
1730
1750
SELECT distributors\&.name
1731
1751
    FROM distributors
1732
 
    WHERE distributors\&.name LIKE \(aqW%\(aq
 
1752
    WHERE distributors\&.name LIKE \*(AqW%\*(Aq
1733
1753
UNION
1734
1754
SELECT actors\&.name
1735
1755
    FROM actors
1736
 
    WHERE actors\&.name LIKE \(aqW%\(aq;
 
1756
    WHERE actors\&.name LIKE \*(AqW%\*(Aq;
1737
1757
 
1738
1758
      name
1739
1759
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1821
1841
WITH RECURSIVE employee_recursive(distance, employee_name, manager_name) AS (
1822
1842
    SELECT 1, employee_name, manager_name
1823
1843
    FROM employee
1824
 
    WHERE manager_name = \(aqMary\(aq
 
1844
    WHERE manager_name = \*(AqMary\*(Aq
1825
1845
  UNION ALL
1826
1846
    SELECT er\&.distance + 1, e\&.employee_name, e\&.manager_name
1827
1847
    FROM employee_recursive er, employee e
1877
1897
.RS 4
1878
1898
.\}
1879
1899
.nf
1880
 
SELECT distributors\&.* WHERE distributors\&.name = \(aqWestward\(aq;
 
1900
SELECT distributors\&.* WHERE distributors\&.name = \*(AqWestward\*(Aq;
1881
1901
.fi
1882
1902
.if n \{\
1883
1903
.RE
1884
1904
.\}
1885
1905
.sp
1886
1906
PostgreSQL
1887
 
releases prior to 8\&.1 would accept queries of this form, and add an implicit entry to the query\(aqs
 
1907
releases prior to 8\&.1 would accept queries of this form, and add an implicit entry to the query\*(Aqs
1888
1908
FROM
1889
1909
clause for each table referenced by the query\&. This is no longer allowed\&.
1890
1910
.SS "Omitting the AS Key Word"
1921
1941
GROUP BY
1922
1942
clause can only use expressions based on input column names\&.
1923
1943
PostgreSQL
1924
 
extends each of these clauses to allow the other choice as well (but it uses the standard\(aqs interpretation if there is ambiguity)\&.
 
1944
extends each of these clauses to allow the other choice as well (but it uses the standard\*(Aqs interpretation if there is ambiguity)\&.
1925
1945
PostgreSQL
1926
1946
also allows both clauses to specify arbitrary expressions\&. Note that names appearing in an expression will always be taken as input\-column names, not as output\-column names\&.
1927
1947
.PP
1937
1957
 
1938
1958
PostgreSQL
1939
1959
recognizes functional dependency (allowing columns to be omitted from
1940
 
GROUP BY) only when a table\(aqs primary key is included in the
 
1960
GROUP BY) only when a table\*(Aqs primary key is included in the
1941
1961
GROUP BY
1942
1962
list\&. The SQL standard specifies additional conditions that should be recognized\&.
1943
1963
.SS "WINDOW Clause Restrictions"