Describe (auto-)analyze behavior for partitioned tables

This explains the new behavior introduced by 0827e8af70f4 as well as
preexisting.

Author: Justin Pryzby <pryzby@telsasoft.com>
Author: Álvaro Herrera <alvherre@alvh.no-ip.org>
Discussion: https://postgr.es/m/20210423180152.GA17270@telsasoft.com

4 files changed, 41 insertions, 14 deletions

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index de7fd75e1c6..4b535809b63 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -817,6 +817,12 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
 </programlisting>
     is compared to the total number of tuples inserted, updated, or deleted
     since the last <command>ANALYZE</command>.
+    For partitioned tables, inserts, updates and deletes on partitions
+    are counted towards this threshold; however, DDL
+    operations such as <literal>ATTACH</literal>, <literal>DETACH</literal>
+    and <literal>DROP</literal> are not, so running a manual
+    <command>ANALYZE</command> is recommended if the partition added or
+    removed contains a statistically significant volume of data.
    </para>
 
    <para>
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 89ff58338e5..ddd6c3ff3e0 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1767,7 +1767,8 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
    <para>
     Whenever you have significantly altered the distribution of data
     within a table, running <link linkend="sql-analyze"><command>ANALYZE</command></link> is strongly recommended. This
-    includes bulk loading large amounts of data into the table.  Running
+    includes bulk loading large amounts of data into the table as well as
+    attaching, detaching or dropping partitions.  Running
     <command>ANALYZE</command> (or <command>VACUUM ANALYZE</command>)
     ensures that the planner has up-to-date statistics about the
     table.  With no statistics or obsolete statistics, the planner might
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index c8fcebc1612..0879004b845 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -250,20 +250,38 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
   </para>
 
   <para>
-    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.
+   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.)
+   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.
   </para>
 
   <para>
-    If any of the child tables are foreign tables whose foreign data wrappers
+   The autovacuum daemon counts inserts, updates and deletes in the
+   partitions to determine if auto-analyze is needed.  However, adding
+   or removing partitions does not affect autovacuum daemon decisions,
+   so triggering a manual <command>ANALYZE</command> is recommended
+   when this occurs.
+  </para>
+
+  <para>
+   Tuples changed in inheritance children do not count towards analyze
+   on the parent table.  If the parent table is empty or rarely modified,
+   it may never be processed by autovacuum.  It's necessary to
+   periodically run a manual <command>ANALYZE</command> to keep the
+   statistics of the table hierarchy up to date.
+  </para>
+
+  <para>
+    If any of the child tables or partitions are foreign tables whose foreign data wrappers
     do not support <command>ANALYZE</command>, those child tables are ignored while
     gathering inheritance statistics.
   </para>
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 93ea937ac8e..35cd56297c8 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -922,8 +922,10 @@ CREATE DATABASE foo WITH TEMPLATE template0;
 
   <para>
    Once restored, it is wise to run <command>ANALYZE</command> on each
-   restored table so the optimizer has useful statistics; see
-   <xref linkend="vacuum-for-statistics"/> and
+   restored table so the optimizer has useful statistics.
+   If the table is a partition or an inheritance child, it may also be useful
+   to analyze the parent to update statistics for the table hierarchy.
+   See <xref linkend="vacuum-for-statistics"/> and
    <xref linkend="autovacuum"/> for more information.
   </para>