|
16 | 16 | <acronym>BRIN</acronym> is designed for handling very large tables |
17 | 17 | in which certain columns have some natural correlation with their |
18 | 18 | physical location within the table. |
19 | | - A <firstterm>block range</firstterm> is a group of pages that are physically |
| 19 | + </para> |
| 20 | + |
| 21 | + <para> |
| 22 | + <acronym>BRIN</acronym> works in terms of <firstterm>block ranges</firstterm> |
| 23 | + (or <quote>page ranges</quote>). |
| 24 | + A block range is a group of pages that are physically |
20 | 25 | adjacent in the table; for each block range, some summary info is stored |
21 | 26 | by the index. |
22 | 27 | For example, a table storing a store's sale orders might have |
|
70 | 75 | summarized will cause the summary information to be updated with data |
71 | 76 | from the new tuples. |
72 | 77 | When a new page is created that does not fall within the last |
73 | | - summarized range, that range does not automatically acquire a summary |
74 | | - tuple; those tuples remain unsummarized until a summarization run is |
75 | | - invoked later, creating initial summaries. |
76 | | - This process can be invoked manually using the |
77 | | - <function>brin_summarize_range(regclass, bigint)</function> or |
78 | | - <function>brin_summarize_new_values(regclass)</function> functions; |
79 | | - automatically when <command>VACUUM</command> processes the table; |
80 | | - or by automatic summarization executed by autovacuum, as insertions |
81 | | - occur. (This last trigger is disabled by default and can be enabled |
82 | | - with the <literal>autosummarize</literal> parameter.) |
83 | | - Conversely, a range can be de-summarized using the |
84 | | - <function>brin_desummarize_range(regclass, bigint)</function> function, |
85 | | - which is useful when the index tuple is no longer a very good |
86 | | - representation because the existing values have changed. |
| 78 | + summarized range, the range that the new page belongs into |
| 79 | + does not automatically acquire a summary tuple; |
| 80 | + those tuples remain unsummarized until a summarization run is |
| 81 | + invoked later, creating the initial summary for that range. |
87 | 82 | </para> |
88 | 83 |
|
89 | 84 | <para> |
90 | | - When autosummarization is enabled, each time a page range is filled a |
91 | | - request is sent to autovacuum for it to execute a targeted summarization |
92 | | - for that range, to be fulfilled at the end of the next worker run on the |
| 85 | + There are several ways to trigger the initial summarization of a page range. |
| 86 | + If the table is vacuumed, either manually or by |
| 87 | + <link linkend="autovacuum">autovacuum</link>, all existing unsummarized |
| 88 | + page ranges are summarized. |
| 89 | + Also, if the index's |
| 90 | + <xref linkend="index-reloption-autosummarize"/> parameter is enabled, |
| 91 | + which it isn't by default, |
| 92 | + whenever autovacuum runs in that database, summarization will occur for all |
| 93 | + unsummarized page ranges that have been filled, |
| 94 | + regardless of whether the table itself is processed by autovacuum; see below. |
| 95 | + </para> |
| 96 | + |
| 97 | + <para> |
| 98 | + Lastly, the following functions can be used: |
| 99 | + <simplelist> |
| 100 | + <member> |
| 101 | + <function>brin_summarize_new_values(regclass)</function> |
| 102 | + which summarizes all unsummarized ranges; |
| 103 | + </member> |
| 104 | + <member> |
| 105 | + <function>brin_summarize_range(regclass, bigint)</function> |
| 106 | + which summarizes only the range containing the given page, |
| 107 | + if it is unsummarized. |
| 108 | + </member> |
| 109 | + </simplelist> |
| 110 | + </para> |
| 111 | + |
| 112 | + <para> |
| 113 | + When autosummarization is enabled, a request is sent to |
| 114 | + <literal>autovacuum</literal> to execute a targeted summarization |
| 115 | + for a block range when an insertion is detected for the first item |
| 116 | + of the first page of the next block range, |
| 117 | + to be fulfilled the next time an autovacuum |
| 118 | + worker finishes running in the |
93 | 119 | same database. If the request queue is full, the request is not recorded |
94 | 120 | and a message is sent to the server log: |
95 | 121 | <screen> |
96 | 122 | LOG: request for BRIN range summarization for index "brin_wi_idx" page 128 was not recorded |
97 | 123 | </screen> |
98 | | - When this happens, the range will be summarized normally during the next |
99 | | - regular vacuum of the table. |
| 124 | + When this happens, the range will remain unsummarized until the next |
| 125 | + regular vacuum run on the table, or one of the functions mentioned above |
| 126 | + are invoked. |
| 127 | + </para> |
| 128 | + |
| 129 | + <para> |
| 130 | + Conversely, a range can be de-summarized using the |
| 131 | + <function>brin_desummarize_range(regclass, bigint)</function> function, |
| 132 | + which is useful when the index tuple is no longer a very good |
| 133 | + representation because the existing values have changed. |
| 134 | + See <xref linkend="functions-admin-index"/> for details. |
100 | 135 | </para> |
| 136 | + |
101 | 137 | </sect2> |
102 | 138 | </sect1> |
103 | 139 |
|
|