doc: expand description of how non-SELECT queries are processed

The previous description of how the executor processes non-SELECT
queries was very dense, causing lack of clarity.  This expanded text
spells it out more simply.

Reported-by: [email protected]
Discussion: https://postgr.es/m/160912275508.676.17469511338925622905@wrigleys.postgresql.org

Backpatch-through: 9.5

diff --git a/doc/src/sgml/arch-dev.sgml b/doc/src/sgml/arch-dev.sgml
index 7883c3cd827ce54e76225a2a4f1cc397a36ab9e4..ade0ad97d8e171ae88f2e4b80c18a10a113eb1cc 100644 (file)
--- a/doc/src/sgml/arch-dev.sgml
+++ b/doc/src/sgml/arch-dev.sgml
@@ -529,26 +529,36 @@
    
 
    
-    The executor mechanism is used to evaluate all four basic SQL query types:
-    SELECT, INSERT, UPDATE, and
-    DELETE.  For SELECT, the top-level executor
-    code only needs to send each row returned by the query plan tree off
-    to the client.  For INSERT, each returned row is inserted
-    into the target table specified for the INSERT.  This is
-    done in a special top-level plan node called ModifyTable.
-    (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.)  For UPDATE, the planner arranges
-    that each computed row includes all the updated column values, plus
-    the TID (tuple ID, or row ID) of the original target row;
-    this data is fed into a ModifyTable node, which uses the
-    information to create a new updated row and mark the old row deleted.
-    For DELETE, the only column that is actually returned by the
-    plan is the TID, and the ModifyTable node simply uses the TID
-    to visit each target row and mark it deleted.
+    The executor mechanism is used to evaluate all four basic SQL query
+    types: SELECT, INSERT,
+    UPDATE, and DELETE.
+    For SELECT, the top-level executor code
+    only needs to send each row returned by the query plan tree
+    off to the client.  INSERT ... SELECT,
+    UPDATE, and DELETE
+    are effectively SELECTs under a special
+    top-level plan node called ModifyTable.
+   
+
+   
+    INSERT ... SELECT feeds the rows up
+    to ModifyTable for insertion.  For
+    UPDATE, the planner arranges that each
+    computed row includes all the updated column values, plus the
+    TID (tuple ID, or row ID) of the original
+    target row; this data is fed up to the ModifyTable
+    node, which uses the information to create a new updated row and
+    mark the old row deleted.  For DELETE, the only
+    column that is actually returned by the plan is the TID, and the
+    ModifyTable node simply uses the TID to visit each
+    target row and mark it deleted.
+   
+
+   
+    A simple INSERT ... VALUES command creates a
+    trivial plan tree consisting of a single Result
+    node, which computes just one result row, feeding that up
+    toModifyTable to perform the insertion.