From: Tom Lane Date: Mon, 17 Sep 2012 18:59:50 +0000 (-0400) Subject: Provide adequate documentation of the "table_name *" notation. X-Git-Tag: REL8_3_21~4 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=8bae564f6ac9c682960f181505e0025768a489d9;p=postgresql 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. --- diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 9591f7cd41..7ac7b98385 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -4648,11 +4648,23 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' inheritance - This controls the inheritance semantics. If turned off, - subtables are not included by various commands by default; basically - an implied ONLY key word. This was added for - compatibility with releases prior to 7.1. See - for more information. + This setting controls whether undecorated table references are + considered to include inheritance child tables. The default is + on, which means child tables are included (thus, + a * suffix is assumed by default). If turned + off, child tables are not included (thus, an + ONLY prefix is assumed). The SQL standard + requires child tables to be included, so the off setting + is not spec-compliant, but it is provided for compatibility with + PostgreSQL releases prior to 7.1. + See for more information. + + + + Turning sql_inheritance off is deprecated, because that + behavior has been found to be error-prone as well as contrary to SQL + standard. Discussions of inheritance behavior elsewhere in this + manual generally assume that it is on. diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 9823386630..37f0cbfddb 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -1995,6 +1995,23 @@ SELECT name, altitude ONLY keyword. + + You can also write the table name with a trailing * + to explicitly specify that descendant tables are included: + + +SELECT name, altitude + FROM cities* + WHERE altitude > 500; + + + Writing * is not necessary, since this behavior is + the default (unless you have changed the setting of the + configuration option). + However writing * might be useful to emphasize that + additional tables will be searched. + + In some cases you might wish to know which table a particular row originated from. There is a system column called @@ -2182,18 +2199,6 @@ VALUES ('New York', NULL, NULL, 'NY'); inheritance is useful for your problem. - - Deprecated - - In releases of PostgreSQL prior to 7.1, the - default behavior was not to include child tables in queries. This was - found to be error prone and also in violation of the SQL - standard. You can get the pre-7.1 behavior by turning off the - configuration - option. - - - diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index b5b5542d51..027768baf4 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -139,6 +139,16 @@ FROM table_reference , table_r — any columns added in subtables are ignored. + + Instead of writing ONLY before the table name, you can write + * after the table name to explicitly specify that descendant + tables are included. Writing * is not necessary since that + behavior is the default (unless you have changed the setting of the configuration option). However writing + * might be useful to emphasize that additional tables will be + searched. + + Joined Tables diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index d6bf184d64..2a1cd0027d 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -433,15 +433,12 @@ where action is one of: name - The name (possibly schema-qualified) of an existing table to - alter. If ONLY is specified, only that table is - altered. If ONLY is not specified, the table and all - its descendant tables (if any) are updated. * can be - appended to the table name to indicate that descendant tables are - to be altered, but in the current version, this is the default - behavior. (In releases before 7.1, ONLY was the - default behavior. The default can be altered by changing the - configuration parameter .) + The name (optionally schema-qualified) of an existing table to + alter. If ONLY is specified before the table name, only + that table is altered. If ONLY is not specified, the table + and all its descendant tables (if any) are altered. Optionally, + * can be specified after the table name to explicitly + indicate that descendant tables are included. diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index 6e3d9ff2c1..81e77fdf39 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -20,7 +20,7 @@ PostgreSQL documentation -DELETE FROM [ ONLY ] table [ [ AS ] alias ] +DELETE FROM [ ONLY ] table [ * ] [ [ AS ] alias ] [ USING usinglist ] [ WHERE condition | WHERE CURRENT OF cursor_name ] [ RETURNING * | output_expression [ AS output_name ] [, ...] ] @@ -45,13 +45,6 @@ DELETE FROM [ ONLY ] table [ [ AS ] - - By default, DELETE will delete rows in the - specified table and all its child tables. If you wish to delete only - from the specific table mentioned, you must use the - ONLY clause. - - There are two ways to delete rows in a table using information contained in other tables in the database: using sub-selects, or @@ -82,21 +75,17 @@ DELETE FROM [ ONLY ] table [ [ AS ] Parameters - - ONLY - - - If specified, delete rows from the named table only. When not - specified, any tables inheriting from the named table are also processed. - - - - table - The name (optionally schema-qualified) of an existing table. + The name (optionally schema-qualified) of the table to delete rows + from. If ONLY is specified before the table name, + matching rows are deleted from the named table only. If + ONLY is not specified, matching rows are also deleted + from any tables inheriting from the named table. Optionally, + * can be specified after the table name to explicitly + indicate that descendant tables are included. diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index b000dbb1f5..b3b6cfb2ec 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -184,16 +184,12 @@ where from_item can be one of: table_name - The name (optionally schema-qualified) of an existing table or - view. If ONLY is specified, only that table is - scanned. If ONLY is not specified, the table and - all its descendant tables (if any) are scanned. * - can be appended to the table name to indicate that descendant - tables are to be scanned, but in the current version, this is - the default behavior. (In releases before 7.1, - ONLY was the default behavior.) The default - behavior can be modified by changing the configuration option. + The name (optionally schema-qualified) of an existing table or view. + If ONLY is specified before the table name, only that + table is scanned. If ONLY is not specified, the table + and all its descendant tables (if any) are scanned. Optionally, + * can be specified after the table name to explicitly + indicate that descendant tables are included. diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index ce05150073..8f39a7d0c1 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -20,7 +20,7 @@ PostgreSQL documentation -UPDATE [ ONLY ] table [ [ AS ] alias ] +UPDATE [ ONLY ] table [ * ] [ [ AS ] alias ] SET { column = { expression | DEFAULT } | ( column [, ...] ) = ( { expression | DEFAULT } [, ...] ) } [, ...] [ FROM fromlist ] @@ -39,13 +39,6 @@ UPDATE [ ONLY ] table [ [ AS ] - - By default, UPDATE will update rows in the - specified table and all its subtables. If you wish to only update - the specific table mentioned, you must use the ONLY - clause. - - There are two ways to modify a table using information contained in other tables in the database: using sub-selects, or specifying @@ -82,6 +75,11 @@ UPDATE [ ONLY ] table [ [ AS ] The name (optionally schema-qualified) of the table to update. + If ONLY is specified before the table name, matching rows + are updated in the named table only. If ONLY is not + specified, matching rows are also updated in any tables inheriting from + the named table. Optionally, * can be specified after the + table name to explicitly indicate that descendant tables are included.