agora inbox for pgsql-docs@postgresql.org  

help / color / mirror / Atom feed

From: Fujii Masao <masao.fujii@oss.nttdata.com>
To: pgsql-docs@lists.postgresql.org
Subject: Add missing references to database object statistics manipulation functions in documentation
Date: Thu, 22 May 2025 20:17:19 +0900
Message-ID: <7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com> (raw)

Hi,

I noticed that the documentation is missing references to the database
object statistics manipulation functions such as pg_restore_relation_stats
in a few relevant places. For instance, the MAINTAIN privilege section
lists allowed operations but doesn't mention these functions, even though
they're covered. Likewise, the pg_class catalog section describes
what can update fields like reltuples, but omits these functions,
which also affect those fields.

So I'd like to propose adding these missing references to improve clarity.
Patch attached. Thought?

Regards,

-- 
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION
From 6e02b416f7742adb6fe82aef4692d455a27d4cf6 Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Thu, 22 May 2025 16:35:45 +0900
Subject: [PATCH v1] doc: Add documentation references for database object
 statistics functions.

Database object statistics manipulation functions were introduced
in PostgreSQL 18. However, references to these functions were missing
in several relevant parts of the documentation.

For example, the documentation for the MAINTAIN privilege lists
permitted operations but omitted mention of the statistics functions,
even though they are allowed under that privilege. Similarly,
the description of the pg_class catalog explains which operations
can update fields like reltuples, but did not include the statistics
functions, which also affect these fields.

This commit updates the documentation to explicitly reference
database object statistics manipulation functions where appropriate.
---
 doc/src/sgml/catalogs.sgml | 24 ++++++++++++++++--------
 doc/src/sgml/ddl.sgml      |  5 +++--
 doc/src/sgml/perform.sgml  | 10 +++++++---
 3 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index cbd4e40a320..60d4c989aba 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -2032,8 +2032,10 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        Size of the on-disk representation of this table in pages (of size
        <symbol>BLCKSZ</symbol>).  This is only an estimate used by the
        planner.  It is updated by <link linkend="sql-vacuum"><command>VACUUM</command></link>,
-       <link linkend="sql-analyze"><command>ANALYZE</command></link>, and a few DDL commands such as
-       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>.
+       <link linkend="sql-analyze"><command>ANALYZE</command></link>, a few DDL commands such as
+       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>,
+       <function>pg_restore_relation_stats</function>, and
+       <function>pg_clear_relation_stats</function>.
       </para></entry>
      </row>
 
@@ -2044,8 +2046,10 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <para>
        Number of live rows in the table.  This is only an estimate used by
        the planner.  It is updated by <link linkend="sql-vacuum"><command>VACUUM</command></link>,
-       <link linkend="sql-analyze"><command>ANALYZE</command></link>, and a few DDL commands such as
-       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>.
+       <link linkend="sql-analyze"><command>ANALYZE</command></link>, a few DDL commands such as
+       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>,
+       <function>pg_restore_relation_stats</function>, and
+       <function>pg_clear_relation_stats</function>.
        If the table has never yet been vacuumed or
        analyzed, <structfield>reltuples</structfield>
        contains <literal>-1</literal> indicating that the row count is
@@ -2061,8 +2065,10 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        Number of pages that are marked all-visible in the table's
        visibility map.  This is only an estimate used by the
        planner.  It is updated by <link linkend="sql-vacuum"><command>VACUUM</command></link>,
-       <link linkend="sql-analyze"><command>ANALYZE</command></link>, and a few DDL commands such as
-       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>.
+       <link linkend="sql-analyze"><command>ANALYZE</command></link>, a few DDL commands such as
+       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>,
+       <function>pg_restore_relation_stats</function>, and
+       <function>pg_clear_relation_stats</function>.
       </para></entry>
      </row>
 
@@ -2081,8 +2087,10 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        It is updated by
        <link linkend="sql-vacuum"><command>VACUUM</command></link>,
        <link linkend="sql-analyze"><command>ANALYZE</command></link>,
-       and a few DDL commands such as
-       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>.
+       a few DDL commands such as
+       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>,
+       <function>pg_restore_relation_stats</function>, and
+       <function>pg_clear_relation_stats</function>.
       </para></entry>
      </row>
 
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index fcd1cb85352..96936bcd3ae 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2223,8 +2223,9 @@ REVOKE ALL ON accounts FROM PUBLIC;
      <para>
       Allows <command>VACUUM</command>, <command>ANALYZE</command>,
       <command>CLUSTER</command>, <command>REFRESH MATERIALIZED VIEW</command>,
-      <command>REINDEX</command>, and <command>LOCK TABLE</command> on a
-      relation.
+      <command>REINDEX</command>, <command>LOCK TABLE</command>,
+      and database object statistics manipulation functions
+      (see <xref linkend="functions-admin-statsmod"/>) on a relation.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 106583fb296..acea2d2ac47 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1253,8 +1253,10 @@ WHERE relname LIKE 'tenk1%';
    For efficiency reasons, <structfield>reltuples</structfield>
    and <structfield>relpages</structfield> are not updated on-the-fly,
    and so they usually contain somewhat out-of-date values.
-   They are updated by <command>VACUUM</command>, <command>ANALYZE</command>, and a
-   few DDL commands such as <command>CREATE INDEX</command>.  A <command>VACUUM</command>
+   They are updated by <command>VACUUM</command>, <command>ANALYZE</command>,
+   a few DDL commands such as <command>CREATE INDEX</command>,
+   <function>pg_restore_relation_stats</function>, and
+   <function>pg_clear_relation_stats</function>. A <command>VACUUM</command>
    or <command>ANALYZE</command> operation that does not scan the entire table
    (which is commonly the case) will incrementally update the
    <structfield>reltuples</structfield> count on the basis of the part
@@ -1281,7 +1283,9 @@ WHERE relname LIKE 'tenk1%';
    system catalog.  Entries in <structname>pg_statistic</structname>
    are updated by the <command>ANALYZE</command> and <command>VACUUM
    ANALYZE</command> commands, and are always approximate even when freshly
-   updated.
+   updated. They can also be updated by
+   <function>pg_restore_attribute_stats</function> and
+   <function>pg_clear_attribute_stats</function>.
   </para>
 
   <indexterm>
-- 
2.49.0



Attachments:

  [text/plain] v1-0001-doc-Add-documentation-references-for-database-obj.patch (6.7K, ../7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com/2-v1-0001-doc-Add-documentation-references-for-database-obj.patch)
  download | inline diff:
From 6e02b416f7742adb6fe82aef4692d455a27d4cf6 Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Thu, 22 May 2025 16:35:45 +0900
Subject: [PATCH v1] doc: Add documentation references for database object
 statistics functions.

Database object statistics manipulation functions were introduced
in PostgreSQL 18. However, references to these functions were missing
in several relevant parts of the documentation.

For example, the documentation for the MAINTAIN privilege lists
permitted operations but omitted mention of the statistics functions,
even though they are allowed under that privilege. Similarly,
the description of the pg_class catalog explains which operations
can update fields like reltuples, but did not include the statistics
functions, which also affect these fields.

This commit updates the documentation to explicitly reference
database object statistics manipulation functions where appropriate.
---
 doc/src/sgml/catalogs.sgml | 24 ++++++++++++++++--------
 doc/src/sgml/ddl.sgml      |  5 +++--
 doc/src/sgml/perform.sgml  | 10 +++++++---
 3 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index cbd4e40a320..60d4c989aba 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -2032,8 +2032,10 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        Size of the on-disk representation of this table in pages (of size
        <symbol>BLCKSZ</symbol>).  This is only an estimate used by the
        planner.  It is updated by <link linkend="sql-vacuum"><command>VACUUM</command></link>,
-       <link linkend="sql-analyze"><command>ANALYZE</command></link>, and a few DDL commands such as
-       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>.
+       <link linkend="sql-analyze"><command>ANALYZE</command></link>, a few DDL commands such as
+       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>,
+       <function>pg_restore_relation_stats</function>, and
+       <function>pg_clear_relation_stats</function>.
       </para></entry>
      </row>
 
@@ -2044,8 +2046,10 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
       <para>
        Number of live rows in the table.  This is only an estimate used by
        the planner.  It is updated by <link linkend="sql-vacuum"><command>VACUUM</command></link>,
-       <link linkend="sql-analyze"><command>ANALYZE</command></link>, and a few DDL commands such as
-       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>.
+       <link linkend="sql-analyze"><command>ANALYZE</command></link>, a few DDL commands such as
+       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>,
+       <function>pg_restore_relation_stats</function>, and
+       <function>pg_clear_relation_stats</function>.
        If the table has never yet been vacuumed or
        analyzed, <structfield>reltuples</structfield>
        contains <literal>-1</literal> indicating that the row count is
@@ -2061,8 +2065,10 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        Number of pages that are marked all-visible in the table's
        visibility map.  This is only an estimate used by the
        planner.  It is updated by <link linkend="sql-vacuum"><command>VACUUM</command></link>,
-       <link linkend="sql-analyze"><command>ANALYZE</command></link>, and a few DDL commands such as
-       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>.
+       <link linkend="sql-analyze"><command>ANALYZE</command></link>, a few DDL commands such as
+       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>,
+       <function>pg_restore_relation_stats</function>, and
+       <function>pg_clear_relation_stats</function>.
       </para></entry>
      </row>
 
@@ -2081,8 +2087,10 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
        It is updated by
        <link linkend="sql-vacuum"><command>VACUUM</command></link>,
        <link linkend="sql-analyze"><command>ANALYZE</command></link>,
-       and a few DDL commands such as
-       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>.
+       a few DDL commands such as
+       <link linkend="sql-createindex"><command>CREATE INDEX</command></link>,
+       <function>pg_restore_relation_stats</function>, and
+       <function>pg_clear_relation_stats</function>.
       </para></entry>
      </row>
 
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index fcd1cb85352..96936bcd3ae 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -2223,8 +2223,9 @@ REVOKE ALL ON accounts FROM PUBLIC;
      <para>
       Allows <command>VACUUM</command>, <command>ANALYZE</command>,
       <command>CLUSTER</command>, <command>REFRESH MATERIALIZED VIEW</command>,
-      <command>REINDEX</command>, and <command>LOCK TABLE</command> on a
-      relation.
+      <command>REINDEX</command>, <command>LOCK TABLE</command>,
+      and database object statistics manipulation functions
+      (see <xref linkend="functions-admin-statsmod"/>) on a relation.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 106583fb296..acea2d2ac47 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1253,8 +1253,10 @@ WHERE relname LIKE 'tenk1%';
    For efficiency reasons, <structfield>reltuples</structfield>
    and <structfield>relpages</structfield> are not updated on-the-fly,
    and so they usually contain somewhat out-of-date values.
-   They are updated by <command>VACUUM</command>, <command>ANALYZE</command>, and a
-   few DDL commands such as <command>CREATE INDEX</command>.  A <command>VACUUM</command>
+   They are updated by <command>VACUUM</command>, <command>ANALYZE</command>,
+   a few DDL commands such as <command>CREATE INDEX</command>,
+   <function>pg_restore_relation_stats</function>, and
+   <function>pg_clear_relation_stats</function>. A <command>VACUUM</command>
    or <command>ANALYZE</command> operation that does not scan the entire table
    (which is commonly the case) will incrementally update the
    <structfield>reltuples</structfield> count on the basis of the part
@@ -1281,7 +1283,9 @@ WHERE relname LIKE 'tenk1%';
    system catalog.  Entries in <structname>pg_statistic</structname>
    are updated by the <command>ANALYZE</command> and <command>VACUUM
    ANALYZE</command> commands, and are always approximate even when freshly
-   updated.
+   updated. They can also be updated by
+   <function>pg_restore_attribute_stats</function> and
+   <function>pg_clear_attribute_stats</function>.
   </para>
 
   <indexterm>
-- 
2.49.0

view thread (4+ messages)  latest in thread

Message-ID: <7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com>
Permalink:  ../7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com/
Also on:    postgresql.org/message-id/7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: pgsql-docs@postgresql.org
  Cc: masao.fujii@oss.nttdata.com, pgsql-docs@lists.postgresql.org
  Subject: Re: Add missing references to database object statistics manipulation functions in documentation
  In-Reply-To: <7c7e1ad5-fdf9-486f-bc63-40ac99b0461d@oss.nttdata.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox