Jeff Janes wrote:
> Another issue is: it seems to have no SGML documentation. Is that OK?
Here's a patch (which I had to write afresh, because I couldn't find
anything in my brin development tree. Maybe I was just remembering
something I planned to do and never got around to.)
This creates a new sub-section at the bottom of "9.26 System
Administration Functions" named "Indexing Helper Functions", containing
a table with a single row which is for this function. Also, in the BRIN
chapter it creates a subsection "62.1.1. Index Maintenance" which has
one paragraph mentioning that pages that aren't already summarized are
only processed by VACUUM or this function.
I thought about moving the last paragraph of the introduction (which
talks about pages_per_range) to the new subsection. It's clearly of a
different spirit that the preceding paragraphs, but then that parameter
is not really "maintenance" of the index. Perhaps I should name the
subsection something like "Operation and Maintenance" instead, and then
those two paragraphs fit in there.
Other opinions?
Regarding 9.26, this is its TOC:
9.26. System Administration Functions
9.26.1. Configuration Settings Functions
9.26.2. Server Signaling Functions
9.26.3. Backup Control Functions
9.26.4. Recovery Control Functions
9.26.5. Snapshot Synchronization Functions
9.26.6. Replication Functions
9.26.7. Database Object Management Functions
9.26.8. Generic File Access Functions
9.26.9. Advisory Lock Functions
9.26.10. Indexing Helper Functions
We can bikeshed whether the new subsection should be at the bottom, or
some other placement. Maybe it should become 9.26.3, for example.
--
Álvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index 2202b7a..c1b6e1a 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -58,6 +58,24 @@
store more index entries), but at the same time the summary data stored can
be more precise and more data blocks can be skipped during an index scan.
</para>
+
+ <sect2 id="brin-operation">
+ <title>Index Maintenance</title>
+
+ <para>
+ At the time of creation, all existing index pages are scanned and a
+ summary is created for each range, including the possibly-incomplete
+ range at the end. As new pages are filled with data, page ranges that
+ are already summarized will cause the summary information to be updated
+ with the new tuples. When a new page is created that does not fall
+ into the last summarized range, that range does not automatically
+ acquire a summary tuple; those insertions remain unsummarized until
+ a summarization run is invoked later, which creates initial summaries
+ for all unsummarized ranges. This process can be invoked manually
+ by the <function>brin_summarize_new_pages(regclass)</function> function,
+ or automatically when <command>VACUUM</command> processes the table.
+ </para>
+ </sect2>
</sect1>
<sect1 id="brin-builtin-opclasses">
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 81c1d3f..577d3bd 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -18281,6 +18281,48 @@ SELECT (pg_stat_file('filename')).modification;
</sect2>
+ <sect2>
+ <title>Indexing Helper Functions</title>
+
+ <indexterm>
+ <primary>brin_summarize_new_values</primary>
+ </indexterm>
+
+ <para>
+ <xref linkend="functions-admin-indexing"> shows the functions
+ available for index maintenance tasks.
+ </para>
+
+ <table id="functions-admin-indexing">
+ <title>Indexing Helper Functions</title>
+ <tgroup cols="3">
+ <thead>
+ <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>
+ <literal><function>brin_summarize_new_values(<parameter>index_oid</parameter>)</function></literal>
+ </entry>
+ <entry><type>integer</type></entry>
+ <entry>summarize page ranges not already summarized</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ <function>brin_summarize_new_values</> receives a BRIN index OID as
+ argument; it scans the table that the index is for, looking for pages
+ that are not currently summarized. Then the data in those pages is
+ scanned and a new summary index tuple is constructed and inserted into
+ the index. It returns the number of new page range summaries that were
+ inserted into the index.
+ </para>
+
+ </sect2>
+
</sect1>
<sect1 id="functions-trigger">
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
