Subject: document the need to analyze partitioned tables

From: Justin Pryzby <[email-masked]>
Date: Sun, 12 Sep 2021 22:54:09 -0500

Adding -hackers, sorry for the duplicate.

This seems to be deficient, citing
https://www.postgresql.org/message-id/flat/0d1b394b-bec9-8a71-a336-44df7078b295%40gmail.com

I'm proposing something like the attached.  Ideally, there would be a central
place to put details, and the other places could refer to that.

Since the autoanalyze patch was reverted, this should be easily applied to
backbranches, which is probably most of its value.

commit 4ad2c8f6fd8eb26d76b226e68d3fdb8f0658f113
Author: Justin Pryzby <[email-masked]>
Date:   Thu Jul 22 16:06:18 2021 -0500

    documentation deficiencies for ANALYZE of partitioned tables
    
    This is partially extracted from 1b5617eb844cd2470a334c1d2eec66cf9b39c41a,
    which was reverted.

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 36f975b1e5..decfabff5d 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -290,6 +290,14 @@
     to meaningful statistical changes.
    </para>
 
+   <para>
+    Tuples changed in partitions and inheritence children do not count towards
+    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 run an manual <command>ANALYZE</command> to keep the statistics
+    of the table hierarchy up to date.
+   </para>
+
    <para>
     As with vacuuming for space recovery, frequent updates of statistics
     are more useful for heavily-updated tables than for seldom-updated
@@ -347,6 +355,18 @@
      <command>ANALYZE</command> commands on those tables on a suitable schedule.
     </para>
    </tip>
+
+   <tip>
+    <para>
+     The autovacuum daemon does not issue <command>ANALYZE</command> commands for
+     partitioned tables.  Inheritence parents will only be analyzed if the
+     parent is changed - changes to child tables do not trigger autoanalyze on
+     the parent table.  It is necessary to periodically run an manual
+     <command>ANALYZE</command> to keep the statistics of the table hierarchy up to
+     date.
+    </para>
+   </tip>
+
   </sect2>
 
   <sect2 id="vacuum-for-visibility-map">
@@ -817,6 +837,18 @@ 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>.
+
+    Partitioned tables are not processed by autovacuum, and their statistics
+    should be updated by manually running <command>ANALYZE</command> when the
+    table is first populated, and whenever the distribution of data in its
+    partitions changes significantly.
+   </para>
+
+   <para>
+    Partitioned tables are not processed by autovacuum.  Statistics
+    should be collected by running a manual <command>ANALYZE</command> when it is
+    first populated, and updated whenever the distribution of data in its
+    partitions changes significantly.
    </para>
 
    <para>
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 89ff58338e..b84853fd6f 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1765,9 +1765,11 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
    <title>Run <command>ANALYZE</command> Afterwards</title>
 
    <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
+
     <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 c423aeeea5..20ffbc2d7a 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -250,22 +250,33 @@ 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
-    do not support <command>ANALYZE</command>, those child tables are ignored while
-    gathering inheritance statistics.
+    The autovacuum daemon does not process partitioned tables or inheritence
+    parents.  It is usually necessary to periodically run a manual
+    <command>ANALYZE</command> to keep the statistics of the table hierarchy
+    up to date (except for nonempty inheritence parents which undergo
+    modifications of their own table data).
+    See...
+  </para>
+
+  <para>
+    If any of the child tables or partitions are foreign tables whose foreign
+    data wrappers do not support <command>ANALYZE</command>, those tables are
+    ignored while gathering inheritance statistics.
   </para>
 
   <para>

---

From: Zhihong Yu <[email-masked]>
Date: Sun, 12 Sep 2021 21:38:50 -0700

On Sun, Sep 12, 2021 at 8:54 PM Justin Pryzby <[email-masked]> wrote:

>     This is partially extracted from
> 1b5617eb844cd2470a334c1d2eec66cf9b39c41a,
>     which was reverted.
>
>      within a table, running <link
> linkend="sql-analyze"><command>ANALYZE</command></link> is strongly
> recommended. This
> @@ -250,22 +250,33 @@ ANALYZE [ VERBOSE ] [ <replaceable
> class="parameter">table_and_columns</replacea
>    </para>
>
>    <para>
> Hi,
Minor comment:

periodically run an manual  -> periodically run a manual

Cheers

---

From: Justin Pryzby <[email-masked]>
Date: Fri, 8 Oct 2021 07:58:22 -0500

Cleaned up and attached as a .patch.

The patch implementing autoanalyze on partitioned tables should revert relevant
portions of this patch.

---

From: Tomas Vondra <[email-masked]>
Date: Fri, 21 Jan 2022 18:21:57 +0100

Hi,

On 10/8/21 14:58, Justin Pryzby wrote:
> The patch implementing autoanalyze on partitioned tables should
> revert relevant portions of this patch.

I went through this patch and I'd like to propose a couple changes, per 
the 0002 patch:

1) I've reworded the changes in maintenance.sgml a bit. It sounded a bit 
strange before, but I'm not a native speaker so maybe it's worse ...

2) Remove unnecessary whitespace changes in perform.sgml.

3) Simplify the analyze.sgml changes a bit - it was trying to cram too 
much stuff into a single paragraph, so I split that.

Does that seem OK, or did omit something important?

FWIW I think it's really confusing we have inheritance and partitioning, 
and partitions and child tables. And sometimes we use partitioning in 
the generic sense (i.e. including the inheritance approach), and 
sometimes only the declarative variant. Same for partitions vs child 
tables. I can't even imagine how confusing this has to be for people 
just learning this stuff. They must be in permanent WTF?! state ...

regards

-- 
Tomas Vondra
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

From c5105f2f067dff553045792d4a171fc835fe2109 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <[email-masked]>
Date: Thu, 22 Jul 2021 16:06:18 -0500
Subject: [PATCH v2 1/2] documentation deficiencies for ANALYZE of partitioned
 tables

This is partially extracted from 1b5617eb844cd2470a334c1d2eec66cf9b39c41a,
which was reverted.
---
 doc/src/sgml/maintenance.sgml | 27 ++++++++++++++++++++++++++
 doc/src/sgml/perform.sgml     |  2 ++
 doc/src/sgml/ref/analyze.sgml | 36 ++++++++++++++++++++++-------------
 3 files changed, 52 insertions(+), 13 deletions(-)

index 36f975b1e5b..b7c806cc906 100644
 
+   <para>
+    Tuples changed in partitions and inheritance children do not count towards
+    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.
+   </para>
+
    <para>
     As with vacuuming for space recovery, frequent updates of statistics
     are more useful for heavily-updated tables than for seldom-updated
@@ -347,6 +355,18 @@
      <command>ANALYZE</command> commands on those tables on a suitable schedule.
     </para>
    </tip>
+
+   <tip>
+    <para>
+     The autovacuum daemon does 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.
+    </para>
+   </tip>
+
   </sect2>
 
   <sect2 id="vacuum-for-visibility-map">
@@ -819,6 +839,13 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
     since the last <command>ANALYZE</command>.
    </para>
 
+   <para>
+    Partitioned tables are not processed by autovacuum.  Statistics
+    should be collected by running a manual <command>ANALYZE</command> when it is
+    first populated, and updated whenever the distribution of data in its
+    partitions changes significantly.
+   </para>
+
    <para>
     Temporary tables cannot be accessed by autovacuum.  Therefore,
     appropriate vacuum and analyze operations should be performed via
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 89ff58338e5..b84853fd6ff 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1765,9 +1765,11 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
    <title>Run <command>ANALYZE</command> Afterwards</title>
 
    <para>
+
index c8fcebc1612..ea78f0d0387 100644
@@ -250,22 +250,32 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
   </para>
 
   <para>
 
   <para>
-    If any of the child tables are foreign tables whose foreign data wrappers
-    do not support <command>ANALYZE</command>, those child tables are ignored while
-    gathering inheritance statistics.
+    The autovacuum daemon does not process partitioned tables, nor does it
+    process inheritance parents due to modifications to its child tables.
+    It is usually necessary to periodically run a manual
+    <command>ANALYZE</command> to keep the statistics of the table hierarchy
+    up to date.  See...
+  </para>
+
+  <para>
+    If any child tables or partitions are foreign tables whose foreign
+    data wrappers do not support <command>ANALYZE</command>, those tables are
+    ignored while gathering inheritance statistics.
   </para>
 
   <para>
-- 
2.31.1

From 993a42ee2c73a1098845319b30811b5b7497f2f8 Mon Sep 17 00:00:00 2001
From: Tomas Vondra <[email-masked]>
Date: Fri, 21 Jan 2022 18:05:56 +0100
Subject: [PATCH v2 2/2] minor changes / rewordings

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

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index b7c806cc906..2086dae61b2 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 relations 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/perform.sgml b/doc/src/sgml/perform.sgml
index b84853fd6ff..89ff58338e5 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1765,11 +1765,9 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
    <title>Run <command>ANALYZE</command> Afterwards</title>
 
    <para>
-
-
index ea78f0d0387..1482fc2d4bb 100644
@@ -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 child relations.  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.31.1

---

From: Justin Pryzby <[email-masked]>
Date: Fri, 21 Jan 2022 12:02:00 -0600

Thanks for looking at this

On Fri, Jan 21, 2022 at 06:21:57PM +0100, Tomas Vondra wrote:
> I went through this patch and I'd like to propose a couple changes, per the
> 0002 patch:
> 

You added two references to "relations", but everything else talks about
"tables", which is all that analyze processes.

> 2) Remove unnecessary whitespace changes in perform.sgml.

Those were a note to myself and to any reviewer - should that be updated too ?

> 3) Simplify the analyze.sgml changes a bit - it was trying to cram too much
> stuff into a single paragraph, so I split that.
> 

I think you're referring to both legacy inheritance and and partitioning.  That
should be more clear.

I think should say ".. and all of its children".

> FWIW I think it's really confusing we have inheritance and partitioning, and
> partitions and child tables. And sometimes we use partitioning in the
> generic sense (i.e. including the inheritance approach), and sometimes only
> the declarative variant. Same for partitions vs child tables. I can't even
> imagine how confusing this has to be for people just learning this stuff.
> They must be in permanent WTF?! state ...

The docs were cleaned up some in 0c06534bd.  At least the word "partitioned"
should never be used for legacy inheritance - but "partitioning" is.

-- 
Justin

---

From: Tomas Vondra <[email-masked]>
Date: Fri, 21 Jan 2022 19:31:38 +0100

> "tables", which is all that analyze processes.

Good point, that should use "tables" too.

> Those were a note to myself and to any reviewer - should that be updated too ?

Ah, I see. I don't think that part needs updating - it talks about 
having to analyze after a bulk load, and that applies to all tables 
anyway. I don't think it needs to mention partitioned tables need an 
analyze too.

> I think you're referring to both legacy inheritance and and partitioning.  That

I think it applies to both types of partitioning - it's just that in the 
declarative partitioning case the table is always empty so no stats with 
inherit=false are built.

> I think should say ".. and all of its children".

OK

> should never be used for legacy inheritance - but "partitioning" is.

OK

From c5105f2f067dff553045792d4a171fc835fe2109 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <[email-masked]>
Date: Thu, 22 Jul 2021 16:06:18 -0500
Subject: [PATCH v3 1/2] documentation deficiencies for ANALYZE of partitioned
 tables

 
+   <para>

+   <para>
 
    <para>
+
 
   <para>
 
   <para>
 
   <para>
-- 
2.31.1

From 6ea713010faf1d6a51a8f2d90f5c3741b97eb153 Mon Sep 17 00:00:00 2001
From: Tomas Vondra <[email-masked]>
Date: Fri, 21 Jan 2022 18:05:56 +0100
Subject: [PATCH v3 2/2] minor changes / rewordings

---

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>
 
    <para>
@@ -358,12 +359,13 @@
 
    <tip>
     <para>
+     parent tables for proper planning, it's necessary to periodically run

    <para>
-
index ea78f0d0387..c89947ea9fe 100644
 
   <para>
+    table and all of its children.  This second set of statistics is needed when
 
   <para>
-- 
2.31.1

---

From: Robert Haas <[email-masked]>
Date: Mon, 14 Mar 2022 17:23:54 -0400

On Fri, Jan 21, 2022 at 1:31 PM Tomas Vondra
<[email-masked]> wrote:
> [ new patch ]

This patch is originally by Justin. The latest version is by Tomas. I
think the next step is for Justin to say whether he's OK with the
latest version that Tomas posted. If he is, then I suggest that he
also mark it Ready for Committer, and that Tomas commit it. If he's
not, he should say what he wants changed and either post a new version
himself or wait for Tomas to do that.

I think the fact that is classified as a "Bug Fix" in the CommitFest
application is not particularly good. I would prefer to see it
classified under "Documentation". I'm prepared to concede that
documentation can have bugs as a general matter, but nobody's data is
getting eaten because the documentation wasn't updated. In fact, this
is the fourth patch from the "bug fix" section I've studied this
afternoon, and, well, none of them have been back-patchable code
defects.

-- 
Robert Haas
EDB: http://www.enterprisedb.com

---

From: Justin Pryzby <[email-masked]>
Date: Tue, 15 Mar 2022 18:00:11 -0500

On Mon, Mar 14, 2022 at 05:23:54PM -0400, Robert Haas wrote:
> On Fri, Jan 21, 2022 at 1:31 PM Tomas Vondra <[email-masked]> wrote:
> > [ new patch ]
> 

Yes, I think it can be Ready.  Done.

I amended some of Tomas' changes (see 0003, attached as txt).

@cfbot: the *.patch file is for your consumption, and the others are only there
to show my changes.

> afternoon, and, well, none of them have been back-patchable code

In fact, I consider this to be back-patchable back to v10.  IMO it's an
omission that this isn't documented.  Not all bugs cause data to be eaten.  If
someone reads the existing documentation, they might conclude that their
partitioned tables don't need to be analyzed, and they would've been better
served by not reading the docs.

-- 
Justin
>From c237d91ec258ebbf24ebd3a38e139777582817f6 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <[email-masked]>
Date: Thu, 22 Jul 2021 16:06:18 -0500
Subject: [PATCH] documentation deficiencies for ANALYZE of partitioned tables

This is partially extracted from 1b5617eb844cd2470a334c1d2eec66cf9b39c41a,
which was reverted.
---
 doc/src/sgml/maintenance.sgml | 29 +++++++++++++++++++++++++++++
 doc/src/sgml/ref/analyze.sgml | 32 +++++++++++++++++++++++++++++---
 2 files changed, 58 insertions(+), 3 deletions(-)

index 36f975b1e5b..34d72dba784 100644
@@ -290,6 +290,15 @@
 
+   <para>
+    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, 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 in order to
+    keep the statistics up to date.
+   </para>
+
    <para>
     As with vacuuming for space recovery, frequent updates of statistics
     are more useful for heavily-updated tables than for seldom-updated
@@ -347,6 +356,19 @@
      <command>ANALYZE</command> commands on those tables on a suitable schedule.
     </para>
    </tip>
+
+   <tip>
+    <para>
+     The autovacuum daemon does 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.  If your queries require statistics on
+     parent tables for proper planning, it is necessary to periodically run
+     a manual <command>ANALYZE</command> on those tables to keep the statistics
+     up to date.
+    </para>
+   </tip>
+
   </sect2>
 
   <sect2 id="vacuum-for-visibility-map">
@@ -819,6 +841,13 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
     since the last <command>ANALYZE</command>.
    </para>
 
+   <para>
+    Partitioned tables are not processed by autovacuum.  Statistics
+    should be collected by running a manual <command>ANALYZE</command> when it is
+    first populated, and again whenever the distribution of data in its
+    partitions changes significantly.
+   </para>
+
    <para>
     Temporary tables cannot be accessed by autovacuum.  Therefore,
     appropriate vacuum and analyze operations should be performed via
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index c423aeeea5e..8268ba87f63 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -263,9 +263,35 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
   </para>
 
   <para>
-    If any of the child tables are foreign tables whose foreign data wrappers
-    do not support <command>ANALYZE</command>, those child tables are ignored while
-    gathering inheritance statistics.
+    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
+    only the parent table (without data from its 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> gathers two sets of statistics: one on the rows
+    of the parent table only, and a second 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 inheritance tree as a whole.  The child
+    tables themselves are not individually analyzed in this case.
+  </para>
+
+  <para>
+    The autovacuum daemon does not process partitioned tables, nor does it
+    process inheritance parents if only the children are ever modified.
+    It is usually necessary to periodically run a manual
+    <command>ANALYZE</command> to keep the statistics of the table hierarchy
+    up to date.
+  </para>
+
+  <para>
+    If any child tables or partitions are foreign tables whose foreign
+    data wrappers do not support <command>ANALYZE</command>, those tables are
+    ignored while gathering inheritance statistics.
   </para>
 
   <para>
-- 
2.17.1

>From ed314a6b257d22fe21b2d13fc52a5d3fe16137b0 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <[email-masked]>
Date: Thu, 22 Jul 2021 16:06:18 -0500
Subject: [PATCH 1/3] documentation deficiencies for ANALYZE of partitioned
 tables

This is partially extracted from 1b5617eb844cd2470a334c1d2eec66cf9b39c41a,
which was reverted.
---
 doc/src/sgml/maintenance.sgml | 27 ++++++++++++++++++++++++++
 doc/src/sgml/ref/analyze.sgml | 36 ++++++++++++++++++++++-------------
 2 files changed, 50 insertions(+), 13 deletions(-)

+   <para>

+   <para>
index c423aeeea5e..3bf904e36f9 100644
 
   <para>
 
   <para>
 
   <para>
-- 
2.17.1

>From c2203a7757f574922edf70b4cd5d85ed4edff7da Mon Sep 17 00:00:00 2001
From: Tomas Vondra <[email-masked]>
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(-)

    <para>
 
    <para>
@@ -358,12 +359,13 @@
 
    <tip>
     <para>
 
index 3bf904e36f9..764cfb19718 100644
 
   <para>
 
   <para>
-- 
2.17.1

>From 773d02724c8aa4294f46b183afccd021be9dd610 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <[email-masked]>
Date: Tue, 15 Mar 2022 13:38:08 -0500
Subject: [PATCH 3/3] f!3

---
 doc/src/sgml/maintenance.sgml | 10 +++++-----
 doc/src/sgml/ref/analyze.sgml | 12 ++++++------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 9e6909cd748..34d72dba784 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -295,8 +295,8 @@
     analyze on the parent table.  If the parent table is empty or rarely
     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.
+    run <command>ANALYZE</command> on the parent table manually in order to
+    keep the statistics up to date.
    </para>
 
    <para>
@@ -359,11 +359,11 @@
 
    <tip>
     <para>
-     The autovacuum daemon may not issue <command>ANALYZE</command> commands
+     The autovacuum daemon does 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.  If your queries require statistics on
-     parent tables for proper planning, it's necessary to periodically run
+     parent tables for proper planning, it is necessary to periodically run
      a manual <command>ANALYZE</command> on those tables to keep the statistics
      up to date.
     </para>
@@ -844,7 +844,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
    <para>
     Partitioned tables are not processed by autovacuum.  Statistics
     should be collected by running a manual <command>ANALYZE</command> when it is
-    first populated, and updated whenever the distribution of data in its
+    first populated, and again whenever the distribution of data in its
     partitions changes significantly.
    </para>
 
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 764cfb19718..8268ba87f63 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -267,22 +267,22 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
     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.
+    only the parent table (without data from its 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> gathers two sets of statistics: once on the rows
-    of the parent table only, and a second one including rows of both the parent
+    <command>ANALYZE</command> gathers two sets of statistics: one on the rows
+    of the parent table only, and a second 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
+    planning queries that process the inheritance tree as a whole.  The child
     tables themselves are not individually analyzed in this case.
   </para>
 
   <para>
     The autovacuum daemon does not process partitioned tables, nor does it
-    process inheritance parents due to modifications to its child tables.
+    process inheritance parents if only the children are ever modified.
     It is usually necessary to periodically run a manual
     <command>ANALYZE</command> to keep the statistics of the table hierarchy
     up to date.
-- 
2.17.1

---

From: Tomas Vondra <[email-masked]>
Date: Mon, 28 Mar 2022 15:05:26 +0200

> served by not reading the docs.

I've pushed the last version, and backpatched it to 10 (not sure I'd
call it a bugfix, but I certainly agree with Justin it's worth
mentioning in the docs, even on older branches).

regards

---

From: Daniel Gustafsson <[email-masked]>
Date: Thu, 31 Mar 2022 12:17:42 +0200

> On 28 Mar 2022, at 15:05, Tomas Vondra <[email-masked]> wrote:

> mentioning in the docs, even on older branches).

I happened to spot a small typo in this commit in the ANALYZE docs, and have
just pushed a fix all the way down to 10 as per the original commit.

--
Daniel Gustafsson		https://vmware.com/

---

From: Laurenz Albe <[email-masked]>
Date: Wed, 05 Oct 2022 10:37:01 +0200

> mentioning in the docs, even on older branches).

I'd like to suggest an improvement to this.  The current wording could
be read to mean that dead tuples won't get cleaned up in partitioned tables.

By the way, where are the statistics of a partitioned tables used?  The actual
tables scanned are always the partitions, and in the execution plans that
I have seen, the optimizer always used the statistics of the partitions.

Yours,
Laurenz Albe
From 5209f228f09e52780535edacfee5f7efd2c25081 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <[email-masked]>
Date: Wed, 5 Oct 2022 10:31:47 +0200
Subject: [PATCH] Improve autovacuum doc on partitioned tables

The documentation mentioned that autovacuum doesn't process
partitioned tables, but it was unclear about the impact.
The old wording could be interpreted to mean that there are
problems with dead tuple cleanup on partitioned tables.
Clarify that the only potential problem is autoanalyze, and
that statistics for the partitions will be gathered.
---
 doc/src/sgml/maintenance.sgml | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/maintenance.sgml b/doc/src/sgml/maintenance.sgml
index 759ea5ac9c..53e3fadbaf 100644
--- a/doc/src/sgml/maintenance.sgml
+++ b/doc/src/sgml/maintenance.sgml
@@ -860,10 +860,15 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
    </para>
 
    <para>
-    Partitioned tables are not processed by autovacuum.  Statistics
-    should be collected by running a manual <command>ANALYZE</command> when it is
-    first populated, and again whenever the distribution of data in its
-    partitions changes significantly.
+    Partitioned tables are not processed by autovacuum.  This is no problem
+    as far as <command>VACUUM</command> is concerned, since autovacuum will process
+    the partitions.  But, as mentioned in <xref linkend="vacuum-for-statistics"/>,
+    it also means that autovacuum won't run <command>ANALYZE</command> on the
+    partitioned table itself.  While statistics are gathered for the partitions,
+    some queries may rely on the statistics for the partitioned table.  You should
+    collect statistics by running a manual <command>ANALYZE</command> when the
+    partitioned table is first populated, and again whenever the distribution
+    of data in its partitions changes significantly.
    </para>
 
    <para>
-- 
2.37.3

---

From: Andrey Lepikhov <[email-masked]>
Date: Thu, 6 Oct 2022 11:02:07 +0500

> I have seen, the optimizer always used the statistics of the partitions.
For example, it is used to estimate selectivity of join clause:

CREATE TABLE test (id integer, val integer) PARTITION BY hash (id);
CREATE TABLE test_0 PARTITION OF test
   FOR VALUES WITH (modulus 2, remainder 0);
CREATE TABLE test_1 PARTITION OF test
   FOR VALUES WITH (modulus 2, remainder 1);

INSERT INTO test (SELECT q, q FROM generate_series(1,10) AS q);
VACUUM ANALYZE test;
INSERT INTO test (SELECT q, q%2 FROM generate_series(11,200) AS q);
VACUUM ANALYZE test_0,test_1;

EXPLAIN (ANALYZE, TIMING OFF, SUMMARY OFF)
SELECT * FROM test t1, test t2 WHERE t1.id = t2.val;
VACUUM ANALYZE test;
EXPLAIN (ANALYZE, TIMING OFF, SUMMARY OFF)
SELECT * FROM test t1, test t2 WHERE t1.id = t2.val;

Here without actual statistics on parent table we make wrong prediction.

-- 
Regards
Andrey Lepikhov
Postgres Professional