On Thu, Feb 13, 2020 at 11:26:45AM -0500, Tom Lane wrote:
> I see where you're coming from, but I do not think that repeating the
> whole from_item syntax in UPDATE and DELETE is the best way forward.
> In the first place, we'd inevitably forget to update those copies,
> and in the second, I'm not sure that the syntax is all that helpful
> without all the supporting text in the SELECT ref page --- which
> surely we aren't going to duplicate.
>
> I think the real problem with the places Alexey is on about is that
> they're too waffle-y. They use wording like "similar to", leaving
> one wondering what discrepancies exist but are being papered over.
> In point of fact, as a look into gram.y will show, what you can
> write after UPDATE ... FROM or DELETE ... USING is *exactly* the
> same thing as what you can write after SELECT ... FROM. So what
> I'm in favor of here is:
>
> * Change the synopsis entries to look like "FROM from_item [, ...]"
> and "USING from_item [, ...]", so that they match the SELECT
> synopsis exactly.
>
> * In the text, describe from_item as being exactly the same as
> it is in SELECT.
>
> (Compare the handling of with_query, which has pretty much the
> same problem of being way too complex to document three times.)
I have implemented the ideas above in the attached patch. I have
synchronized the syntax to match SELECT, and synchronized the paragraphs
describing the item.
--
Bruce Momjian <[email protected]> https://momjian.us
EnterpriseDB https://enterprisedb.com
+ As you are, so once was I. As I am, so you will be. +
+ Ancient Roman grave inscription +
diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml
index df8cea48cf..9f0ef0e681 100644
--- a/doc/src/sgml/ref/delete.sgml
+++ b/doc/src/sgml/ref/delete.sgml
@@ -23,7 +23,7 @@ PostgreSQL documentation
<synopsis>
[ WITH [ RECURSIVE ] <replaceable class="parameter">with_query</replaceable> [, ...] ]
DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
- [ USING <replaceable class="parameter">using_list</replaceable> ]
+ [ USING <replaceable class="parameter">using_item</replaceable> [, ...] ]
[ WHERE <replaceable class="parameter">condition</replaceable> | WHERE CURRENT OF <replaceable class="parameter">cursor_name</replaceable> ]
[ RETURNING * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] [, ...] ]
</synopsis>
@@ -117,17 +117,18 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ *
</varlistentry>
<varlistentry>
- <term><replaceable class="parameter">using_list</replaceable></term>
+ <term><replaceable class="parameter">using_item</replaceable></term>
<listitem>
<para>
- A list of table expressions, allowing columns from other tables
- to appear in the <literal>WHERE</literal> condition. This is similar
- to the list of tables that can be specified in the <xref
- linkend="sql-from" endterm="sql-from-title"/> of a
- <command>SELECT</command> statement; for example, an alias for
- the table name can be specified. Do not repeat the target table
- in the <replaceable class="parameter">using_list</replaceable>,
- unless you wish to set up a self-join.
+ A table expression allowing columns from other tables to appear
+ in the <literal>WHERE</literal> condition. This is the same as
+ the table that can be specified in the <xref linkend="sql-from"
+ endterm="sql-from-title"/> of a <command>SELECT</command>
+ statement; for example, an alias for the table name can be
+ specified. Do not repeat the target table as a <replaceable
+ class="parameter">using_item</replaceable> unless you wish to set
+ up a self-join (in which case it must appear with an alias in the
+ <replaceable>using_item</replaceable>).
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index f58dcd8877..d1e74a7c3b 100644
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -27,7 +27,7 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [
( <replaceable class="parameter">column_name</replaceable> [, ...] ) = [ ROW ] ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) |
( <replaceable class="parameter">column_name</replaceable> [, ...] ) = ( <replaceable class="parameter">sub-SELECT</replaceable> )
} [, ...]
- [ FROM <replaceable class="parameter">from_list</replaceable> ]
+ [ FROM <replaceable class="parameter">from_item</replaceable> [, ...] ]
[ WHERE <replaceable class="parameter">condition</replaceable> | WHERE CURRENT OF <replaceable class="parameter">cursor_name</replaceable> ]
[ RETURNING * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] [, ...] ]
</synopsis>
@@ -164,17 +164,18 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [
</varlistentry>
<varlistentry>
- <term><replaceable class="parameter">from_list</replaceable></term>
+ <term><replaceable class="parameter">from_item</replaceable></term>
<listitem>
<para>
- A list of table expressions, allowing columns from other tables
- to appear in the <literal>WHERE</literal> condition and the update
- expressions. This is similar to the list of tables that can be
- specified in the <xref linkend="sql-from"
- endterm="sql-from-title"/> of a <command>SELECT</command>
- statement. Note that the target table must not appear in the
- <replaceable>from_list</replaceable>, unless you intend a self-join (in which
- case it must appear with an alias in the <replaceable>from_list</replaceable>).
+ A table expression allowing columns from other tables to
+ appear in the <literal>WHERE</literal> condition and update
+ expressions. This is the same as the table that can be specified
+ in the <xref linkend="sql-from" endterm="sql-from-title"/> of a
+ <command>SELECT</command> statement; for example, an alias for
+ the table name can be specified. Do not repeat the target table
+ as a <replaceable>from_item</replaceable> unless you intend a
+ self-join (in which case it must appear with an alias in the
+ <replaceable>from_item</replaceable>).
</para>
</listitem>
</varlistentry>
@@ -264,7 +265,7 @@ UPDATE <replaceable class="parameter">count</replaceable>
<para>
When a <literal>FROM</literal> clause is present, what essentially happens
is that the target table is joined to the tables mentioned in the
- <replaceable>from_list</replaceable>, and each output row of the join
+ <replaceable>from_item</replaceable> list, and each output row of the join
represents an update operation for the target table. When using
<literal>FROM</literal> you should ensure that the join
produces at most one output row for each row to be modified. In
