Update parallel.sgml for Parallel Append

Patch by me, reviewed by Thomas Munro, in response to a complaint
from Adrien Nayrat.

Discussion: http://postgr.es/m/baa0d036-7349-f722-ef88-2d8bb3413045@anayrat.info

diff --git a/doc/src/sgml/parallel.sgml b/doc/src/sgml/parallel.sgml
index e9a015ecd3cb43de99657584ebac9dc4f533d474..52806261b6f6bd81967261d09014bdc1f884bf7d 100644 (file)
--- a/doc/src/sgml/parallel.sgml
+++ b/doc/src/sgml/parallel.sgml
@@ -393,6 +393,54 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
 
  
 
+ 
+  Parallel Append
+
+  
+    Whenever PostgreSQL needs to combine rows
+    from multiple sources into a single result set, it uses an
+    Append or MergeAppend plan node.
+    This commonly happens when implementing UNION ALL or
+    when scanning a partitioned table.  Such nodes can be used in parallel
+    plans just as they can in any other plan.  However, in a parallel plan,
+    the planner may instead use a Parallel Append node.
+  
+
+  
+    When an Append node is used in a parallel plan, each
+    process will execute the child plans in the order in which they appear,
+    so that all participating processes cooperate to execute the first child
+    plan until it is complete and then move to the second plan at around the
+    same time.  When a Parallel Append is used instead, the
+    executor will instead spread out the participating processes as evenly as
+    possible across its child plans, so that multiple child plans are executed
+    simultaneously.  This avoids contention, and also avoids paying the startup
+    cost of a child plan in those processes that never execute it.
+  
+
+  
+    Also, unlike a regular Append node, which can only have
+    partial children when used within a parallel plan, a Parallel
+    Append node can have both partial and non-partial child plans.
+    Non-partial children will be scanned by only a single process, since
+    scanning them more than once would produce duplicate results.  Plans that
+    involve appending multiple results sets can therefore achieve
+    coarse-grained parallelism even when efficient partial plans are not
+    available.  For example, consider a query against a partitioned table
+    which can be only be implemented efficiently by using an index that does
+    not support parallel scans.  The planner might choose a Parallel
+    Append of regular Index Scan plans; each
+    individual index scan would have to be executed to completion by a single
+    process, but different scans could be performed at the same time by
+    different processes.
+  
+
+  
+     can be used to disable
+    this feature.
+  
+ 
+
  
   Parallel Plan Tips