On Wed, May 7, 2025 at 4:15 PM David Rowley <dgrowle...@gmail.com> wrote:
> In [1] there's a bug report about ALTER TABLE ... ALTER COLUMN SET
> (n_distinct = N) not working for partitioned tables. Of course, you
> need to use n_distinct_inherited for partitioned tables, but the docs
> don't say that.
>
> I went through a few iterations of the wording to make this clearer
> and landed on the attached.
>
>
Not liking the proposal, not sure it is even correct. Somehow "children of
inheritance parent tables" are omitted. In both cases the only statistics
affected are those of the table upon which the option is being read. That
can go implied. Leaving "affects the statistics for the table itself,
while" is causing most of the harm.
In terms of wording - n_distinct must be used for all tables except
partitioned tables and inheritance parent tables. Those two acquire their
override value from n_distinct_inherited. So something like:
diff --git a/doc/src/sgml/ref/alter_table.sgml
b/doc/src/sgml/ref/alter_table.sgml
index 24316bb816a..657e4c835ac 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -339,9 +339,13 @@ WITH ( MODULUS <replaceable
class="parameter">numeric_literal</replaceable>, REM
<literal>n_distinct_inherited</literal>, which override the
number-of-distinct-values estimates made by subsequent
<link linkend="sql-analyze"><command>ANALYZE</command></link>
- operations. <literal>n_distinct</literal> affects the statistics
for the table
- itself, while <literal>n_distinct_inherited</literal> affects the
statistics
- gathered for the table plus its inheritance children. When set to a
+ operations.
+ For partitioned tables and inheritance parents
<command>ANALYZE</command>
+ consults the <literal>n_distinct_inherited</literal> option and, if
applicable,
+ includes all descendants when calculating the table size for use in
the
+ number-of-distinct-values estimate. For all other tables,
<literal>n_distinct</literal>
+ is used and the table size estimate is based on the table itself.
+ When set to a
positive value, <command>ANALYZE</command> will assume that the
column contains
exactly the specified number of distinct nonnull values. When set
to a
negative value, which must be greater
It has a bit of forward-referencing to the following paragraph, but nothing
surprising or novel. The existing wording is already doing the same by
alluding to descendants/children - but its just one data point that is
involved so lets call it out.
David J.
