From c655899ba9ae2a0d24e99c797167c33e0cfa0820 Mon Sep 17 00:00:00 2001
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
Date: Sat, 1 Apr 2017 16:10:04 -0300
Subject: BRIN de-summarization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When the BRIN summary tuple for a page range becomes too "wide" for the
values actually stored in the table (because the tuples that were
present originally are no longer present due to updates or deletes), it
can be useful to remove the outdated summary tuple, so that a future
summarization can install a tighter summary.

This commit introduces a SQL-callable interface to do so.

Author: Álvaro Herrera
Reviewed-by: Eiji Seki
Discussion: https://postgr.es/m/20170228045643.n2ri74ara4fhhfxf@alvherre.pgsql
---
 doc/src/sgml/brin.sgml |  4 ++++
 doc/src/sgml/func.sgml | 15 +++++++++++++++
 2 files changed, 19 insertions(+)

(limited to 'doc/src')

diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index 5140a38baad..ad11109775f 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -80,6 +80,10 @@
    or by automatic summarization executed by autovacuum, as insertions
    occur.  (This last trigger is disabled by default and can be enabled
    with the <literal>autosummarize</literal> parameter.)
+   Conversely, a range can be de-summarized using the
+   <function>brin_desummarize_range(regclass, bigint)</function> range,
+   which is useful when the index tuple is no longer a very good
+   representation because the existing values have changed.
   </para>
 
  </sect2>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 25c18d107c8..19329dd1033 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -19660,6 +19660,14 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
     <primary>gin_clean_pending_list</primary>
    </indexterm>
 
+   <indexterm>
+    <primary>brin_summarize_range</primary>
+   </indexterm>
+
+   <indexterm>
+    <primary>brin_desummarize_range</primary>
+   </indexterm>
+
    <para>
     <xref linkend="functions-admin-index-table"> shows the functions
     available for index maintenance tasks.
@@ -19690,6 +19698,13 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
        <entry><type>integer</type></entry>
        <entry>summarize the page range covering the given block, if not already summarized</entry>
       </row>
+      <row>
+       <entry>
+        <literal><function>brin_desummarize_range(<parameter>index</> <type>regclass</>, <parameter>blockNumber</> <type>bigint</type>)</function></literal>
+       </entry>
+       <entry><type>integer</type></entry>
+       <entry>de-summarize the page range covering the given block, if summarized</entry>
+      </row>
       <row>
        <entry>
         <literal><function>gin_clean_pending_list(<parameter>index</> <type>regclass</>)</function></literal>
-- 
cgit v1.2.3