Remove redundant pg_set_*_stats() variants.

After commit f3dae2ae58, the primary purpose of separating the
pg_set_*_stats() from the pg_restore_*_stats() variants was
eliminated.

Leave pg_restore_relation_stats() and pg_restore_attribute_stats(),
which satisfy both purposes, and remove pg_set_relation_stats() and
pg_set_attribute_stats().

Reviewed-by: Corey Huinker <corey.huinker@gmail.com>
Discussion: https://postgr.es/m/1457469.1740419458@sss.pgh.pa.us

1 files changed, 104 insertions, 150 deletions

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index f0ccb751106..12206e0cfc6 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -30181,66 +30181,6 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
 
      <tbody>
       <row>
-       <entry role="func_table_entry">
-        <para role="func_signature">
-         <indexterm>
-          <primary>pg_set_relation_stats</primary>
-         </indexterm>
-         <function>pg_set_relation_stats</function> (
-         <parameter>relation</parameter> <type>regclass</type>
-         <optional>, <parameter>relpages</parameter> <type>integer</type></optional>
-         <optional>, <parameter>reltuples</parameter> <type>real</type></optional>
-         <optional>, <parameter>relallvisible</parameter> <type>integer</type></optional> )
-         <returnvalue>void</returnvalue>
-        </para>
-        <para>
-         Updates relation-level statistics for the given relation to the
-         specified values. The parameters correspond to columns in <link
-         linkend="catalog-pg-class"><structname>pg_class</structname></link>. Unspecified
-         or <literal>NULL</literal> values leave the setting unchanged.
-        </para>
-        <para>
-         Ordinarily, these statistics are collected automatically or updated
-         as a part of <xref linkend="sql-vacuum"/> or <xref
-         linkend="sql-analyze"/>, so it's not necessary to call this
-         function. However, it may be useful when testing the effects of
-         statistics on the planner to understand or anticipate plan changes.
-        </para>
-        <para>
-         The caller must have the <literal>MAINTAIN</literal> privilege on
-         the table or be the owner of the database.
-        </para>
-        <para>
-         The value of <structfield>relpages</structfield> must be greater than
-         or equal to <literal>-1</literal>,
-         <structfield>reltuples</structfield> must be greater than or equal to
-         <literal>-1.0</literal>, and <structfield>relallvisible</structfield>
-         must be greater than or equal to <literal>0</literal>.
-        </para>
-       </entry>
-      </row>
-
-      <row>
-       <entry role="func_table_entry">
-        <para role="func_signature">
-         <indexterm>
-          <primary>pg_clear_relation_stats</primary>
-         </indexterm>
-         <function>pg_clear_relation_stats</function> ( <parameter>relation</parameter> <type>regclass</type> )
-         <returnvalue>void</returnvalue>
-        </para>
-        <para>
-         Clears table-level statistics for the given relation, as though the
-         table was newly created.
-        </para>
-        <para>
-         The caller must have the <literal>MAINTAIN</literal> privilege on
-         the table or be the owner of the database.
-        </para>
-       </entry>
-      </row>
-
-      <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
          <primary>pg_restore_relation_stats</primary>
@@ -30248,26 +30188,25 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
         <function>pg_restore_relation_stats</function> (
         <literal>VARIADIC</literal> <parameter>kwargs</parameter> <type>"any"</type> )
         <returnvalue>boolean</returnvalue>
-        </para>
-        <para>
-         Similar to <function>pg_set_relation_stats()</function>, but intended
-         for bulk restore of relation statistics. The tracked statistics may
-         change from version to version, so the primary purpose of this
-         function is to maintain a consistent function signature to avoid
-         errors when restoring statistics from previous versions.
-        </para>
+       </para>
         <para>
-         Arguments are passed as pairs of <replaceable>argname</replaceable>
-         and <replaceable>argvalue</replaceable>, where
-         <replaceable>argname</replaceable> corresponds to a named argument in
-         <function>pg_set_relation_stats()</function> and
-         <replaceable>argvalue</replaceable> is of the corresponding type.
+         Updates table-level statistics.  Ordinarily, these statistics are
+         collected automatically or updated as a part of <xref
+         linkend="sql-vacuum"/> or <xref linkend="sql-analyze"/>, so it's not
+         necessary to call this function.  However, it is useful after a
+         restore to enable the optimizer to choose better plans if
+         <command>ANALYZE</command> has not been run yet.
         </para>
         <para>
-         Additionally, this function supports argument name
-         <literal>version</literal> of type <type>integer</type>, which
-         specifies the version from which the statistics originated, improving
-         interpretation of older statistics.
+         The tracked statistics may change from version to version, so
+         arguments are passed as pairs of <replaceable>argname</replaceable>
+         and <replaceable>argvalue</replaceable> in the form:
+<programlisting>
+ SELECT pg_restore_relation_stats(
+    '<replaceable>arg1name</replaceable>', '<replaceable>arg1value</replaceable>'::<replaceable>arg1type</replaceable>,
+    '<replaceable>arg2name</replaceable>', '<replaceable>arg2value</replaceable>'::<replaceable>arg2type</replaceable>,
+    '<replaceable>arg3name</replaceable>', '<replaceable>arg3value</replaceable>'::<replaceable>arg3type</replaceable>);
+</programlisting>
         </para>
         <para>
          For example, to set the <structname>relpages</structname> and
@@ -30277,62 +30216,37 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
  SELECT pg_restore_relation_stats(
     'relation',  'mytable'::regclass,
     'relpages',  173::integer,
-    'reltuples', 10000::float4);
+    'reltuples', 10000::real);
 </programlisting>
         </para>
         <para>
-         Minor errors are reported as a <literal>WARNING</literal> and
-         ignored, and remaining statistics will still be restored. If all
-         specified statistics are successfully restored, return
-         <literal>true</literal>, otherwise <literal>false</literal>.
-        </para>
-       </entry>
-      </row>
-
-      <row>
-       <entry role="func_table_entry">
-        <para role="func_signature">
-         <indexterm>
-          <primary>pg_set_attribute_stats</primary>
-         </indexterm>
-         <function>pg_set_attribute_stats</function> (
-         <parameter>relation</parameter> <type>regclass</type>,
-         <parameter>attname</parameter> <type>name</type>,
-         <parameter>inherited</parameter> <type>boolean</type>
-         <optional>, <parameter>null_frac</parameter> <type>real</type></optional>
-         <optional>, <parameter>avg_width</parameter> <type>integer</type></optional>
-         <optional>, <parameter>n_distinct</parameter> <type>real</type></optional>
-         <optional>, <parameter>most_common_vals</parameter> <type>text</type>, <parameter>most_common_freqs</parameter> <type>real[]</type> </optional>
-         <optional>, <parameter>histogram_bounds</parameter> <type>text</type> </optional>
-         <optional>, <parameter>correlation</parameter> <type>real</type> </optional>
-         <optional>, <parameter>most_common_elems</parameter> <type>text</type>, <parameter>most_common_elem_freqs</parameter> <type>real[]</type> </optional>
-         <optional>, <parameter>elem_count_histogram</parameter> <type>real[]</type> </optional>
-         <optional>, <parameter>range_length_histogram</parameter> <type>text</type> </optional>
-         <optional>, <parameter>range_empty_frac</parameter> <type>real</type> </optional>
-         <optional>, <parameter>range_bounds_histogram</parameter> <type>text</type> </optional> )
-         <returnvalue>void</returnvalue>
-        </para>
-        <para>
-         Creates or updates attribute-level statistics for the given relation
-         and attribute name to the specified values. The parameters correspond
-         to attributes of the same name found in the <link
-         linkend="view-pg-stats"><structname>pg_stats</structname></link>
-         view.
+         The argument <literal>relation</literal> with a value of type
+         <type>regclass</type> is required, and specifies the table. Other
+         arguments are the names of statistics corresponding to certain
+         columns in <link
+         linkend="catalog-pg-class"><structname>pg_class</structname></link>.
+         The currently-supported relation statistics are
+         <literal>relpages</literal> with a value of type
+         <type>integer</type>, <literal>reltuples</literal> with a value of
+         type <type>real</type>, and <literal>relallvisible</literal> with a
+         value of type <type>integer</type>.
         </para>
         <para>
-         Optional parameters default to <literal>NULL</literal>, which leave
-         the corresponding statistic unchanged.
+         Additionally, this function supports argument name
+         <literal>version</literal> of type <type>integer</type>, which
+         specifies the version from which the statistics originated, improving
+         interpretation of statistics from older versions of
+         <productname>PostgreSQL</productname>.
         </para>
         <para>
-         Ordinarily, these statistics are collected automatically or updated
-         as a part of <xref linkend="sql-vacuum"/> or <xref
-         linkend="sql-analyze"/>, so it's not necessary to call this
-         function. However, it may be useful when testing the effects of
-         statistics on the planner to understand or anticipate plan changes.
+         Minor errors are reported as a <literal>WARNING</literal> and
+         ignored, and remaining statistics will still be restored. If all
+         specified statistics are successfully restored, return
+         <literal>true</literal>, otherwise <literal>false</literal>.
         </para>
         <para>
-         The caller must have the <literal>MAINTAIN</literal> privilege on
-         the table or be the owner of the database.
+         The caller must have the <literal>MAINTAIN</literal> privilege on the
+         table or be the owner of the database.
         </para>
        </entry>
       </row>
@@ -30341,21 +30255,18 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
        <entry role="func_table_entry">
         <para role="func_signature">
          <indexterm>
-          <primary>pg_clear_attribute_stats</primary>
+          <primary>pg_clear_relation_stats</primary>
          </indexterm>
-         <function>pg_clear_attribute_stats</function> (
-         <parameter>relation</parameter> <type>regclass</type>,
-         <parameter>attname</parameter> <type>name</type>,
-         <parameter>inherited</parameter> <type>boolean</type> )
+         <function>pg_clear_relation_stats</function> ( <parameter>relation</parameter> <type>regclass</type> )
          <returnvalue>void</returnvalue>
         </para>
         <para>
-         Clears table-level statistics for the given relation attribute, as
-         though the table was newly created.
+         Clears table-level statistics for the given relation, as though the
+         table was newly created.
         </para>
         <para>
-         The caller must have the <literal>MAINTAIN</literal> privilege on
-         the table or be the owner of the database.
+         The caller must have the <literal>MAINTAIN</literal> privilege on the
+         table or be the owner of the database.
         </para>
        </entry>
       </row>
@@ -30368,26 +30279,25 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
         <function>pg_restore_attribute_stats</function> (
         <literal>VARIADIC</literal> <parameter>kwargs</parameter> <type>"any"</type> )
         <returnvalue>boolean</returnvalue>
-        </para>
-        <para>
-         Similar to <function>pg_set_attribute_stats()</function>, but
-         intended for bulk restore of attribute statistics. The tracked
-         statistics may change from version to version, so the primary purpose
-         of this function is to maintain a consistent function signature to
-         avoid errors when restoring statistics from previous versions.
-        </para>
+       </para>
         <para>
-         Arguments are passed as pairs of <replaceable>argname</replaceable>
-         and <replaceable>argvalue</replaceable>, where
-         <replaceable>argname</replaceable> corresponds to a named argument in
-         <function>pg_set_attribute_stats()</function> and
-         <replaceable>argvalue</replaceable> is of the corresponding type.
+         Create or update column-level statistics.  Ordinarily, these
+         statistics are collected automatically or updated as a part of <xref
+         linkend="sql-vacuum"/> or <xref linkend="sql-analyze"/>, so it's not
+         necessary to call this function.  However, it is useful after a
+         restore to enable the optimizer to choose better plans if
+         <command>ANALYZE</command> has not been run yet.
         </para>
         <para>
-         Additionally, this function supports argument name
-         <literal>version</literal> of type <type>integer</type>, which
-         specifies the version from which the statistics originated, improving
-         interpretation of older statistics.
+         The tracked statistics may change from version to version, so
+         arguments are passed as pairs of <replaceable>argname</replaceable>
+         and <replaceable>argvalue</replaceable> in the form:
+<programlisting>
+ SELECT pg_restore_attribute_stats(
+    '<replaceable>arg1name</replaceable>', '<replaceable>arg1value</replaceable>'::<replaceable>arg1type</replaceable>,
+    '<replaceable>arg2name</replaceable>', '<replaceable>arg2value</replaceable>'::<replaceable>arg2type</replaceable>,
+    '<replaceable>arg3name</replaceable>', '<replaceable>arg3value</replaceable>'::<replaceable>arg3type</replaceable>);
+</programlisting>
         </para>
         <para>
          For example, to set the <structname>avg_width</structname> and
@@ -30404,11 +30314,55 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset
 </programlisting>
         </para>
         <para>
+         The required arguments are <literal>relation</literal> with a value
+         of type <type>regclass</type>, which specifies the table;
+         <literal>attname</literal> with a value of type <type>name</type>,
+         which specifies the column; and <literal>inherited</literal>, which
+         specifies whether the statistics includes values from child tables.
+         Other arguments are the names of statistics corresponding to columns
+         in <link
+         linkend="view-pg-stats"><structname>pg_stats</structname></link>.
+        </para>
+        <para>
+         Additionally, this function supports argument name
+         <literal>version</literal> of type <type>integer</type>, which
+         specifies the version from which the statistics originated, improving
+         interpretation of statistics from older versions of
+         <productname>PostgreSQL</productname>.
+        </para>
+        <para>
          Minor errors are reported as a <literal>WARNING</literal> and
          ignored, and remaining statistics will still be restored. If all
          specified statistics are successfully restored, return
          <literal>true</literal>, otherwise <literal>false</literal>.
         </para>
+        <para>
+         The caller must have the <literal>MAINTAIN</literal> privilege on the
+         table or be the owner of the database.
+        </para>
+       </entry>
+      </row>
+
+      <row>
+       <entry role="func_table_entry">
+        <para role="func_signature">
+         <indexterm>
+          <primary>pg_clear_attribute_stats</primary>
+         </indexterm>
+         <function>pg_clear_attribute_stats</function> (
+         <parameter>relation</parameter> <type>regclass</type>,
+         <parameter>attname</parameter> <type>name</type>,
+         <parameter>inherited</parameter> <type>boolean</type> )
+         <returnvalue>void</returnvalue>
+        </para>
+        <para>
+         Clears column-level statistics for the given relation and
+         attribute, as though the table was newly created.
+        </para>
+        <para>
+         The caller must have the <literal>MAINTAIN</literal> privilege on
+         the table or be the owner of the database.
+        </para>
        </entry>
       </row>
      </tbody>