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 <fu...@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><iteration
count></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><iteration
count></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><iteration
count></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><iteration
count></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
