Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit3440583

Browse files
committed
Provide adequate documentation of the "table_name *" notation.
Somewhere along the line, somebody decided to remove all trace of thisnotation from the documentation text. It was still in the command syntaxsynopses, 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 legacySQL code and need to know what it does.
1 parent25560fd commit3440583

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
@@ -5574,11 +5574,23 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
55745574
<indexterm><primary>inheritance</></>
55755575
<listitem>
55765576
<para>
5577-
This controls the inheritance semantics. If turned <literal>off</>,
5578-
subtables are not accessed by various commands by default; basically
5579-
an implied <literal>ONLY</literal> key word. This was added for
5580-
compatibility with releases prior to 7.1. See
5581-
<xref linkend="ddl-inherit"> for more information.
5577+
This setting controls whether undecorated table references are
5578+
considered to include inheritance child tables. The default is
5579+
<literal>on</>, which means child tables are included (thus,
5580+
a <literal>*</> suffix is assumed by default). If turned
5581+
<literal>off</>, child tables are not included (thus, an
5582+
<literal>ONLY</literal> prefix is assumed). The SQL standard
5583+
requires child tables to be included, so the <literal>off</> setting
5584+
is not spec-compliant, but it is provided for compatibility with
5585+
<productname>PostgreSQL</> releases prior to 7.1.
5586+
See <xref linkend="ddl-inherit"> for more information.
5587+
</para>
5588+
5589+
<para>
5590+
Turning <varname>sql_inheritance</> off is deprecated, because that
5591+
behavior has been found to be error-prone as well as contrary to SQL
5592+
standard. Discussions of inheritance behavior elsewhere in this
5593+
manual generally assume that it is <literal>on</>.
55825594
</para>
55835595
</listitem>
55845596
</varlistentry>

‎doc/src/sgml/ddl.sgml

Lines changed: 21 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2062,6 +2062,23 @@ SELECT name, altitude
20622062
<literal>ONLY</literal> keyword.
20632063
</para>
20642064

2065+
<para>
2066+
You can also write the table name with a trailing <literal>*</>
2067+
to explicitly specify that descendant tables are included:
2068+
2069+
<programlisting>
2070+
SELECT name, altitude
2071+
FROM cities*
2072+
WHERE altitude &gt; 500;
2073+
</programlisting>
2074+
2075+
Writing <literal>*</> is not necessary, since this behavior is
2076+
the default (unless you have changed the setting of the
2077+
<xref linkend="guc-sql-inheritance"> configuration option).
2078+
However writing <literal>*</> might be useful to emphasize that
2079+
additional tables will be searched.
2080+
</para>
2081+
20652082
<para>
20662083
In some cases you might wish to know which table a particular row
20672084
originated from. There is a system column called
@@ -2209,15 +2226,15 @@ VALUES ('New York', NULL, NULL, 'NY');
22092226
data modification, or schema modification
22102227
(e.g., <literal>SELECT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>,
22112228
most variants of <literal>ALTER TABLE</literal>, but
2212-
not <literal>INSERT</literal>and <literal>ALTER TABLE ...
2229+
not <literal>INSERT</literal>or <literal>ALTER TABLE ...
22132230
RENAME</literal>) typically default to including child tables and
22142231
support the <literal>ONLY</literal> notation to exclude them.
22152232
Commands that do database maintenance and tuning
22162233
(e.g., <literal>REINDEX</literal>, <literal>VACUUM</literal>)
2217-
typically only work on individual, physical tables and dono
2234+
typically only work on individual, physical tables and donot
22182235
support recursing over inheritance hierarchies. The respective
2219-
behavior of each individual command is documented inthe reference
2220-
part (<xref linkend="sql-commands">).
2236+
behavior of each individual command is documented inits reference
2237+
page (<xref linkend="sql-commands">).
22212238
</para>
22222239

22232240
<para>
@@ -2267,18 +2284,6 @@ VALUES ('New York', NULL, NULL, 'NY');
22672284
inheritance is useful for your application.
22682285
</para>
22692286

2270-
<note>
2271-
<title>Deprecated</title>
2272-
<para>
2273-
In releases of <productname>PostgreSQL</productname> prior to 7.1, the
2274-
default behavior was not to include child tables in queries. This was
2275-
found to be error prone and also in violation of the SQL
2276-
standard. You can get the pre-7.1 behavior by turning off the
2277-
<xref linkend="guc-sql-inheritance"> configuration
2278-
option.
2279-
</para>
2280-
</note>
2281-
22822287
</sect2>
22832288
</sect1>
22842289

‎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
@@ -604,10 +604,12 @@ ALTER TABLE <replaceable class="PARAMETER">name</replaceable>
604604
<term><replaceable class="PARAMETER">name</replaceable></term>
605605
<listitem>
606606
<para>
607-
The name (possibly schema-qualified) of an existing table to
608-
alter. If <literal>ONLY</> is specified, only that table is
609-
altered. If <literal>ONLY</> is not specified, the table and any
610-
descendant tables are altered.
607+
The name (optionally schema-qualified) of an existing table to
608+
alter. If <literal>ONLY</> is specified before the table name, only
609+
that table is altered. If <literal>ONLY</> is not specified, the table
610+
and all its descendant tables (if any) are altered. Optionally,
611+
<literal>*</> can be specified after the table name to explicitly
612+
indicate that descendant tables are included.
611613
</para>
612614
</listitem>
613615
</varlistentry>
@@ -989,7 +991,7 @@ ALTER TABLE distributors DROP CONSTRAINT zipchk;
989991
</para>
990992

991993
<para>
992-
To remove a check constraint froma table only:
994+
To remove a check constraint fromone table only:
993995
<programlisting>
994996
ALTER TABLE ONLY distributors DROP CONSTRAINT zipchk;
995997
</programlisting>

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

Lines changed: 8 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<synopsis>
2424
[ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ]
25-
DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
25+
DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [* ] [[ AS ] <replaceable class="parameter">alias</replaceable> ]
2626
[ USING <replaceable class="PARAMETER">using_list</replaceable> ]
2727
[ WHERE <replaceable class="PARAMETER">condition</replaceable> | WHERE CURRENT OF <replaceable class="PARAMETER">cursor_name</replaceable> ]
2828
[ RETURNING * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] [, ...] ]
@@ -47,13 +47,6 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ]
4747
</para>
4848
</tip>
4949

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

99-
<varlistentry>
100-
<term><literal>ONLY</></term>
101-
<listitem>
102-
<para>
103-
If specified, delete rows from the named table only. When not
104-
specified, any tables inheriting from the named table are also processed.
105-
</para>
106-
</listitem>
107-
</varlistentry>
108-
10992
<varlistentry>
11093
<term><replaceable class="parameter">table</replaceable></term>
11194
<listitem>
11295
<para>
113-
The name (optionally schema-qualified) of an existing table.
96+
The name (optionally schema-qualified) of the table to delete rows
97+
from. If <literal>ONLY</> is specified before the table name,
98+
matching rows are deleted from the named table only. If
99+
<literal>ONLY</> is not specified, matching rows are also deleted
100+
from any tables inheriting from the named table. Optionally,
101+
<literal>*</> can be specified after the table name to explicitly
102+
indicate that descendant tables are included.
114103
</para>
115104
</listitem>
116105
</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
<phrase>where <replaceable class="PARAMETER">lockmode</replaceable> is one of:</phrase>
2727

@@ -111,9 +111,11 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [, ...
111111
<listitem>
112112
<para>
113113
The name (optionally schema-qualified) of an existing table to
114-
lock. If <literal>ONLY</> is specified, only that table is
115-
locked. If <literal>ONLY</> is not specified, the table and all
116-
its descendant tables (if any) are locked.
114+
lock. If <literal>ONLY</> is specified before the table name, only that
115+
table is locked. If <literal>ONLY</> is not specified, the table and all
116+
its descendant tables (if any) are locked. Optionally, <literal>*</>
117+
can be specified after the table name to explicitly indicate that
118+
descendant tables are included.
117119
</para>
118120

119121
<para>

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

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -298,10 +298,12 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
298298
<term><replaceable class="parameter">table_name</replaceable></term>
299299
<listitem>
300300
<para>
301-
The name (optionally schema-qualified) of an existing table or
302-
view. If <literal>ONLY</> is specified, only that table is
303-
scanned. If <literal>ONLY</> is not specified, the table and
304-
any descendant tables are scanned.
301+
The name (optionally schema-qualified) of an existing table or view.
302+
If <literal>ONLY</> is specified before the table name, only that
303+
table is scanned. If <literal>ONLY</> is not specified, the table
304+
and all its descendant tables (if any) are scanned. Optionally,
305+
<literal>*</> can be specified after the table name to explicitly
306+
indicate that descendant tables are included.
305307
</para>
306308
</listitem>
307309
</varlistentry>
@@ -1598,15 +1600,24 @@ SELECT distributors.* WHERE distributors.name = 'Westward';
15981600
</refsect2>
15991601

16001602
<refsect2>
1601-
<title><literal>ONLY</literal> andParentheses</title>
1603+
<title><literal>ONLY</literal> andInheritance</title>
16021604

16031605
<para>
1604-
The SQL standard requires parentheses around the table name
1605-
after <literal>ONLY</literal>, as in <literal>SELECT * FROM ONLY
1606-
(tab1), ONLY (tab2) WHERE ...</literal>. PostgreSQL supports that
1607-
as well, but the parentheses are optional. (This point applies
1608-
equally to all SQL commands supporting the <literal>ONLY</literal>
1609-
option.)
1606+
The SQL standard requires parentheses around the table name when
1607+
writing <literal>ONLY</literal>, for example <literal>SELECT * FROM ONLY
1608+
(tab1), ONLY (tab2) WHERE ...</literal>. <productname>PostgreSQL</>
1609+
considers these parentheses to be optional.
1610+
</para>
1611+
1612+
<para>
1613+
<productname>PostgreSQL</> allows a trailing <literal>*</> to be written to
1614+
explicitly specify the non-<literal>ONLY</literal> behavior of including
1615+
child tables. The standard does not allow this.
1616+
</para>
1617+
1618+
<para>
1619+
(These points apply equally to all SQL commands supporting the
1620+
<literal>ONLY</literal> option.)
16101621
</para>
16111622
</refsect2>
16121623

‎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
@@ -22,7 +22,7 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<synopsis>
2424
[ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ]
25-
UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
25+
UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [* ] [[ AS ] <replaceable class="parameter">alias</replaceable> ]
2626
SET { <replaceable class="PARAMETER">column</replaceable> = { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } |
2727
( <replaceable class="PARAMETER">column</replaceable> [, ...] ) = ( { <replaceable class="PARAMETER">expression</replaceable> | DEFAULT } [, ...] ) } [, ...]
2828
[ FROM <replaceable class="PARAMETER">from_list</replaceable> ]
@@ -41,13 +41,6 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <rep
4141
columns not explicitly modified retain their previous values.
4242
</para>
4343

44-
<para>
45-
By default, <command>UPDATE</command> will update rows in the
46-
specified table and all its subtables. If you wish to only update
47-
the specific table mentioned, you must use the <literal>ONLY</>
48-
clause.
49-
</para>
50-
5144
<para>
5245
There are two ways to modify a table using information contained in
5346
other tables in the database: using sub-selects, or specifying
@@ -97,6 +90,11 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <rep
9790
<listitem>
9891
<para>
9992
The name (optionally schema-qualified) of the table to update.
93+
If <literal>ONLY</> is specified before the table name, matching rows
94+
are updated in the named table only. If <literal>ONLY</> is not
95+
specified, matching rows are also updated in any tables inheriting from
96+
the named table. Optionally, <literal>*</> can be specified after the
97+
table name to explicitly indicate that descendant tables are included.
10098
</para>
10199
</listitem>
102100
</varlistentry>

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp