public inbox for [email protected]
help / color / mirror / Atom feedUpdate wording of INSERT ON CONFLICT "rows proposed for insertion"
2+ messages / 1 participants
[nested] [flat]
* Update wording of INSERT ON CONFLICT "rows proposed for insertion"
@ 2022-03-09 00:14 David G. Johnston <[email protected]>
2022-04-12 03:21 ` Re: Update wording of INSERT ON CONFLICT "rows proposed for insertion" David G. Johnston <[email protected]>
0 siblings, 1 reply; 2+ messages in thread
From: David G. Johnston @ 2022-03-09 00:14 UTC (permalink / raw)
To: Pg Docs <[email protected]>
Hey,
I suggest a minor rewording of:
https://www.postgresql.org/docs/devel/sql-insert.html
Current:
"The SET and WHERE clauses in ON CONFLICT DO UPDATE have access to the
existing row using the table's name (or an alias), and to [rows] proposed
for insertion using the special excluded table."
Becomes:
"The SET and WHERE clauses in ON CONFLICT DO UPDATE have access to the
existing row using the table's name (or an alias), and to [the
corresponding row] proposed for insertion using the special excluded table."
The plural "rows" just reads oddly since in any single evaluation only one
row is going to be present in the excluded table for the "existing row" in
the target table.
David J.
^ permalink raw reply [nested|flat] 2+ messages in thread
* Re: Update wording of INSERT ON CONFLICT "rows proposed for insertion"
2022-03-09 00:14 Update wording of INSERT ON CONFLICT "rows proposed for insertion" David G. Johnston <[email protected]>
@ 2022-04-12 03:21 ` David G. Johnston <[email protected]>
0 siblings, 0 replies; 2+ messages in thread
From: David G. Johnston @ 2022-04-12 03:21 UTC (permalink / raw)
To: Pg Docs <[email protected]>
On Tue, Mar 8, 2022 at 5:14 PM David G. Johnston <[email protected]>
wrote:
>
> I suggest a minor rewording of:
>
> https://www.postgresql.org/docs/devel/sql-insert.html
>
>
Concretely as attached. I did a bit more than minor work - I decided that
actually calling it a table in the docs didn't really fit how it behaves in
practice and so reworded the "table" into just "name". Please see the
commit message for more exposition.
David J.
Attachments:
[application/octet-stream] v0001-on-conflict-excluded-is-name-not-table.patch (3.3K, 3-v0001-on-conflict-excluded-is-name-not-table.patch)
download | inline diff:
commit 3ae125aafb5bad062952be1e9f97cb2288350f5b
Author: David G. Johnston <[email protected]>
Date: Tue Apr 12 02:51:18 2022 +0000
doc: For INSERT ON CONFLICT excluded is a only a name, not a table.
As one cannot place excluded in a FROM clause (subquery) in the
ON CONFLICT clause referring to it as a table, with plural rows
nonetheless, leads the reader to infer more about what the
behavior here is than is correct. We already just say use the
table's name for the existing row so just match that pattern
of using the name excluded for the proposed row.
The alias description doesn't have the same issue regarding the
use of the word table and rows, as the use there is more conceptual,
but the wording about "otherwise taken as" is wrong: rather two
labels of excluded end up in scope and you get an ambigious name error.
The error messages still consider excluded to be a table reference
and this patch does not try to change that. That implementation
detail need not force the user-facing documentation for the feature
to use the term table when it doesn't really apply.
diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index a9af9959c0..0fad1d3640 100644
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -175,9 +175,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
class="parameter">table_name</replaceable>. When an alias is
provided, it completely hides the actual name of the table.
This is particularly useful when <literal>ON CONFLICT DO UPDATE</literal>
- targets a table named <varname>excluded</varname>, since that will otherwise
- be taken as the name of the special table representing rows proposed
- for insertion.
+ targets a table named <varname>excluded</varname>, since that will
+ conflict with the special name representing the row proposed for insertion.
</para>
</listitem>
</varlistentry>
@@ -396,8 +395,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
conflict. The <literal>SET</literal> and
<literal>WHERE</literal> clauses in <literal>ON CONFLICT DO
UPDATE</literal> have access to the existing row using the
- table's name (or an alias), and to rows proposed for insertion
- using the special <varname>excluded</varname> table.
+ table's name (or an alias), and to the proposed row
+ using the name <varname>excluded</varname>.
<literal>SELECT</literal> privilege is required on any column in the
target table where corresponding <varname>excluded</varname>
columns are read.
@@ -699,8 +698,8 @@ INSERT INTO employees_log SELECT *, current_timestamp FROM upd;
<para>
Insert or update new distributors as appropriate. Assumes a unique
index has been defined that constrains values appearing in the
- <literal>did</literal> column. Note that the special
- <varname>excluded</varname> table is used to reference values originally
+ <literal>did</literal> column. Note that the name
+ <varname>excluded</varname> is used to reference values originally
proposed for insertion:
<programlisting>
INSERT INTO distributors (did, dname)
^ permalink raw reply [nested|flat] 2+ messages in thread
end of thread, other threads:[~2022-04-12 03:21 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-03-09 00:14 Update wording of INSERT ON CONFLICT "rows proposed for insertion" David G. Johnston <[email protected]>
2022-04-12 03:21 ` David G. Johnston <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox