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

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>

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

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,
+   If the table being analyzed is partitioned, <command>ANALYZE</command>
-    <command>ANALYZE</command> will gather statistics twice: once on the
+   will gather statistics by sampling blocks randomly from its partitions;
-    rows of the parent table only, and a second time on the rows of the
+   in addition, it will recurse into each partition and update its statistics.
-    parent table with all of its children.  This second set of statistics
+   (However, in multi-level partitioning scenarios, each leaf partition
-    is needed when planning queries that traverse the entire inheritance
+   will only be analyzed once.)
-    tree.  The autovacuum daemon, however, will only consider inserts or
+   By constrast, if the table being analyzed has inheritance children,
-    updates on the parent table itself when deciding whether to trigger an
+   <command>ANALYZE</command> will gather statistics for it twice:
-    automatic analyze for that table.  If that table is rarely inserted into
+   once on the rows of the parent table only, and a second time on the
-    or updated, the inheritance statistics will not be up to date unless you
+   rows of the parent table with all of its children.  This second set of
-    run <command>ANALYZE</command> manually.
+   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>

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
+   restored table so the optimizer has useful statistics.
-   <xref linkend="vacuum-for-statistics"/> and
+   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>