10000 Provide adequate documentation of the "table_name *" notation. · haying/postgres@c842673 · GitHub
[go: up one dir, main page]
Skip to content

Commit c842673

Browse files
tglsfdctglsfdc
committed
Provide adequate documentation of the "table_name *" notation.
Somewhere along the line, somebody decided to remove all trace of this notation from the documentation text. It was still in the command syntax synopses, or at least some of them, but with no indication what it meant. This will not do, as evidenced by the confusion apparent in bug #7543; even if the notation is now unnecessary, people will find it in legacy SQL code and need to know what it does.
1 parent 5010bbc commit c842673

File tree

9 files changed

+104
-73
lines changed

9 files changed

+104
-73
lines changed

‎doc/src/sgml/config.sgml

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4801,11 +4801,23 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
48014801
<indexterm><primary>inheritance</></>
48024802
<listitem>
48034803
<para>
4804-
This controls the inheritance semantics. If turned <literal>off</>,
4805-
subtables are not included by various commands by default; basically
4806-
an implied <literal>ONLY</literal> key word. This was added for
4807-
compatibility with releases prior to 7.1. See
4808-
<xref linkend="ddl-inherit"> for more information.
4804+
This setting controls whether undecorated table references are
4805+
considered to include inheritance child tables. The default is
4806+
<literal>on</>, which means child tables are included (thus,
4807+
a <literal>*</> suffix is assumed by default). If turned
4808+
<literal>off</>, child tables are not included (thus, an
4809+
<literal>ONLY</literal> prefix is assumed). The SQL standard
4810+
requires child tables to be included, so the <literal>off</> setting
4811+
is not spec-compliant, but it is provided for compatibility with
4812+
<productname>PostgreSQL</> releases prior to 7.1.
4813+
See <xref linkend="ddl-inherit"> for more information.
4814+
</para>
4815+
4816+
<para>
4817+
Turning <varname>sql_inheritance</> off is deprecated, because that
4818+
behavior has been found to be error-prone as well as contrary to SQL
4819+
standard. Discussions of inheritance behavior elsewhere in this
4820+
manual generally assume that it is <literal>on</>.
48094821
</para>
48104822
</listitem>
48114823
</varlistentry>

‎doc/src/sgml/ddl.sgml

Lines changed: 21 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1995,6 +1995,23 @@ SELECT name, altitude
19951995
<literal>ONLY</literal> keyword.
19961996
</para>
19971997

1998+
<para>
1999+
You can also write the table name with a trailing <literal>*</>
2000+
to explicitly specify that descendant tables are included:
2001+
2002+
<programlisting>
2003+
SELECT name, altitude
2004+
FROM cities*
2005+
WHERE altitude &gt; 500;
2006+
</programlisting>
2007+
2008+
Writing <literal>*</> is not necessary, since this behavior is
2009+
the default (unless you have changed the setting of the
2010+
<xref linkend="guc-sql-inheritance"> configuration option).
2011+
However writing <literal>*</> might be useful to emphasize that
2012+
additional tables will be searched.
2013+
</para>
2014+
19982015
<para>
19992016
In some cases you might wish to know which table a particular row
20002017
originated from. There is a system column called
@@ -2142,15 +2159,15 @@ VALUES ('New York', NULL, NULL, 'NY');
21422159
data modification, or schema modification
21432160
(e.g., <literal>SELECT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>,
21442161
most variants of <literal>ALTER TABLE</literal>, but
2145-
not <literal>INSERT</literal> and <literal>ALTER TABLE ...
2162+
not <literal>INSERT</literal> or <literal>ALTER TABLE ...
21462163
RENAME</literal>) typically default to including child tables and
21472164
support the <literal>ONLY</literal> notation to exclude them.
21482165
Commands that do database maintenance and tuning
21492166
(e.g., <literal>REINDEX</literal>, <literal>VACUUM</literal>)
2150-
typically only work on individual, physical tables and do no
2167+
typically only work on individual, physical tables and do not
21512168
support recursing over inheritance hierarchies. The respective
2152-
behavior of each individual command is documented in the reference
2153-
part (<xref linkend="sql-commands">).
2169+
behavior of each individual command is documented in its reference
2170+
page (<xref linkend="sql-commands">).
21542171
</para>
21552172

21562173
<para>
@@ -2200,18 +2217,6 @@ VALUES ('New York', NULL, NULL, 'NY');
22002217
inheritance is useful for your application.
22012218
</para>
22022219

2203-
<note>
2204-
<title>Deprecated</title>
2205-
<para>
2206-
In releases of <productname>PostgreSQL</productname> prior to 7.1, the
2207-
default behavior was not to include child tables in queries. This was
2208-
found to be error prone and also in violation of the SQL
2209-
standard. You can get the pre-7.1 behavior by turning off the
2210-
<xref linkend="guc-sql-inheritance"> configuration
2211-
option.
2212-
</para>
2213-
</note>
2214-
22152220
</sect2>
22162221
</sect1>
22172222

‎doc/src/sgml/queries.sgml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,16 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
140140
&mdash; any columns added in subtables are ignored.
141141
</para>
142142

143+
<para>
144+
Instead of writing <literal>ONLY</> before the table name, you can write
145+
<literal>*</> after the table name to explicitly specify that descendant
146+
tables are included. Writing <literal>*</> is not necessary since that
147+
behavior is the default (unless you have changed the setting of the <xref
148+
linkend="guc-sql-inheritance"> configuration option). However writing
149+
<literal>*</> might be useful to emphasize that additional tables will be
150+
searched.
151+
</para>
152+
143153
<sect3 id="queries-join">
144154
<title>Joined Tables</title>
145155

‎doc/src/sgml/ref/alter_table.sgml

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -449,10 +449,12 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
449449
<term><replaceable class="PARAMETER">name</replaceable></term>
450450
<listitem>
451451
<para>
452-
The name (possibly schema-qualified) of an existing table to
453-
alter. If <literal>ONLY</> is specified, only that table is
454-
altered. If <literal>ONLY</> is not specified, the table and any
455-
descendant tables are altered.
452+
The name (optionally schema-qualified) of an existing table to
453+
alter. If <literal>ONLY</> is specified before the table name, only
454+
that table is altered. If <literal>ONLY</> is not specified, the table
455+
and all its descendant tables (if any) are altered. Optionally,
456+
<literal>*</> can be specified after the table name to explicitly
457+
indicate that descendant tables are included.
456458
</para>
457459
</listitem>
458460
</varlistentry>
@@ -833,7 +835,7 @@ ALTER TABLE distributors DROP CONSTRAINT zipchk;
833835
</para>
834836

835837
<para>
836-
To remove a check constraint from a table only:
838+
To remove a check constraint from one table only:
837839
<programlisting>
838840
ALTER TABLE ONLY distributors DROP CONSTRAINT zipchk;
839841
</programlisting>

‎doc/src/sgml/ref/delete.sgml

Lines changed: 8 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ PostgreSQL documentation
2121

2222
<refsynopsisdiv>
2323
<synopsis>
24-
DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
24+
DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
2525
[ USING <replaceable class="PARAMETER">usinglist</replaceable> ]
2626
[ WHERE <replaceable class="PARAMETER">condition</replaceable> | WHERE CURRENT OF <replaceable class="PARAMETER">cursor_name</replaceable> ]
2727
[ RETURNING * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] [, ...] ]
@@ -46,13 +46,6 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ]
4646
</para>
4747
</tip>
4848

49-
<para>
50-
By default, <command>DELETE</command> will delete rows in the
51-
specified table and all its child tables. If you wish to delete only
52-
from the specific table mentioned, you must use the
53-
<literal>ONLY</literal> clause.
54-
</para>
55-
5649
<para>
5750
There are two ways to delete rows in a table using information
5851
contained in other tables in the database: using sub-selects, or
@@ -83,21 +76,17 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ]
8376
<title>Parameters</title>
8477

8578
<variablelist>
86-
<varlistentry>
87-
<term><literal>ONLY</></term>
88-
<listitem>
89-
<para>
90-
If specified, delete rows from the named table only. When not
91-
specified, any tables inheriting from the named table are also processed.
92-
</para>
93-
</listitem>
94-
</varlistentry>
95-
9679
<varlistentry>
9780
<term><replaceable class="parameter">table</replaceable></term>
9881
<listitem>
9982
<para>
100-
The name (optionally schema-qualified) of an existing table.
83+
The name (optionally schema-qualified) of the table to delete rows
84+
from. If <literal>ONLY</> is specified before the table name,
85+
matching rows are deleted from the named table only. If
86+
<literal>ONLY</> is not specified, matching rows are also deleted
87+
from any tables inheriting from the named table. Optionally,
88+
<literal>*</> can be specified after the table name to explicitly
89+
indicate that descendant tables are included.
10190
</para>
10291
</listitem>
10392
</varlistentry>

‎doc/src/sgml/ref/lock.sgml

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ PostgreSQL documentation
2121

2222
<refsynopsisdiv>
2323
<synopsis>
24-
LOCK [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [, ...] [ IN <replaceable class="PARAMETER">lockmode</replaceable> MODE ] [ NOWAIT ]
24+
LOCK [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [ * ] [, ...] [ IN <replaceable class="PARAMETER">lockmode</replaceable> MODE ] [ NOWAIT ]
2525

2626
where <replaceable class="PARAMETER">lockmode</replaceable> is one of:
2727

@@ -109,9 +109,11 @@ where <replaceable class="PARAMETER">lockmode</replaceable> is one of:
109109
<listitem>
110110
<para>
111111
The name (optionally schema-qualified) of an existing table to
112-
lock. If <literal>ONLY</> is specified, only that table is
113-
locked. If <literal>ONLY</> is not specified, the table and all
114-
its descendant tables (if any) are locked.
112+
lock. If <literal>ONLY</> is specified before the table name, only that
113+
table is locked. If <literal>ONLY</> is not specified, the table and all
114+
its descendant tables (if any) are locked. Optionally, <literal>*</>
115+
can be specified after the table name to explicitly indicate that
116+
descendant tables are included.
115117
</para>
116118

117119
<para>

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

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -268,10 +268,12 @@ TABLE { [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] |
268268
<term><replaceable class="parameter">table_name</replaceable></term>
269269
<listitem>
270270
<para>
271-
The name (optionally schema-qualified) of an existing table or
272-
view. If <literal>ONLY</> is specified, only that table is
273-
scanned. If <literal>ONLY</> is not specified, the table and
274-
any descendant tables are scanned.
271+
The name (optionally schema-qualified) of an existing table or view.
272+
If <literal>ONLY</> is specified before the table name, only that
273+
table is scanned. If <literal>ONLY</> is not specified, the table
274+
and all its descendant tables (if any) are scanned. Optionally,
275+
<literal>*</> can be specified after the table name to explicitly
276+
indicate that descendant tables are included.
275277
</para>
276278
</listitem>
277279
</varlistentry>
@@ -1488,15 +1490,24 @@ SELECT distributors.* WHERE distributors.name = 'Westward';
14881490
</refsect2>
14891491

14901492
<refsect2>
1491-
<title><literal>ONLY</literal> and Parentheses</title>
1493+
<title><literal>ONLY</literal> and Inheritance</title>
14921494

14931495
<para>
1494-
The SQL standard requires parentheses around the table name
1495-
after <literal>ONLY</literal>, as in <literal>SELECT * FROM ONLY
1496-
(tab1), ONLY (tab2) WHERE ...</literal>. PostgreSQL supports that
1497-
as well, but the parentheses are optional. (This point applies
1498-
equally to all SQL commands supporting the <literal>ONLY</literal>
1499-
option.)
1496+
The SQL standard requires parentheses around the table name when
1497+
writing <literal>ONLY</literal>, for example <literal>SELECT * FROM ONLY
1498+
(tab1), ONLY (tab2) WHERE ...</literal>. <productname>PostgreSQL</>
1499+
considers these parentheses to be optional.
1500+
</para>
1501+
1502+
<para>
1503+
<productname>PostgreSQL</> allows a trailing <literal>*</> to be written to
1504+
explicitly specify the non-<literal>ONLY</literal> behavior of including
1505+
child tables. The standard does not allow this.
1506+
</para>
1507+
1508+
<para>
1509+
(These points apply equally to all SQL commands supporting the
1510+
<literal>ONLY</literal> option.)
15001511
</para>
15011512
</refsect2>
15021513

‎doc/src/sgml/ref/truncate.sgml

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ PostgreSQL documentation
2121

2222
<refsynopsisdiv>
2323
<synopsis>
24-
TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [, ... ]
24+
TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [ * ] [, ... ]
2525
[ RESTART IDENTITY | CONTINUE IDENTITY ] [ CASCADE | RESTRICT ]
2626
</synopsis>
2727
</refsynopsisdiv>
@@ -47,10 +47,12 @@ TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [,
4747
<term><replaceable class="PARAMETER">name</replaceable></term>
4848
<listitem>
4949
<para>
50-
The name (optionally schema-qualified) of a table to be
51-
truncated. If <literal>ONLY</> is specified, only that table is
52-
truncated. If <literal>ONLY</> is not specified, the table and
53-
all its descendant tables (if any) are truncated.
50+
The name (optionally schema-qualified) of a table to truncate.
51+
If <literal>ONLY</> is specified before the table name, only that table
52+
is truncated. If <literal>ONLY</> is not specified, the table and all
53+
its descendant tables (if any) are truncated. Optionally, <literal>*</>
54+
can be specified after the table name to explicitly indicate that
55+
descendant tables are included.
5456
</para>
5557
</listitem>
5658
</varlistentry>

‎doc/src/sgml/ref/update.sgml

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ PostgreSQL documentation
2121

2222
<refsynopsisdiv>
2323
<synopsis>
24-
UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
24+
UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
2525
SET { <replaceable class="PARAMETER">column</replaceable> = { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } |
2626
( <replaceable class="PARAMETER">column</replaceable> [, ...] ) = ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) } [, ...]
2727
[ FROM <replaceable class="PARAMETER">fromlist</replaceable> ]
@@ -40,13 +40,6 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <rep
4040
columns not explicitly modified retain their previous values.
4141
</para>
4242

43-
<para>
44-
By default, <command>UPDATE</command> will update rows in the
45-
specified table and all its subtables. If you wish to only update
46-
the specific table mentioned, you must use the <literal>ONLY</>
47-
clause.
48-
</para>
49-
5043
<para>
5144
There are two ways to modify a table using information contained in
5245
other tables in the database: using sub-selects, or specifying
@@ -84,6 +77,11 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <rep
8477
<listitem>
8578
<para>
8679
The name (optionally schema-qualified) of the table to update.
80+
If <literal>ONLY</> is specified before the table name, matching rows
81+
are updated in the named table only. If <literal>ONLY</> is not
82+
specified, matching rows are also updated in any tables inheriting from
83+
the named table. Optionally, <literal>*</> can be specified after the
84+
table name to explicitly indicate that descendant tables are included.
8785
</para>
8886
</listitem>
8987
</varlistentry>

0 commit comments

Comments
 (0)
0