Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1kv2wX-0004Ot-Ip
	for pgsql-docs@arkaria.postgresql.org; Thu, 31 Dec 2020 18:45:01 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1kv2wW-0003vF-Gw
	for pgsql-docs@arkaria.postgresql.org; Thu, 31 Dec 2020 18:45:00 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1kv2wW-0003v8-BD
	for pgsql-docs@lists.postgresql.org; Thu, 31 Dec 2020 18:45:00 +0000
Received: from momjian.us ([72.94.173.45])
	by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1kv2wT-0006FT-Q1
	for pgsql-docs@lists.postgresql.org; Thu, 31 Dec 2020 18:44:59 +0000
Received: from bruce by momjian.us with local (Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1kv2wS-0002Nb-6B; Thu, 31 Dec 2020 13:44:56 -0500
Date: Thu, 31 Dec 2020 13:44:56 -0500
From: Bruce Momjian <bruce@momjian.us>
To: fotis.koutoupas@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Potential typo in abbreviated insertion query
Message-ID: <20201231184456.GG22199@momjian.us>
References: <160912275508.676.17469511338925622905@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="H8ygTp4AXg6deix2"
Content-Disposition: inline
In-Reply-To: <160912275508.676.17469511338925622905@wrigleys.postgresql.org>
User-Agent: Mutt/1.10.1 (2018-07-13)
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk


--H8ygTp4AXg6deix2
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

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  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee


--H8ygTp4AXg6deix2
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="executor.diff"

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>

--H8ygTp4AXg6deix2--