From c2203a7757f574922edf70b4cd5d85ed4edff7da Mon Sep 17 00:00:00 2001
From: Tomas Vondra <tomas.vondra@postgresql.org>
Date: Fri, 21 Jan 2022 18:05:56 +0100
Subject: [PATCH 2/3] minor changes / rewordings

---
 doc/src/sgml/maintenance.sgml | 20 +++++++++---------
 doc/src/sgml/ref/analyze.sgml | 38 +++++++++++++++++++++++++----------
 2 files changed, 38 insertions(+), 20 deletions(-)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index b7c806cc906..9e6909cd748 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -291,11 +291,12 @@
    </para>
 
    <para>
-    Tuples changed in partitions and inheritance children do not count towards
+    Tuples changed in partitions and inheritance children do not trigger
     analyze on the parent table.  If the parent table is empty or rarely
-    changed, it may never be processed by autovacuum.  It is necessary to
-    periodically manual run <command>ANALYZE</command> on the parent table to
-    keep the statistics of its table hierarchy up to date.
+    changed, it may never be processed by autovacuum, and the statistics for
+    the inheritance tree as a whole won't be collected. It is necessary to
+    run <command>ANALYZE</command> on the parent table manually, to keep
+    the statistics up to date.
    </para>
 
    <para>
@@ -358,12 +359,13 @@
 
    <tip>
     <para>
-     The autovacuum daemon does not issue <command>ANALYZE</command> commands for
-     partitioned tables.  Inheritance parents will only be analyzed if the
+     The autovacuum daemon may not issue <command>ANALYZE</command> commands
+     for partitioned tables.  Inheritance parents will only be analyzed if the
      parent itself is changed - changes to child tables do not trigger
-     autoanalyze on the parent table.  It is necessary to periodically run a
-     manual <command>ANALYZE</command> to keep the statistics of the table
-     hierarchy up to date.
+     autoanalyze on the parent table.  If your queries require statistics on
+     parent tables for proper planning, it's necessary to periodically run
+     a manual <command>ANALYZE</command> on those tables to keep the statistics
+     up to date.
     </para>
    </tip>
 
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 3bf904e36f9..764cfb19718 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -250,18 +250,34 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
   </para>
 
   <para>
-    If the table being analyzed is partitioned, <command>ANALYZE</command>
-    will gather statistics by sampling blocks randomly from its partitions;
-    in addition, it will recurse into each partition and update its statistics.
-    (However, in multi-level partitioning scenarios, each leaf partition
-    will only be analyzed once.)
+    If the table being analyzed has one or more children,
+    <command>ANALYZE</command> will gather statistics twice: once on the
+    rows of the parent table only, and a second time on the rows of the
+    parent table with all of its children.  This second set of statistics
+    is needed when planning queries that traverse the entire inheritance
+    tree.  The autovacuum daemon, however, will only consider inserts or
+    updates on the parent table itself when deciding whether to trigger an
+    automatic analyze for that table.  If that table is rarely inserted into
+    or updated, the inheritance statistics will not be up to date unless you
+    run <command>ANALYZE</command> manually.
+  </para>
+
+  <para>
+    For partitioned tables, <command>ANALYZE</command> gathers statistics by
+    sampling rows from all partitions; in addition, it will recurse into each
+    partition and update its statistics.  Each leaf partition is analyzed only
+    once, even with multi-level partitioning.  No statistics are collected for
+    the parent table (ignoring data from partitions), because with partitioning
+    it's guaranteed to be empty.
+  </para>
+
+  <para>
     By constrast, if the table being analyzed has inheritance children,
-    <command>ANALYZE</command> will gather statistics for it twice:
-    once on the rows of the parent table only, and a second time on the
-    rows of the parent table with all of its children.  This second set of
-    statistics is needed when planning queries that traverse the entire
-    inheritance tree.  The child tables themselves are not individually
-    analyzed in this case.
+    <command>ANALYZE</command> gathers two sets of statistics: once on the rows
+    of the parent table only, and a second one including rows of both the parent
+    table and all of its children.  This second set of statistics is needed when
+    planning queries that process the whole inheritance tree at once.  The child
+    tables themselves are not individually analyzed in this case.
   </para>
 
   <para>
-- 
2.17.1