Subject: Typo in perform.sgml?

From: Tatsuo Ishii <[email-masked]>
Date: Sat, 07 Dec 2019 20:05:00 +0900 (JST)

Around line 904 of perform.sgml

"These node types have the ability to discard subnodes which they are
able to determine won't contain any records required by the query."

I was not able to parse this. Maybe "that they " is needed after
"determine"?

Best regards,
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp

---

From: Julien Rouhaud <[email-masked]>
Date: Sat, 7 Dec 2019 14:01:37 +0100

> I was not able to parse this. Maybe "that they " is needed after

Agreed.  Also, I'm not a native english speaker either, but the
"which" sounds weird too.  How about:

These node types have the ability to discard subnodes for which they
are able to determine that won't contain any records required by the
query.

---

From: Tom Lane <[email-masked]>
Date: Sat, 07 Dec 2019 11:46:47 -0500

> are able to determine that won't contain any records required by the

Hm.  A grammar purist would say that the "which" should be "that",
because it's introducing a restrictive clause.  But I think the real
problem here is that "contain" is a crummy choice of verb: the notion
of a plan node "containing" records is what seems weird to me.
I think "produce" might work better.  Also, there's a lot of unnecessary
words here; I think we should be trying to make the sentence shorter
not longer.  How about something like

"These node types will discard subnodes when they detect that a
particular subnode won't produce any records required by the query."

Actually, that whole para could do with a rewrite; whoever wrote
it was obviously not familiar with Strunk & White's dictum
"Omit needless words".

			regards, tom lane

---

From: Tom Lane <[email-masked]>
Date: Sat, 07 Dec 2019 15:56:39 -0500

> it was obviously not familiar with Strunk & White's dictum

Looking closer, there were also some unnecessary inconsistencies with
the rest of the section, such as use of "records" rather than "rows",
and different markup choices.  I propose the attached ... it's
actually a bit longer than the original, but that's because it
offers more details.

			regards, tom lane

diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 715aff6..0f61b09 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -896,15 +896,16 @@ EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE unique1 &lt; 100 AND unique2 &gt; 9000
    </para>
 
    <para>
-    Generally, the <command>EXPLAIN</command> output will display details for
-    every plan node which was generated by the query planner.  However, there
-    are cases where the executor is able to determine that certain nodes are
-    not required; currently, the only node types to support this are the
-    <literal>Append</literal> and <literal>MergeAppend</literal> nodes.  These
-    node types have the ability to discard subnodes which they are able to
-    determine won't contain any records required by the query.  It is possible
-    to determine that nodes have been removed in this way by the presence of a
-    "Subplans Removed" property in the <command>EXPLAIN</command> output.
+    Normally, <command>EXPLAIN</command> will display every plan node
+    created by the planner.  However, there are cases where the executor
+    can determine that certain nodes need not be executed because they
+    cannot produce any rows, based on parameter values that were not
+    available at planning time.  (Currently this can only happen for child
+    nodes of an Append or MergeAppend node that is scanning a partitioned
+    table.)  When this happens, those plan nodes are omitted from
+    the <command>EXPLAIN</command> output and a <literal>Subplans
+    Removed: <replaceable>N</replaceable></literal> annotation appears
+    instead.
    </para>
   </sect2>

---

From: Tatsuo Ishii <[email-masked]>
Date: Sun, 08 Dec 2019 11:51:01 +0900 (JST)

> actually a bit longer than the original, but that's because it

Thanks for looking into this. The patch looks much cleaner than
before.

Best regards,

---

From: Julien Rouhaud <[email-masked]>
Date: Sun, 8 Dec 2019 09:07:53 +0100

> Thanks for looking into this. The patch looks much cleaner than

I agree this is way better!

---

From: Tom Lane <[email-masked]>
Date: Sun, 08 Dec 2019 10:37:40 -0500

> I agree this is way better!

Pushed like that, then.

			regards, tom lane