Document brin_summarize_new_pages

Pointer out by Jeff Janes

2 files changed, 62 insertions, 0 deletions

diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index 2202b7a0996..0883b9a0efc 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -58,6 +58,26 @@
   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 index tuple 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 data
+   from the new tuples.
+   When a new page is created that does not fall within the last
+   summarized range, that range does not automatically acquire a summary
+   tuple; those tuples remain unsummarized until a summarization run is
+   invoked later, creating initial summaries.
+   This process can be invoked manually using 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 d230c6073d2..8ef9fcedfc9 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -17912,6 +17912,48 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
 
   </sect2>
 
+  <sect2 id="functions-admin-index">
+   <title>Index Maintenance Functions</title>
+
+   <indexterm>
+    <primary>brin_summarize_new_values</primary>
+   </indexterm>
+
+   <para>
+    <xref linkend="functions-admin-index-table"> shows the functions
+    available for index maintenance tasks.
+   </para>
+
+   <table id="functions-admin-index-table">
+    <title>Index Maintenance 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</> <type>regclass</>)</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 and inspects the index to find page ranges in the base table
+    that are not currently summarized by the index; for any such range
+    it creates a new summary index tuple by scanning the table pages.
+    It returns the number of new page range summaries that were inserted
+    into the index.
+   </para>
+
+  </sect2>
+
   <sect2 id="functions-admin-genfile">
    <title>Generic File Access Functions</title>