rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
postgresql/doc/src/sgml/ref/analyze.sgml

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

330 lines
13 KiB
Plaintext
Raw Normal View History

Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
<!--
Remove cvs keywords from all files.
2010-09-20 22:08:53 +02:00
doc/src/sgml/ref/analyze.sgml
Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:40 +01:00
PostgreSQL documentation
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
-->
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<refentry id="sql-analyze">
doc: Improve DocBook XML validity DocBook XML is superficially compatible with DocBook SGML but has a slightly stricter DTD that we have been violating in a few cases. Although XSLT doesn't care whether the document is valid, the style sheets don't necessarily process invalid documents correctly, so we need to work toward fixing this. This first commit moves the indexterms in refentry elements to an allowed position. It has no impact on the output.
2014-02-24 03:25:35 +01:00
<indexterm zone="sql-analyze">
<primary>ANALYZE</primary>
</indexterm>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
<refmeta>
Remove unnecessary xref endterm attributes and title ids The endterm attribute is mainly useful when the toolchain does not support automatic link target text generation for a particular situation. In the past, this was required by the man page tools for all reference page links, but that is no longer the case, and it now actually gets in the way of proper automatic link text generation. The only remaining use cases are currently xrefs to refsects.
2010-04-03 09:23:02 +02:00
<refentrytitle>ANALYZE</refentrytitle>
Set SQL man pages to be section 7 by default, and only transform them to another section if required by the platform (instead of the old way of building them in section "l" and always transforming them to the platform-specific section). This speeds up the installation on common platforms, and it avoids some funny business with the man page tools and build process.
2008-11-14 11:22:48 +01:00
<manvolnum>7</manvolnum>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
<refnamediv>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<refname>ANALYZE</refname>
<refpurpose>collect statistics about a database</refpurpose>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</refnamediv>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
<refsynopsisdiv>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<synopsis>
Add parenthesized options syntax for ANALYZE. This is analogous to the syntax allowed for VACUUM. This allows us to avoid making new options reserved keywords and makes it easier to allow arbitrary argument order. Oh, and it's consistent with the other commands, too. Author: Nathan Bossart Reviewed-By: Michael Paquier, Masahiko Sawada Discussion: https://postgr.es/m/D3FC73E2-9B1A-4DB4-8180-55F57D116B4E@amazon.com
2018-03-06 01:21:05 +01:00
ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
Allow multiple tables to be specified in one VACUUM or ANALYZE command. Not much to say about this; does what it says on the tin. However, formerly, if there was a column list then the ANALYZE action was implied; now it must be specified, or you get an error. This is because it would otherwise be a bit unclear what the user meant if some tables have column lists and some don't. Nathan Bossart, reviewed by Michael Paquier and Masahiko Sawada, with some editorialization by me Discussion: https://postgr.es/m/E061A8E3-5E3D-494D-94F0-E8A9B312BBFC@amazon.com
2017-10-04 00:53:44 +02:00
Add parenthesized options syntax for ANALYZE. This is analogous to the syntax allowed for VACUUM. This allows us to avoid making new options reserved keywords and makes it easier to allow arbitrary argument order. Oh, and it's consistent with the other commands, too. Author: Nathan Bossart Reviewed-By: Michael Paquier, Masahiko Sawada Discussion: https://postgr.es/m/D3FC73E2-9B1A-4DB4-8180-55F57D116B4E@amazon.com
2018-03-06 01:21:05 +01:00
<phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
Mention ANALYZE boolean options in documentation. Commit 41b54ba78e allowed not only VACUUM but also ANALYZE options to take a boolean argument. But it forgot to update the documentation for ANALYZE. This commit adds the descriptions about those ANALYZE boolean options into the documentation. This patch also updates tab-completion for ANALYZE boolean options. Reported-by: Kyotaro Horiguchi Author: Fujii Masao Reviewed-by: Masahiko Sawada, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHTUt-kuwgiwe8f0AvTnB+ySqJWh95jvmh-qcoKW9YA9g@mail.gmail.com
2019-05-22 18:18:16 +02:00
VERBOSE [ <replaceable class="parameter">boolean</replaceable> ]
SKIP_LOCKED [ <replaceable class="parameter">boolean</replaceable> ]
Add parenthesized options syntax for ANALYZE. This is analogous to the syntax allowed for VACUUM. This allows us to avoid making new options reserved keywords and makes it easier to allow arbitrary argument order. Oh, and it's consistent with the other commands, too. Author: Nathan Bossart Reviewed-By: Michael Paquier, Masahiko Sawada Discussion: https://postgr.es/m/D3FC73E2-9B1A-4DB4-8180-55F57D116B4E@amazon.com
2018-03-06 01:21:05 +01:00
<phrase>and <replaceable class="parameter">table_and_columns</replaceable> is:</phrase>
Allow multiple tables to be specified in one VACUUM or ANALYZE command. Not much to say about this; does what it says on the tin. However, formerly, if there was a column list then the ANALYZE action was implied; now it must be specified, or you get an error. This is because it would otherwise be a bit unclear what the user meant if some tables have column lists and some don't. Nathan Bossart, reviewed by Michael Paquier and Masahiko Sawada, with some editorialization by me Discussion: https://postgr.es/m/E061A8E3-5E3D-494D-94F0-E8A9B312BBFC@amazon.com
2017-10-04 00:53:44 +02:00
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<replaceable class="parameter">table_name</replaceable> [ ( <replaceable class="parameter">column_name</replaceable> [, ...] ) ]
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</synopsis>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</refsynopsisdiv>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<refsect1>
<title>Description</title>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
<para>
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
<command>ANALYZE</command> collects statistics about the contents
Various fixes for the SGML docs. Consistently use spaces before/after parentheses in syntax descriptions. Consistently use the present tense when describing the basic purpose of each "DROP" command. Add a few more hyperlinks.
2007-05-15 21:13:55 +02:00
of tables in the database, and stores the results in the <link
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link>
Various fixes for the SGML docs. Consistently use spaces before/after parentheses in syntax descriptions. Consistently use the present tense when describing the basic purpose of each "DROP" command. Add a few more hyperlinks.
2007-05-15 21:13:55 +02:00
system catalog. Subsequently, the query planner uses these
statistics to help determine the most efficient execution plans for
queries.
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</para>
<para>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
Without a <replaceable class="parameter">table_and_columns</replaceable>
Allow multiple tables to be specified in one VACUUM or ANALYZE command. Not much to say about this; does what it says on the tin. However, formerly, if there was a column list then the ANALYZE action was implied; now it must be specified, or you get an error. This is because it would otherwise be a bit unclear what the user meant if some tables have column lists and some don't. Nathan Bossart, reviewed by Michael Paquier and Masahiko Sawada, with some editorialization by me Discussion: https://postgr.es/m/E061A8E3-5E3D-494D-94F0-E8A9B312BBFC@amazon.com
2017-10-04 00:53:44 +02:00
list, <command>ANALYZE</command> processes every table and materialized view
in the current database that the current user has permission to analyze.
With a list, <command>ANALYZE</command> processes only those table(s).
It is further possible to give a list of column names for a table,
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
in which case only the statistics for those columns are collected.
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</para>
Add parenthesized options syntax for ANALYZE. This is analogous to the syntax allowed for VACUUM. This allows us to avoid making new options reserved keywords and makes it easier to allow arbitrary argument order. Oh, and it's consistent with the other commands, too. Author: Nathan Bossart Reviewed-By: Michael Paquier, Masahiko Sawada Discussion: https://postgr.es/m/D3FC73E2-9B1A-4DB4-8180-55F57D116B4E@amazon.com
2018-03-06 01:21:05 +01:00
<para>
When the option list is surrounded by parentheses, the options can be
written in any order. The parenthesized syntax was added in
<productname>PostgreSQL</productname> 11; the unparenthesized syntax
is deprecated.
</para>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
Enables display of progress messages.
</para>
</listitem>
</varlistentry>
Add option SKIP_LOCKED to VACUUM and ANALYZE When specified, this option allows VACUUM to skip the work on a relation if there is a conflicting lock on it when trying to open it at the beginning of its processing. Similarly to autovacuum, this comes with a couple of limitations while the relation is processed which can cause the process to still block: - when opening the relation indexes. - when acquiring row samples for table inheritance trees, partition trees or certain types of foreign tables, and that a lock is taken on some leaves of such trees. Author: Nathan Bossart Reviewed-by: Michael Paquier, Andres Freund, Masahiko Sawada Discussion: https://postgr.es/m/9EF7EBE4-720D-4CF1-9D0E-4403D7E92990@amazon.com Discussion: https://postgr.es/m/20171201160907.27110.74730@wrigleys.postgresql.org
2018-10-04 02:00:33 +02:00
<varlistentry>
<term><literal>SKIP_LOCKED</literal></term>
<listitem>
<para>
Specifies that <command>ANALYZE</command> should not wait for any
conflicting locks to be released when beginning work on a relation:
if a relation cannot be locked immediately without waiting, the relation
is skipped. Note that even with this option, <command>ANALYZE</command>
may still block when opening the relation's indexes or when acquiring
sample rows from partitions, table inheritance children, and some
types of foreign tables. Also, while <command>ANALYZE</command>
ordinarily processes all partitions of specified partitioned tables,
this option will cause <command>ANALYZE</command> to skip all
partitions if there is a conflicting lock on the partitioned table.
</para>
</listitem>
</varlistentry>
Mention ANALYZE boolean options in documentation. Commit 41b54ba78e allowed not only VACUUM but also ANALYZE options to take a boolean argument. But it forgot to update the documentation for ANALYZE. This commit adds the descriptions about those ANALYZE boolean options into the documentation. This patch also updates tab-completion for ANALYZE boolean options. Reported-by: Kyotaro Horiguchi Author: Fujii Masao Reviewed-by: Masahiko Sawada, Michael Paquier Discussion: https://postgr.es/m/CAHGQGwHTUt-kuwgiwe8f0AvTnB+ySqJWh95jvmh-qcoKW9YA9g@mail.gmail.com
2019-05-22 18:18:16 +02:00
<varlistentry>
<term><replaceable class="parameter">boolean</replaceable></term>
<listitem>
<para>
Specifies whether the selected option should be turned on or off.
You can write <literal>TRUE</literal>, <literal>ON</literal>, or
<literal>1</literal> to enable the option, and <literal>FALSE</literal>,
<literal>OFF</literal>, or <literal>0</literal> to disable it. The
<replaceable class="parameter">boolean</replaceable> value can also
be omitted, in which case <literal>TRUE</literal> is assumed.
</para>
</listitem>
</varlistentry>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">table_name</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
The name (possibly schema-qualified) of a specific table to
Don't uselessly rewrite, truncate, VACUUM, or ANALYZE partitioned tables. Also, recursively perform VACUUM and ANALYZE on partitions when the command is applied to a partitioned table. In passing, some related documentation updates. Amit Langote, reviewed by Michael Paquier, Ashutosh Bapat, and by me. Discussion: http://postgr.es/m/47288cf1-f72c-dfc2-5ff0-4af962ae5c1b@lab.ntt.co.jp
2017-03-02 12:48:19 +01:00
analyze. If omitted, all regular tables, partitioned tables, and
Remove duplicated word. Amit Langote
2017-03-07 17:18:56 +01:00
materialized views in the current database are analyzed (but not
Don't uselessly rewrite, truncate, VACUUM, or ANALYZE partitioned tables. Also, recursively perform VACUUM and ANALYZE on partitions when the command is applied to a partitioned table. In passing, some related documentation updates. Amit Langote, reviewed by Michael Paquier, Ashutosh Bapat, and by me. Discussion: http://postgr.es/m/47288cf1-f72c-dfc2-5ff0-4af962ae5c1b@lab.ntt.co.jp
2017-03-02 12:48:19 +01:00
foreign tables). If the specified table is a partitioned table, both the
inheritance statistics of the partitioned table as a whole and
statistics of the individual partitions are updated.
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Use lower-case SGML attribute values for DocBook XML compatibility
2017-10-09 04:00:57 +02:00
<term><replaceable class="parameter">column_name</replaceable></term>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<listitem>
<para>
The name of a specific column to analyze. Defaults to all columns.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
Mop-up for error-message updates in documentation.
2003-09-13 01:04:46 +02:00
<refsect1>
<title>Outputs</title>
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
When <literal>VERBOSE</literal> is specified, <command>ANALYZE</command> emits
Mop-up for error-message updates in documentation.
2003-09-13 01:04:46 +02:00
progress messages to indicate which table is currently being
processed. Various statistics about the tables are printed as well.
</para>
</refsect1>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<refsect1>
<title>Notes</title>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
Doc: document permissions required for ANALYZE. VACUUM's reference page had this text, but ANALYZE's didn't. That's a clear oversight given that section 5.7 explicitly delegates the responsibility to define permissions requirements to the individual commands' man pages. Per gripe from Isaac Morland. Back-patch to all supported branches. Discussion: https://postgr.es/m/CAMsGm5fp3oBUs-2iRfii0iEO=fZuJALVyM2zJLhNTjG34gpAVQ@mail.gmail.com
2019-08-08 00:09:28 +02:00
<para>
To analyze a table, one must ordinarily be the table's owner or a
superuser. However, database owners are allowed to
analyze all tables in their databases, except shared catalogs.
(The restriction for shared catalogs means that a true database-wide
<command>ANALYZE</command> can only be performed by a superuser.)
<command>ANALYZE</command> will skip over any tables that the calling user
does not have permission to analyze.
</para>
Allow statistics to be collected for foreign tables. ANALYZE now accepts foreign tables and allows the table's FDW to control how the sample rows are collected. (But only manual ANALYZEs will touch foreign tables, for the moment, since among other things it's not very clear how to handle remote permissions checks in an auto-analyze.) contrib/file_fdw is extended to support this. Etsuro Fujita, reviewed by Shigeru Hanada, some further tweaking by me.
2012-04-06 21:02:35 +02:00
<para>
Foreign tables are analyzed only when explicitly selected. Not all
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
foreign data wrappers support <command>ANALYZE</command>. If the table's
wrapper does not support <command>ANALYZE</command>, the command prints a
Allow statistics to be collected for foreign tables. ANALYZE now accepts foreign tables and allows the table's FDW to control how the sample rows are collected. (But only manual ANALYZEs will touch foreign tables, for the moment, since among other things it's not very clear how to handle remote permissions checks in an auto-analyze.) contrib/file_fdw is extended to support this. Etsuro Fujita, reviewed by Shigeru Hanada, some further tweaking by me.
2012-04-06 21:02:35 +02:00
warning and does nothing.
</para>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
<para>
A few improvements to analyze and vacuum sections in documentation: add "see also" entries for autovacuum in analyze and vacuum reference pages, and enhance usage of cross-references in the maintenance page.
2007-10-07 03:16:42 +02:00
In the default <productname>PostgreSQL</productname> configuration,
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
the autovacuum daemon (see <xref linkend="autovacuum"/>)
A few improvements to analyze and vacuum sections in documentation: add "see also" entries for autovacuum in analyze and vacuum reference pages, and enhance usage of cross-references in the maintenance page.
2007-10-07 03:16:42 +02:00
takes care of automatic analyzing of tables when they are first loaded
with data, and as they change throughout regular operation.
When autovacuum is disabled,
it is a good idea to run <command>ANALYZE</command> periodically, or
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
just after making major changes in the contents of a table. Accurate
statistics will help the planner to choose the most appropriate query
plan, and thereby improve the speed of query processing. A common
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
strategy for read-mostly databases is to run <link linkend="sql-vacuum"><command>VACUUM</command></link>
Update various obsolete remarks about VACUUM.
2001-11-18 23:17:30 +01:00
and <command>ANALYZE</command> once a day during a low-usage time of day.
Update and extend the EXPLAIN-related documentation. I've made a significant effort at filling in the "Using EXPLAIN" section to be reasonably complete about mentioning everything that EXPLAIN can output, including the "Rows Removed" outputs that were added by Marko Tiikkaja's recent documentation-free patch. I also updated the examples to be consistent with current behavior; several of them were not close to what the current code will do. No doubt there's more that can be done here, but I'm out of patience for today.
2011-09-29 01:39:54 +02:00
(This will not be sufficient if there is heavy update activity.)
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</para>
<para>
A few improvements to analyze and vacuum sections in documentation: add "see also" entries for autovacuum in analyze and vacuum reference pages, and enhance usage of cross-references in the maintenance page.
2007-10-07 03:16:42 +02:00
<command>ANALYZE</command>
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
requires only a read lock on the target table, so it can run in
parallel with other activity on the table.
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</para>
<para>
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
The statistics collected by <command>ANALYZE</command> usually
include a list of some of the most common values in each column and
a histogram showing the approximate data distribution in each
Update reference documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
column. One or both of these can be omitted if
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
<command>ANALYZE</command> deems them uninteresting (for example,
in a unique-key column, there are no common values) or if the
column data type does not support the appropriate operators. There
is more information about the statistics in <xref
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
linkend="maintenance"/>.
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</para>
<para>
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
For large tables, <command>ANALYZE</command> takes a random sample
of the table contents, rather than examining every row. This
allows even very large tables to be analyzed in a small amount of
time. Note, however, that the statistics are only approximate, and
will change slightly each time <command>ANALYZE</command> is run,
Update reference documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
even if the actual table contents did not change. This might result
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
in small changes in the planner's estimated costs shown by
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
<link linkend="sql-explain"><command>EXPLAIN</command></link>.
Increase the default value of default_statistics_target from 10 to 100, and its maximum value from 1000 to 10000. ALTER TABLE SET STATISTICS similarly now allows a value up to 10000. Per discussion.
2008-12-13 20:13:44 +01:00
In rare situations, this non-determinism will cause the planner's
choices of query plans to change after <command>ANALYZE</command> is run.
To avoid this, raise the amount of statistics collected by
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
<command>ANALYZE</command>, as described below.
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</para>
<para>
Instead of having a configure-time DEFAULT_ATTSTATTARGET, store -1 in attstattarget to indicate 'use the default'. The default is now a GUC variable default_statistics_target, and so may be changed on the fly. Along the way we gain the ability to have pg_dump dump the per-column statistics target when it's not the default. Patch by Neil Conway, with some kibitzing from Tom Lane.
2002-07-31 19:19:54 +02:00
The extent of analysis can be controlled by adjusting the
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<xref linkend="guc-default-statistics-target"/> configuration variable, or
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
on a column-by-column basis by setting the per-column statistics
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
target with <link linkend="sql-altertable"><command>ALTER TABLE ... ALTER COLUMN ... SET
STATISTICS</command></link>.
Remove unnecessary xref endterm attributes and title ids The endterm attribute is mainly useful when the toolchain does not support automatic link target text generation for a particular situation. In the past, this was required by the man page tools for all reference page links, but that is no longer the case, and it now actually gets in the way of proper automatic link text generation. The only remaining use cases are currently xrefs to refsects.
2010-04-03 09:23:02 +02:00
The target value sets the
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
maximum number of entries in the most-common-value list and the
maximum number of bins in the histogram. The default target value
Increase the default value of default_statistics_target from 10 to 100, and its maximum value from 1000 to 10000. ALTER TABLE SET STATISTICS similarly now allows a value up to 10000. Per discussion.
2008-12-13 20:13:44 +01:00
is 100, but this can be adjusted up or down to trade off accuracy of
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
planner estimates against the time taken for
<command>ANALYZE</command> and the amount of space occupied in
<literal>pg_statistic</literal>. In particular, setting the
statistics target to zero disables collection of statistics for
Update reference documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
that column. It might be useful to do that for columns that are
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
never used as part of the <literal>WHERE</literal>, <literal>GROUP BY</literal>,
or <literal>ORDER BY</literal> clauses of queries, since the planner will
This patch makes a few minor improvements to the docs: make the <varname> conventions more consistent, and improve the ANALYZE ref page. Neil Conway
2003-09-11 19:31:45 +02:00
have no use for statistics on such columns.
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</para>
<para>
The largest statistics target among the columns being analyzed determines
the number of table rows sampled to prepare the statistics. Increasing
the target causes a proportional increase in the time and space needed
to do <command>ANALYZE</command>.
</para>
Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT Robert Haas
2009-08-03 00:14:53 +02:00
<para>
One of the values estimated by <command>ANALYZE</command> is the number of
distinct values that appear in each column. Because only a subset of the
rows are examined, this estimate can sometimes be quite inaccurate, even
with the largest possible statistics target. If this inaccuracy leads to
bad query plans, a more accurate value can be determined manually and then
installed with
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
<link linkend="sql-altertable"><command>ALTER TABLE ... ALTER COLUMN ... SET (n_distinct = ...)</command></link>.
Add ALTER TABLE ... ALTER COLUMN ... SET STATISTICS DISTINCT Robert Haas
2009-08-03 00:14:53 +02:00
</para>
Document new 9.0 behavior of ANALYZE on inheritance hierarchies. In particular, note that autovacuum does not yet understand that it might need to vacuum inheritance parents as a result of changes to the child tables.
2010-06-15 20:43:35 +02:00
<para>
Revert analyze support for partitioned tables This reverts the following commits: 1b5617eb844cd2470a334c1d2eec66cf9b39c41a Describe (auto-)analyze behavior for partitioned tables 0e69f705cc1a3df273b38c9883fb5765991e04fe Set pg_class.reltuples for partitioned tables 41badeaba8beee7648ebe7923a41c04f1f3cb302 Document ANALYZE storage parameters for partitioned tables 0827e8af70f4653ba17ed773f123a60eadd9f9c9 autovacuum: handle analyze for partitioned tables There are efficiency issues in this code when handling databases with large numbers of partitions, and it doesn't look like there isn't any trivial way to handle those. There are some other issues as well. It's now too late in the cycle for nontrivial fixes, so we'll have to let Postgres 14 users continue to manually deal with ANALYZE their partitioned tables, and hopefully we can fix the issues for Postgres 15. I kept [most of] be280cdad298 ("Don't reset relhasindex for partitioned tables on ANALYZE") because while we added it due to 0827e8af70f4, it is a good bugfix in its own right, since it affects manual analyze as well as autovacuum-induced analyze, and there's no reason to revert it. I retained the addition of relkind 'p' to tables included by pg_stat_user_tables, because reverting that would require a catversion bump. Also, in pg14 only, I keep a struct member that was added to PgStat_TabStatEntry to avoid breaking compatibility with existing stat files. Backpatch to 14. Discussion: https://postgr.es/m/20210722205458.f2bug3z6qzxzpx2s@alap3.anarazel.de
2021-08-16 23:27:52 +02:00
If the table being analyzed has one or more children,
<command>ANALYZE</command> will gather statistics twice: once on the
rows of the parent table only, and a second time on the rows of the
parent table with all of its children. This second set of statistics
is needed when planning queries that traverse the entire inheritance
tree. The autovacuum daemon, however, will only consider inserts or
updates on the parent table itself when deciding whether to trigger an
automatic analyze for that table. If that table is rarely inserted into
or updated, the inheritance statistics will not be up to date unless you
run <command>ANALYZE</command> manually.
Document new 9.0 behavior of ANALYZE on inheritance hierarchies. In particular, note that autovacuum does not yet understand that it might need to vacuum inheritance parents as a result of changes to the child tables.
2010-06-15 20:43:35 +02:00
</para>
Document that analyzing an empty table doesn't update the statistics. Per a suggestion from Sergey Konoplev
2012-01-27 18:13:49 +01:00
Allow foreign tables to participate in inheritance. Foreign tables can now be inheritance children, or parents. Much of the system was already ready for this, but we had to fix a few things of course, mostly in the area of planner and executor handling of row locks. As side effects of this, allow foreign tables to have NOT VALID CHECK constraints (and hence to accept ALTER ... VALIDATE CONSTRAINT), and to accept ALTER SET STORAGE and ALTER SET WITH/WITHOUT OIDS. Continuing to disallow these things would've required bizarre and inconsistent special cases in inheritance behavior. Since foreign tables don't enforce CHECK constraints anyway, a NOT VALID one is a complete no-op, but that doesn't mean we shouldn't allow it. And it's possible that some FDWs might have use for SET STORAGE or SET WITH OIDS, though doubtless they will be no-ops for most. An additional change in support of this is that when a ModifyTable node has multiple target tables, they will all now be explicitly identified in EXPLAIN output, for example: Update on pt1 (cost=0.00..321.05 rows=3541 width=46) Update on pt1 Foreign Update on ft1 Foreign Update on ft2 Update on child3 -> Seq Scan on pt1 (cost=0.00..0.00 rows=1 width=46) -> Foreign Scan on ft1 (cost=100.00..148.03 rows=1170 width=46) -> Foreign Scan on ft2 (cost=100.00..148.03 rows=1170 width=46) -> Seq Scan on child3 (cost=0.00..25.00 rows=1200 width=46) This was done mainly to provide an unambiguous place to attach "Remote SQL" fields, but it is useful for inherited updates even when no foreign tables are involved. Shigeru Hanada and Etsuro Fujita, reviewed by Ashutosh Bapat and Kyotaro Horiguchi, some additional hacking by me
2015-03-22 18:53:11 +01:00
<para>
Document autoanalyze limitations for partitioned tables When dealing with partitioned tables, counters for partitioned tables are not updated when modifying child tables. This means autoanalyze may not update optimizer statistics for the parent relations, which can result in poor plans for some queries. It's worth documenting this limitation, so that people are aware of it and can take steps to mitigate it (e.g. by setting up a script executing ANALYZE regularly). Backpatch to v10. Older branches are affected too, of couse, but we no longer maintain those. Author: Justin Pryzby Reviewed-by: Zhihong Yu, Tomas Vondra Backpatch-through: 10 Discussion: https://postgr.es/m/20210913035409.GA10647%40telsasoft.com
2022-03-28 14:27:36 +02:00
For partitioned tables, <command>ANALYZE</command> gathers statistics by
sampling rows from all partitions; in addition, it will recurse into each
partition and update its statistics. Each leaf partition is analyzed only
once, even with multi-level partitioning. No statistics are collected for
only the parent table (without data from its partitions), because with
partitioning it's guaranteed to be empty.
</para>
<para>
doc: Fix typo in ANALYZE documentation Commit 61fa6ca79b3 accidentally wrote constrast instead of contrast. Backpatch-through: 10 Discussion: https://postgr.es/m/88903179-5ce2-3d4d-af43-7830372bdcb6@enterprisedb.com
2022-03-31 12:03:33 +02:00
By contrast, if the table being analyzed has inheritance children,
Document autoanalyze limitations for partitioned tables When dealing with partitioned tables, counters for partitioned tables are not updated when modifying child tables. This means autoanalyze may not update optimizer statistics for the parent relations, which can result in poor plans for some queries. It's worth documenting this limitation, so that people are aware of it and can take steps to mitigate it (e.g. by setting up a script executing ANALYZE regularly). Backpatch to v10. Older branches are affected too, of couse, but we no longer maintain those. Author: Justin Pryzby Reviewed-by: Zhihong Yu, Tomas Vondra Backpatch-through: 10 Discussion: https://postgr.es/m/20210913035409.GA10647%40telsasoft.com
2022-03-28 14:27:36 +02:00
<command>ANALYZE</command> gathers two sets of statistics: one on the rows
of the parent table only, and a second including rows of both the parent
table and all of its children. This second set of statistics is needed when
planning queries that process the inheritance tree as a whole. The child
tables themselves are not individually analyzed in this case.
</para>
<para>
The autovacuum daemon does not process partitioned tables, nor does it
process inheritance parents if only the children are ever modified.
It is usually necessary to periodically run a manual
<command>ANALYZE</command> to keep the statistics of the table hierarchy
up to date.
</para>
<para>
If any child tables or partitions are foreign tables whose foreign
data wrappers do not support <command>ANALYZE</command>, those tables are
ignored while gathering inheritance statistics.
Allow foreign tables to participate in inheritance. Foreign tables can now be inheritance children, or parents. Much of the system was already ready for this, but we had to fix a few things of course, mostly in the area of planner and executor handling of row locks. As side effects of this, allow foreign tables to have NOT VALID CHECK constraints (and hence to accept ALTER ... VALIDATE CONSTRAINT), and to accept ALTER SET STORAGE and ALTER SET WITH/WITHOUT OIDS. Continuing to disallow these things would've required bizarre and inconsistent special cases in inheritance behavior. Since foreign tables don't enforce CHECK constraints anyway, a NOT VALID one is a complete no-op, but that doesn't mean we shouldn't allow it. And it's possible that some FDWs might have use for SET STORAGE or SET WITH OIDS, though doubtless they will be no-ops for most. An additional change in support of this is that when a ModifyTable node has multiple target tables, they will all now be explicitly identified in EXPLAIN output, for example: Update on pt1 (cost=0.00..321.05 rows=3541 width=46) Update on pt1 Foreign Update on ft1 Foreign Update on ft2 Update on child3 -> Seq Scan on pt1 (cost=0.00..0.00 rows=1 width=46) -> Foreign Scan on ft1 (cost=100.00..148.03 rows=1170 width=46) -> Foreign Scan on ft2 (cost=100.00..148.03 rows=1170 width=46) -> Seq Scan on child3 (cost=0.00..25.00 rows=1200 width=46) This was done mainly to provide an unambiguous place to attach "Remote SQL" fields, but it is useful for inherited updates even when no foreign tables are involved. Shigeru Hanada and Etsuro Fujita, reviewed by Ashutosh Bapat and Kyotaro Horiguchi, some additional hacking by me
2015-03-22 18:53:11 +01:00
</para>
Document that analyzing an empty table doesn't update the statistics. Per a suggestion from Sergey Konoplev
2012-01-27 18:13:49 +01:00
<para>
If the table being analyzed is completely empty, <command>ANALYZE</command>
will not record new statistics for that table. Any existing statistics
will be retained.
</para>
doc: Add backlinks to progress reporting documentation Previously, the only place where progress reports were mentioned is in the section for monitoring dedicated to its catalogs. This makes the progress reporting more discoverable, by adding links from the pages of the commands supporting progress reports to their related catalog views. Author: Matthias van de Meent Reviewed-by: Justin Pryzby, Bharath Rupireddy, Josef Šimánek, Tomas Vondra Discussion: https://postgr.es/m/CAEze2WiOcgdH4aQA8NtZq-4dgvnJzp8PohdeKchPkhMY-jWZXA@mail.gmail.com
2021-03-05 06:58:16 +01:00
<para>
Each backend running <command>ANALYZE</command> will report its progress
in the <structname>pg_stat_progress_analyze</structname> view. See
<xref linkend="analyze-progress-reporting"/> for details.
</para>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</refsect1>
Bring SQL ref pages to consistent format, part 1.
2003-04-15 15:25:08 +02:00
<refsect1>
<title>Compatibility</title>
<para>
There is no <command>ANALYZE</command> statement in the SQL standard.
</para>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</refsect1>
A few improvements to analyze and vacuum sections in documentation: add "see also" entries for autovacuum in analyze and vacuum reference pages, and enhance usage of cross-references in the maintenance page.
2007-10-07 03:16:42 +02:00
<refsect1>
<title>See Also</title>
<simplelist type="inline">
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<member><xref linkend="sql-vacuum"/></member>
<member><xref linkend="app-vacuumdb"/></member>
<member><xref linkend="runtime-config-resource-vacuum-cost"/></member>
<member><xref linkend="autovacuum"/></member>
doc: Add backlinks to progress reporting documentation Previously, the only place where progress reports were mentioned is in the section for monitoring dedicated to its catalogs. This makes the progress reporting more discoverable, by adding links from the pages of the commands supporting progress reports to their related catalog views. Author: Matthias van de Meent Reviewed-by: Justin Pryzby, Bharath Rupireddy, Josef Šimánek, Tomas Vondra Discussion: https://postgr.es/m/CAEze2WiOcgdH4aQA8NtZq-4dgvnJzp8PohdeKchPkhMY-jWZXA@mail.gmail.com
2021-03-05 06:58:16 +01:00
<member><xref linkend="analyze-progress-reporting"/></member>
A few improvements to analyze and vacuum sections in documentation: add "see also" entries for autovacuum in analyze and vacuum reference pages, and enhance usage of cross-references in the maintenance page.
2007-10-07 03:16:42 +02:00
</simplelist>
</refsect1>
Rewrite of planner statistics-gathering code. ANALYZE is now available as a separate statement (though it can still be invoked as part of VACUUM, too). pg_statistic redesigned to be more flexible about what statistics are stored. ANALYZE now collects a list of several of the most common values, not just one, plus a histogram (not just the min and max values). Random sampling is used to make the process reasonably fast even on very large tables. The number of values and histogram bins collected is now user-settable via an ALTER TABLE command. There is more still to do; the new stats are not being used everywhere they could be in the planner. But the remaining changes for this project should be localized, and the behavior is already better than before. A not-very-related change is that sorting now makes use of btree comparison routines if it can find one, rather than invoking '<' twice.
2001-05-07 02:43:27 +02:00
</refentry>