diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/func.sgml | 254 |
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> |