diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index caf1ea4cef..4ee8908b65 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -16,7 +16,12 @@
BRIN is designed for handling very large tables
in which certain columns have some natural correlation with their
physical location within the table.
- A block range is a group of pages that are physically
+
+
+
+ BRIN works in terms of block ranges
+ (or page ranges).
+ A block range is a group of pages that are physically
adjacent in the table; for each block range, some summary info is stored
by the index.
For example, a table storing a store's sale orders might have
@@ -70,34 +75,65 @@
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
- brin_summarize_range(regclass, bigint) or
- brin_summarize_new_values(regclass) functions;
- automatically when VACUUM processes the table;
- or by automatic summarization executed by autovacuum, as insertions
- occur. (This last trigger is disabled by default and can be enabled
- with the autosummarize parameter.)
- Conversely, a range can be de-summarized using the
- brin_desummarize_range(regclass, bigint) function,
- which is useful when the index tuple is no longer a very good
- representation because the existing values have changed.
+ summarized range, the range that the new page belongs into
+ does not automatically acquire a summary tuple;
+ those tuples remain unsummarized until a summarization run is
+ invoked later, creating the initial summary for that range.
- When autosummarization is enabled, each time a page range is filled a
- request is sent to autovacuum for it to execute a targeted summarization
- for that range, to be fulfilled at the end of the next worker run on the
+ There are several ways to trigger the initial summarization of a page range.
+ If the table is vacuumed, either manually or by
+ autovacuum, all existing unsummarized
+ page ranges are summarized.
+ Also, if the index's
+ parameter is enabled,
+ which it isn't by default,
+ whenever autovacuum runs in that database, summarization will occur for all
+ unsummarized page ranges that have been filled,
+ regardless of whether the table itself is processed by autovacuum; see below.
+
+
+
+ Lastly, the following functions can be used:
+
+
+ brin_summarize_new_values(regclass)
+ which summarizes all unsummarized ranges;
+
+
+ brin_summarize_range(regclass, bigint)
+ which summarizes only the range containing the given page,
+ if it is unsummarized.
+
+
+
+
+
+ When autosummarization is enabled, a request is sent to
+ autovacuum to execute a targeted summarization
+ for a block range when an insertion is detected for the first item
+ of the first page of the next block range,
+ to be fulfilled the next time an autovacuum
+ worker finishes running in the
same database. If the request queue is full, the request is not recorded
and a message is sent to the server log:
LOG: request for BRIN range summarization for index "brin_wi_idx" page 128 was not recorded
- When this happens, the range will be summarized normally during the next
- regular vacuum of the table.
+ When this happens, the range will remain unsummarized until the next
+ regular vacuum run on the table, or one of the functions mentioned above
+ are invoked.
+
+
+ Conversely, a range can be de-summarized using the
+ brin_desummarize_range(regclass, bigint) function,
+ which is useful when the index tuple is no longer a very good
+ representation because the existing values have changed.
+ See for details.
+
+
diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index df45bc9746..f50c88fe0a 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -562,8 +562,10 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ]
- Defines whether a summarization run is invoked for the previous page
+ Defines whether a summarization run is queued for the previous page
range whenever an insertion is detected on the next one.
+ See for more details.
+ The default is off.