On Mon, Dec 28, 2020 at 02:32:35AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/13/executor.html
> Description:
>
> It's located within the parentheses of the last paragraph.
>
> >(A simple INSERT ... VALUES command creates a trivial plan tree consisting
> of a single Result node, which computes just one result row, and ModifyTable
> above it to perform the insertion. But INSERT ... SELECT can demand the full
> power of the executor mechanism.)
>
> I'm under the impression that the second inline code block refers to `INSERT
> ... VALUES`.
I think the text is correct, but I also think it is trying to do too
much in one paragraph. Here is a doc patch to improve this.
--
Bruce Momjian <br...@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
diff --git a/doc/src/sgml/arch-dev.sgml b/doc/src/sgml/arch-dev.sgml
new file mode 100644
index 7883c3c..ade0ad9
*** a/doc/src/sgml/arch-dev.sgml
--- b/doc/src/sgml/arch-dev.sgml
***************
*** 529,554 ****
</para>
<para>
! The executor mechanism is used to evaluate all four basic SQL query types:
! <command>SELECT</command>, <command>INSERT</command>, <command>UPDATE</command>, and
! <command>DELETE</command>. For <command>SELECT</command>, the top-level executor
! code only needs to send each row returned by the query plan tree off
! to the client. For <command>INSERT</command>, each returned row is inserted
! into the target table specified for the <command>INSERT</command>. This is
! done in a special top-level plan node called <literal>ModifyTable</literal>.
! (A simple
! <command>INSERT ... VALUES</command> command creates a trivial plan tree
! consisting of a single <literal>Result</literal> node, which computes just one
! result row, and <literal>ModifyTable</literal> above it to perform the insertion.
! But <command>INSERT ... SELECT</command> can demand the full power
! of the executor mechanism.) For <command>UPDATE</command>, the planner arranges
! that each computed row includes all the updated column values, plus
! the <firstterm>TID</firstterm> (tuple ID, or row ID) of the original target row;
! this data is fed into a <literal>ModifyTable</literal> node, which uses the
! information to create a new updated row and mark the old row deleted.
! For <command>DELETE</command>, the only column that is actually returned by the
! plan is the TID, and the <literal>ModifyTable</literal> node simply uses the TID
! to visit each target row and mark it deleted.
</para>
</sect1>
--- 529,564 ----
</para>
<para>
! The executor mechanism is used to evaluate all four basic SQL query
! types: <command>SELECT</command>, <command>INSERT</command>,
! <command>UPDATE</command>, and <command>DELETE</command>.
! For <command>SELECT</command>, the top-level executor code
! only needs to send each row returned by the query plan tree
! off to the client. <command>INSERT ... SELECT</command>,
! <command>UPDATE</command>, and <command>DELETE</command>
! are effectively <command>SELECT</command>s under a special
! top-level plan node called <literal>ModifyTable</literal>.
! </para>
!
! <para>
! <command>INSERT ... SELECT</command> feeds the rows up
! to <literal>ModifyTable</literal> for insertion. For
! <command>UPDATE</command>, the planner arranges that each
! computed row includes all the updated column values, plus the
! <firstterm>TID</firstterm> (tuple ID, or row ID) of the original
! target row; this data is fed up to the <literal>ModifyTable</literal>
! node, which uses the information to create a new updated row and
! mark the old row deleted. For <command>DELETE</command>, the only
! column that is actually returned by the plan is the TID, and the
! <literal>ModifyTable</literal> node simply uses the TID to visit each
! target row and mark it deleted.
! </para>
!
! <para>
! A simple <command>INSERT ... VALUES</command> command creates a
! trivial plan tree consisting of a single <literal>Result</literal>
! node, which computes just one result row, feeding that up
! to<literal>ModifyTable</literal> to perform the insertion.
</para>
</sect1>
