Debian Codegraph @

doc/src/sgml/brin.sgml

raw
1 <!-- doc/src/sgml/brin.sgml -->
2
3 <sect1 id="brin">
4 <title>BRIN Indexes</title>
5
6 <indexterm>
7 <primary>index</primary>
8 <secondary>BRIN</secondary>
9 </indexterm>
10
11 <sect2 id="brin-intro">
12 <title>Introduction</title>
13
14 <para>
15 <acronym>BRIN</acronym> stands for Block Range Index.
16 <acronym>BRIN</acronym> is designed for handling very large tables
17 in which certain columns have some natural correlation with their
18 physical location within the table.
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
25 adjacent in the table; for each block range, some summary info is stored
26 by the index.
27 For example, a table storing a store's sale orders might have
28 a date column on which each order was placed, and most of the time
29 the entries for earlier orders will appear earlier in the table as well;
30 a table storing a ZIP code column might have all codes for a city
31 grouped together naturally.
32 </para>
33
34 <para>
35 <acronym>BRIN</acronym> indexes can satisfy queries via regular bitmap
36 index scans, and will return all tuples in all pages within each range if
37 the summary info stored by the index is <firstterm>consistent</firstterm> with the
38 query conditions.
39 The query executor is in charge of rechecking these tuples and discarding
40 those that do not match the query conditions &mdash; in other words, these
41 indexes are lossy.
42 Because a <acronym>BRIN</acronym> index is very small, scanning the index
43 adds little overhead compared to a sequential scan, but may avoid scanning
44 large parts of the table that are known not to contain matching tuples.
45 </para>
46
47 <para>
48 The specific data that a <acronym>BRIN</acronym> index will store,
49 as well as the specific queries that the index will be able to satisfy,
50 depend on the operator class selected for each column of the index.
51 Data types having a linear sort order can have operator classes that
52 store the minimum and maximum value within each block range, for instance;
53 geometrical types might store the bounding box for all the objects
54 in the block range.
55 </para>
56
57 <para>
58 The size of the block range is determined at index creation time by
59 the <literal>pages_per_range</literal> storage parameter. The number of index
60 entries will be equal to the size of the relation in pages divided by
61 the selected value for <literal>pages_per_range</literal>. Therefore, the smaller
62 the number, the larger the index becomes (because of the need to
63 store more index entries), but at the same time the summary data stored can
64 be more precise and more data blocks can be skipped during an index scan.
65 </para>
66
67 <sect3 id="brin-operation">
68 <title>Index Maintenance</title>
69
70 <para>
71 At the time of creation, all existing heap pages are scanned and a
72 summary index tuple is created for each range, including the
73 possibly-incomplete range at the end.
74 As new pages are filled with data, page ranges that are already
75 summarized will cause the summary information to be updated with data
76 from the new tuples.
77 When a new page is created that does not fall within the last
78 summarized range, the range that the new page belongs to
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.
82 </para>
83
84 <para>
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 (while these functions run,
99 <xref linkend="guc-search-path"/> is temporarily changed to
100 <literal>pg_catalog, pg_temp</literal>):
101 <simplelist>
102 <member>
103 <function>brin_summarize_new_values(regclass)</function>
104 which summarizes all unsummarized ranges;
105 </member>
106 <member>
107 <function>brin_summarize_range(regclass, bigint)</function>
108 which summarizes only the range containing the given page,
109 if it is unsummarized.
110 </member>
111 </simplelist>
112 </para>
113
114 <para>
115 When autosummarization is enabled, a request is sent to
116 <literal>autovacuum</literal> to execute a targeted summarization
117 for a block range when an insertion is detected for the first item
118 of the first page of the next block range,
119 to be fulfilled the next time an autovacuum
120 worker finishes running in the
121 same database. If the request queue is full, the request is not recorded
122 and a message is sent to the server log:
123 <screen>
124 LOG: request for BRIN range summarization for index "brin_wi_idx" page 128 was not recorded
125 </screen>
126 When this happens, the range will remain unsummarized until the next
127 regular vacuum run on the table, or one of the functions mentioned above
128 are invoked.
129 </para>
130
131 <para>
132 Conversely, a range can be de-summarized using the
133 <function>brin_desummarize_range(regclass, bigint)</function> function,
134 which is useful when the index tuple is no longer a very good
135 representation because the existing values have changed.
136 See <xref linkend="functions-admin-index"/> for details.
137 </para>
138
139 </sect3>
140 </sect2>
141
142 <sect2 id="brin-builtin-opclasses">
143 <title>Built-in Operator Classes</title>
144
145 <para>
146 The core <productname>PostgreSQL</productname> distribution
147 includes the <acronym>BRIN</acronym> operator classes shown in
148 <xref linkend="brin-builtin-opclasses-table"/>.
149 </para>
150
151 <para>
152 The <firstterm>minmax</firstterm>
153 operator classes store the minimum and the maximum values appearing
154 in the indexed column within the range. The <firstterm>inclusion</firstterm>
155 operator classes store a value which includes the values in the indexed
156 column within the range. The <firstterm>bloom</firstterm> operator
157 classes build a Bloom filter for all values in the range. The
158 <firstterm>minmax-multi</firstterm> operator classes store multiple
159 minimum and maximum values, representing values appearing in the indexed
160 column within the range.
161 </para>
162
163 <table id="brin-builtin-opclasses-table">
164 <title>Built-in <acronym>BRIN</acronym> Operator Classes</title>
165 <tgroup cols="2">
166 <thead>
167 <row>
168 <entry>Name</entry>
169 <entry>Indexable Operators</entry>
170 </row>
171 </thead>
172 <tbody>
173 <row>
174 <entry valign="middle" morerows="4"><literal>bit_minmax_ops</literal></entry>
175 <entry><literal>= (bit,bit)</literal></entry>
176 </row>
177 <row><entry><literal>&lt; (bit,bit)</literal></entry></row>
178 <row><entry><literal>&gt; (bit,bit)</literal></entry></row>
179 <row><entry><literal>&lt;= (bit,bit)</literal></entry></row>
180 <row><entry><literal>&gt;= (bit,bit)</literal></entry></row>
181
182 <row>
183 <entry valign="middle" morerows="12"><literal>box_inclusion_ops</literal></entry>
184 <entry><literal>@&gt; (box,point)</literal></entry>
185 </row>
186 <row><entry><literal>&lt;&lt; (box,box)</literal></entry></row>
187 <row><entry><literal>&amp;&lt; (box,box)</literal></entry></row>
188 <row><entry><literal>&amp;&gt; (box,box)</literal></entry></row>
189 <row><entry><literal>&gt;&gt; (box,box)</literal></entry></row>
190 <row><entry><literal>&lt;@ (box,box)</literal></entry></row>
191 <row><entry><literal>@&gt; (box,box)</literal></entry></row>
192 <row><entry><literal>~= (box,box)</literal></entry></row>
193 <row><entry><literal>&amp;&amp; (box,box)</literal></entry></row>
194 <row><entry><literal>&lt;&lt;| (box,box)</literal></entry></row>
195 <row><entry><literal>&amp;&lt;| (box,box)</literal></entry></row>
196 <row><entry><literal>|&amp;&gt; (box,box)</literal></entry></row>
197 <row><entry><literal>|&gt;&gt; (box,box)</literal></entry></row>
198
199 <row>
200 <entry valign="middle"><literal>bpchar_bloom_ops</literal></entry>
201 <entry><literal>= (character,character)</literal></entry>
202 </row>
203
204 <row>
205 <entry valign="middle" morerows="4"><literal>bpchar_minmax_ops</literal></entry>
206 <entry><literal>= (character,character)</literal></entry>
207 </row>
208 <row><entry><literal>&lt; (character,character)</literal></entry></row>
209 <row><entry><literal>&lt;= (character,character)</literal></entry></row>
210 <row><entry><literal>&gt; (character,character)</literal></entry></row>
211 <row><entry><literal>&gt;= (character,character)</literal></entry></row>
212
213 <row>
214 <entry valign="middle"><literal>bytea_bloom_ops</literal></entry>
215 <entry><literal>= (bytea,bytea)</literal></entry>
216 </row>
217
218 <row>
219 <entry valign="middle" morerows="4"><literal>bytea_minmax_ops</literal></entry>
220 <entry><literal>= (bytea,bytea)</literal></entry>
221 </row>
222 <row><entry><literal>&lt; (bytea,bytea)</literal></entry></row>
223 <row><entry><literal>&lt;= (bytea,bytea)</literal></entry></row>
224 <row><entry><literal>&gt; (bytea,bytea)</literal></entry></row>
225 <row><entry><literal>&gt;= (bytea,bytea)</literal></entry></row>
226
227 <row>
228 <entry valign="middle"><literal>char_bloom_ops</literal></entry>
229 <entry><literal>= ("char","char")</literal></entry>
230 </row>
231
232 <row>
233 <entry valign="middle" morerows="4"><literal>char_minmax_ops</literal></entry>
234 <entry><literal>= ("char","char")</literal></entry>
235 </row>
236 <row><entry><literal>&lt; ("char","char")</literal></entry></row>
237 <row><entry><literal>&lt;= ("char","char")</literal></entry></row>
238 <row><entry><literal>&gt; ("char","char")</literal></entry></row>
239 <row><entry><literal>&gt;= ("char","char")</literal></entry></row>
240
241 <row>
242 <entry valign="middle"><literal>date_bloom_ops</literal></entry>
243 <entry><literal>= (date,date)</literal></entry>
244 </row>
245
246 <row>
247 <entry valign="middle" morerows="4"><literal>date_minmax_ops</literal></entry>
248 <entry><literal>= (date,date)</literal></entry>
249 </row>
250 <row><entry><literal>&lt; (date,date)</literal></entry></row>
251 <row><entry><literal>&lt;= (date,date)</literal></entry></row>
252 <row><entry><literal>&gt; (date,date)</literal></entry></row>
253 <row><entry><literal>&gt;= (date,date)</literal></entry></row>
254
255 <row>
256 <entry valign="middle" morerows="4"><literal>date_minmax_multi_ops</literal></entry>
257 <entry><literal>= (date,date)</literal></entry>
258 </row>
259 <row><entry><literal>&lt; (date,date)</literal></entry></row>
260 <row><entry><literal>&lt;= (date,date)</literal></entry></row>
261 <row><entry><literal>&gt; (date,date)</literal></entry></row>
262 <row><entry><literal>&gt;= (date,date)</literal></entry></row>
263
264 <row>
265 <entry valign="middle"><literal>float4_bloom_ops</literal></entry>
266 <entry><literal>= (float4,float4)</literal></entry>
267 </row>
268
269 <row>
270 <entry valign="middle" morerows="4"><literal>float4_minmax_ops</literal></entry>
271 <entry><literal>= (float4,float4)</literal></entry>
272 </row>
273 <row><entry><literal>&lt; (float4,float4)</literal></entry></row>
274 <row><entry><literal>&gt; (float4,float4)</literal></entry></row>
275 <row><entry><literal>&lt;= (float4,float4)</literal></entry></row>
276 <row><entry><literal>&gt;= (float4,float4)</literal></entry></row>
277
278 <row>
279 <entry valign="middle" morerows="4"><literal>float4_minmax_multi_ops</literal></entry>
280 <entry><literal>= (float4,float4)</literal></entry>
281 </row>
282 <row><entry><literal>&lt; (float4,float4)</literal></entry></row>
283 <row><entry><literal>&gt; (float4,float4)</literal></entry></row>
284 <row><entry><literal>&lt;= (float4,float4)</literal></entry></row>
285 <row><entry><literal>&gt;= (float4,float4)</literal></entry></row>
286
287 <row>
288 <entry valign="middle"><literal>float8_bloom_ops</literal></entry>
289 <entry><literal>= (float8,float8)</literal></entry>
290 </row>
291
292 <row>
293 <entry valign="middle" morerows="4"><literal>float8_minmax_ops</literal></entry>
294 <entry><literal>= (float8,float8)</literal></entry>
295 </row>
296 <row><entry><literal>&lt; (float8,float8)</literal></entry></row>
297 <row><entry><literal>&lt;= (float8,float8)</literal></entry></row>
298 <row><entry><literal>&gt; (float8,float8)</literal></entry></row>
299 <row><entry><literal>&gt;= (float8,float8)</literal></entry></row>
300
301 <row>
302 <entry valign="middle" morerows="4"><literal>float8_minmax_multi_ops</literal></entry>
303 <entry><literal>= (float8,float8)</literal></entry>
304 </row>
305 <row><entry><literal>&lt; (float8,float8)</literal></entry></row>
306 <row><entry><literal>&lt;= (float8,float8)</literal></entry></row>
307 <row><entry><literal>&gt; (float8,float8)</literal></entry></row>
308 <row><entry><literal>&gt;= (float8,float8)</literal></entry></row>
309
310 <row>
311 <entry valign="middle" morerows="5"><literal>inet_inclusion_ops</literal></entry>
312 <entry><literal>&lt;&lt; (inet,inet)</literal></entry>
313 </row>
314 <row><entry><literal>&lt;&lt;= (inet,inet)</literal></entry></row>
315 <row><entry><literal>&gt;&gt; (inet,inet)</literal></entry></row>
316 <row><entry><literal>&gt;&gt;= (inet,inet)</literal></entry></row>
317 <row><entry><literal>= (inet,inet)</literal></entry></row>
318 <row><entry><literal>&amp;&amp; (inet,inet)</literal></entry></row>
319
320 <row>
321 <entry valign="middle"><literal>inet_bloom_ops</literal></entry>
322 <entry><literal>= (inet,inet)</literal></entry>
323 </row>
324
325 <row>
326 <entry valign="middle" morerows="4"><literal>inet_minmax_ops</literal></entry>
327 <entry><literal>= (inet,inet)</literal></entry>
328 </row>
329 <row><entry><literal>&lt; (inet,inet)</literal></entry></row>
330 <row><entry><literal>&lt;= (inet,inet)</literal></entry></row>
331 <row><entry><literal>&gt; (inet,inet)</literal></entry></row>
332 <row><entry><literal>&gt;= (inet,inet)</literal></entry></row>
333
334 <row>
335 <entry valign="middle" morerows="4"><literal>inet_minmax_multi_ops</literal></entry>
336 <entry><literal>= (inet,inet)</literal></entry>
337 </row>
338 <row><entry><literal>&lt; (inet,inet)</literal></entry></row>
339 <row><entry><literal>&lt;= (inet,inet)</literal></entry></row>
340 <row><entry><literal>&gt; (inet,inet)</literal></entry></row>
341 <row><entry><literal>&gt;= (inet,inet)</literal></entry></row>
342
343 <row>
344 <entry valign="middle"><literal>int2_bloom_ops</literal></entry>
345 <entry><literal>= (int2,int2)</literal></entry>
346 </row>
347
348 <row>
349 <entry valign="middle" morerows="4"><literal>int2_minmax_ops</literal></entry>
350 <entry><literal>= (int2,int2)</literal></entry>
351 </row>
352 <row><entry><literal>&lt; (int2,int2)</literal></entry></row>
353 <row><entry><literal>&gt; (int2,int2)</literal></entry></row>
354 <row><entry><literal>&lt;= (int2,int2)</literal></entry></row>
355 <row><entry><literal>&gt;= (int2,int2)</literal></entry></row>
356
357 <row>
358 <entry valign="middle" morerows="4"><literal>int2_minmax_multi_ops</literal></entry>
359 <entry><literal>= (int2,int2)</literal></entry>
360 </row>
361 <row><entry><literal>&lt; (int2,int2)</literal></entry></row>
362 <row><entry><literal>&gt; (int2,int2)</literal></entry></row>
363 <row><entry><literal>&lt;= (int2,int2)</literal></entry></row>
364 <row><entry><literal>&gt;= (int2,int2)</literal></entry></row>
365
366 <row>
367 <entry valign="middle"><literal>int4_bloom_ops</literal></entry>
368 <entry><literal>= (int4,int4)</literal></entry>
369 </row>
370
371 <row>
372 <entry valign="middle" morerows="4"><literal>int4_minmax_ops</literal></entry>
373 <entry><literal>= (int4,int4)</literal></entry>
374 </row>
375 <row><entry><literal>&lt; (int4,int4)</literal></entry></row>
376 <row><entry><literal>&gt; (int4,int4)</literal></entry></row>
377 <row><entry><literal>&lt;= (int4,int4)</literal></entry></row>
378 <row><entry><literal>&gt;= (int4,int4)</literal></entry></row>
379
380 <row>
381 <entry valign="middle" morerows="4"><literal>int4_minmax_multi_ops</literal></entry>
382 <entry><literal>= (int4,int4)</literal></entry>
383 </row>
384 <row><entry><literal>&lt; (int4,int4)</literal></entry></row>
385 <row><entry><literal>&gt; (int4,int4)</literal></entry></row>
386 <row><entry><literal>&lt;= (int4,int4)</literal></entry></row>
387 <row><entry><literal>&gt;= (int4,int4)</literal></entry></row>
388
389 <row>
390 <entry valign="middle"><literal>int8_bloom_ops</literal></entry>
391 <entry><literal>= (bigint,bigint)</literal></entry>
392 </row>
393
394 <row>
395 <entry valign="middle" morerows="4"><literal>int8_minmax_ops</literal></entry>
396 <entry><literal>= (bigint,bigint)</literal></entry>
397 </row>
398 <row><entry><literal>&lt; (bigint,bigint)</literal></entry></row>
399 <row><entry><literal>&gt; (bigint,bigint)</literal></entry></row>
400 <row><entry><literal>&lt;= (bigint,bigint)</literal></entry></row>
401 <row><entry><literal>&gt;= (bigint,bigint)</literal></entry></row>
402
403 <row>
404 <entry valign="middle" morerows="4"><literal>int8_minmax_multi_ops</literal></entry>
405 <entry><literal>= (bigint,bigint)</literal></entry>
406 </row>
407 <row><entry><literal>&lt; (bigint,bigint)</literal></entry></row>
408 <row><entry><literal>&gt; (bigint,bigint)</literal></entry></row>
409 <row><entry><literal>&lt;= (bigint,bigint)</literal></entry></row>
410 <row><entry><literal>&gt;= (bigint,bigint)</literal></entry></row>
411
412 <row>
413 <entry valign="middle"><literal>interval_bloom_ops</literal></entry>
414 <entry><literal>= (interval,interval)</literal></entry>
415 </row>
416
417 <row>
418 <entry valign="middle" morerows="4"><literal>interval_minmax_ops</literal></entry>
419 <entry><literal>= (interval,interval)</literal></entry>
420 </row>
421 <row><entry><literal>&lt; (interval,interval)</literal></entry></row>
422 <row><entry><literal>&lt;= (interval,interval)</literal></entry></row>
423 <row><entry><literal>&gt; (interval,interval)</literal></entry></row>
424 <row><entry><literal>&gt;= (interval,interval)</literal></entry></row>
425
426 <row>
427 <entry valign="middle" morerows="4"><literal>interval_minmax_multi_ops</literal></entry>
428 <entry><literal>= (interval,interval)</literal></entry>
429 </row>
430 <row><entry><literal>&lt; (interval,interval)</literal></entry></row>
431 <row><entry><literal>&lt;= (interval,interval)</literal></entry></row>
432 <row><entry><literal>&gt; (interval,interval)</literal></entry></row>
433 <row><entry><literal>&gt;= (interval,interval)</literal></entry></row>
434
435 <row>
436 <entry valign="middle"><literal>macaddr_bloom_ops</literal></entry>
437 <entry><literal>= (macaddr,macaddr)</literal></entry>
438 </row>
439
440 <row>
441 <entry valign="middle" morerows="4"><literal>macaddr_minmax_ops</literal></entry>
442 <entry><literal>= (macaddr,macaddr)</literal></entry>
443 </row>
444 <row><entry><literal>&lt; (macaddr,macaddr)</literal></entry></row>
445 <row><entry><literal>&lt;= (macaddr,macaddr)</literal></entry></row>
446 <row><entry><literal>&gt; (macaddr,macaddr)</literal></entry></row>
447 <row><entry><literal>&gt;= (macaddr,macaddr)</literal></entry></row>
448
449 <row>
450 <entry valign="middle" morerows="4"><literal>macaddr_minmax_multi_ops</literal></entry>
451 <entry><literal>= (macaddr,macaddr)</literal></entry>
452 </row>
453 <row><entry><literal>&lt; (macaddr,macaddr)</literal></entry></row>
454 <row><entry><literal>&lt;= (macaddr,macaddr)</literal></entry></row>
455 <row><entry><literal>&gt; (macaddr,macaddr)</literal></entry></row>
456 <row><entry><literal>&gt;= (macaddr,macaddr)</literal></entry></row>
457
458 <row>
459 <entry valign="middle"><literal>macaddr8_bloom_ops</literal></entry>
460 <entry><literal>= (macaddr8,macaddr8)</literal></entry>
461 </row>
462
463 <row>
464 <entry valign="middle" morerows="4"><literal>macaddr8_minmax_ops</literal></entry>
465 <entry><literal>= (macaddr8,macaddr8)</literal></entry>
466 </row>
467 <row><entry><literal>&lt; (macaddr8,macaddr8)</literal></entry></row>
468 <row><entry><literal>&lt;= (macaddr8,macaddr8)</literal></entry></row>
469 <row><entry><literal>&gt; (macaddr8,macaddr8)</literal></entry></row>
470 <row><entry><literal>&gt;= (macaddr8,macaddr8)</literal></entry></row>
471
472 <row>
473 <entry valign="middle" morerows="4"><literal>macaddr8_minmax_multi_ops</literal></entry>
474 <entry><literal>= (macaddr8,macaddr8)</literal></entry>
475 </row>
476 <row><entry><literal>&lt; (macaddr8,macaddr8)</literal></entry></row>
477 <row><entry><literal>&lt;= (macaddr8,macaddr8)</literal></entry></row>
478 <row><entry><literal>&gt; (macaddr8,macaddr8)</literal></entry></row>
479 <row><entry><literal>&gt;= (macaddr8,macaddr8)</literal></entry></row>
480
481 <row>
482 <entry valign="middle"><literal>name_bloom_ops</literal></entry>
483 <entry><literal>= (name,name)</literal></entry>
484 </row>
485
486 <row>
487 <entry valign="middle" morerows="4"><literal>name_minmax_ops</literal></entry>
488 <entry><literal>= (name,name)</literal></entry>
489 </row>
490 <row><entry><literal>&lt; (name,name)</literal></entry></row>
491 <row><entry><literal>&lt;= (name,name)</literal></entry></row>
492 <row><entry><literal>&gt; (name,name)</literal></entry></row>
493 <row><entry><literal>&gt;= (name,name)</literal></entry></row>
494
495 <row>
496 <entry valign="middle"><literal>numeric_bloom_ops</literal></entry>
497 <entry><literal>= (numeric,numeric)</literal></entry>
498 </row>
499
500 <row>
501 <entry valign="middle" morerows="4"><literal>numeric_minmax_ops</literal></entry>
502 <entry><literal>= (numeric,numeric)</literal></entry>
503 </row>
504 <row><entry><literal>&lt; (numeric,numeric)</literal></entry></row>
505 <row><entry><literal>&lt;= (numeric,numeric)</literal></entry></row>
506 <row><entry><literal>&gt; (numeric,numeric)</literal></entry></row>
507 <row><entry><literal>&gt;= (numeric,numeric)</literal></entry></row>
508
509 <row>
510 <entry valign="middle" morerows="4"><literal>numeric_minmax_multi_ops</literal></entry>
511 <entry><literal>= (numeric,numeric)</literal></entry>
512 </row>
513 <row><entry><literal>&lt; (numeric,numeric)</literal></entry></row>
514 <row><entry><literal>&lt;= (numeric,numeric)</literal></entry></row>
515 <row><entry><literal>&gt; (numeric,numeric)</literal></entry></row>
516 <row><entry><literal>&gt;= (numeric,numeric)</literal></entry></row>
517
518 <row>
519 <entry valign="middle"><literal>oid_bloom_ops</literal></entry>
520 <entry><literal>= (oid,oid)</literal></entry>
521 </row>
522
523 <row>
524 <entry valign="middle" morerows="4"><literal>oid_minmax_ops</literal></entry>
525 <entry><literal>= (oid,oid)</literal></entry>
526 </row>
527 <row><entry><literal>&lt; (oid,oid)</literal></entry></row>
528 <row><entry><literal>&gt; (oid,oid)</literal></entry></row>
529 <row><entry><literal>&lt;= (oid,oid)</literal></entry></row>
530 <row><entry><literal>&gt;= (oid,oid)</literal></entry></row>
531
532 <row>
533 <entry valign="middle" morerows="4"><literal>oid_minmax_multi_ops</literal></entry>
534 <entry><literal>= (oid,oid)</literal></entry>
535 </row>
536 <row><entry><literal>&lt; (oid,oid)</literal></entry></row>
537 <row><entry><literal>&gt; (oid,oid)</literal></entry></row>
538 <row><entry><literal>&lt;= (oid,oid)</literal></entry></row>
539 <row><entry><literal>&gt;= (oid,oid)</literal></entry></row>
540
541 <row>
542 <entry valign="middle"><literal>pg_lsn_bloom_ops</literal></entry>
543 <entry><literal>= (pg_lsn,pg_lsn)</literal></entry>
544 </row>
545
546 <row>
547 <entry valign="middle" morerows="4"><literal>pg_lsn_minmax_ops</literal></entry>
548 <entry><literal>= (pg_lsn,pg_lsn)</literal></entry>
549 </row>
550 <row><entry><literal>&lt; (pg_lsn,pg_lsn)</literal></entry></row>
551 <row><entry><literal>&gt; (pg_lsn,pg_lsn)</literal></entry></row>
552 <row><entry><literal>&lt;= (pg_lsn,pg_lsn)</literal></entry></row>
553 <row><entry><literal>&gt;= (pg_lsn,pg_lsn)</literal></entry></row>
554
555 <row>
556 <entry valign="middle" morerows="4"><literal>pg_lsn_minmax_multi_ops</literal></entry>
557 <entry><literal>= (pg_lsn,pg_lsn)</literal></entry>
558 </row>
559 <row><entry><literal>&lt; (pg_lsn,pg_lsn)</literal></entry></row>
560 <row><entry><literal>&gt; (pg_lsn,pg_lsn)</literal></entry></row>
561 <row><entry><literal>&lt;= (pg_lsn,pg_lsn)</literal></entry></row>
562 <row><entry><literal>&gt;= (pg_lsn,pg_lsn)</literal></entry></row>
563
564 <row>
565 <entry valign="middle" morerows="13"><literal>range_inclusion_ops</literal></entry>
566 <entry><literal>= (anyrange,anyrange)</literal></entry>
567 </row>
568 <row><entry><literal>&lt; (anyrange,anyrange)</literal></entry></row>
569 <row><entry><literal>&lt;= (anyrange,anyrange)</literal></entry></row>
570 <row><entry><literal>&gt;= (anyrange,anyrange)</literal></entry></row>
571 <row><entry><literal>&gt; (anyrange,anyrange)</literal></entry></row>
572 <row><entry><literal>&amp;&amp; (anyrange,anyrange)</literal></entry></row>
573 <row><entry><literal>@&gt; (anyrange,anyelement)</literal></entry></row>
574 <row><entry><literal>@&gt; (anyrange,anyrange)</literal></entry></row>
575 <row><entry><literal>&lt;@ (anyrange,anyrange)</literal></entry></row>
576 <row><entry><literal>&lt;&lt; (anyrange,anyrange)</literal></entry></row>
577 <row><entry><literal>&gt;&gt; (anyrange,anyrange)</literal></entry></row>
578 <row><entry><literal>&amp;&lt; (anyrange,anyrange)</literal></entry></row>
579 <row><entry><literal>&amp;&gt; (anyrange,anyrange)</literal></entry></row>
580 <row><entry><literal>-|- (anyrange,anyrange)</literal></entry></row>
581
582 <row>
583 <entry valign="middle"><literal>text_bloom_ops</literal></entry>
584 <entry><literal>= (text,text)</literal></entry>
585 </row>
586
587 <row>
588 <entry valign="middle" morerows="4"><literal>text_minmax_ops</literal></entry>
589 <entry><literal>= (text,text)</literal></entry>
590 </row>
591 <row><entry><literal>&lt; (text,text)</literal></entry></row>
592 <row><entry><literal>&lt;= (text,text)</literal></entry></row>
593 <row><entry><literal>&gt; (text,text)</literal></entry></row>
594 <row><entry><literal>&gt;= (text,text)</literal></entry></row>
595
596 <row>
597 <entry valign="middle"><literal>tid_bloom_ops</literal></entry>
598 <entry><literal>= (tid,tid)</literal></entry>
599 </row>
600
601 <row>
602 <entry valign="middle" morerows="4"><literal>tid_minmax_ops</literal></entry>
603 <entry><literal>= (tid,tid)</literal></entry>
604 </row>
605 <row><entry><literal>&lt; (tid,tid)</literal></entry></row>
606 <row><entry><literal>&gt; (tid,tid)</literal></entry></row>
607 <row><entry><literal>&lt;= (tid,tid)</literal></entry></row>
608 <row><entry><literal>&gt;= (tid,tid)</literal></entry></row>
609
610 <row>
611 <entry valign="middle" morerows="4"><literal>tid_minmax_multi_ops</literal></entry>
612 <entry><literal>= (tid,tid)</literal></entry>
613 </row>
614 <row><entry><literal>&lt; (tid,tid)</literal></entry></row>
615 <row><entry><literal>&gt; (tid,tid)</literal></entry></row>
616 <row><entry><literal>&lt;= (tid,tid)</literal></entry></row>
617 <row><entry><literal>&gt;= (tid,tid)</literal></entry></row>
618
619 <row>
620 <entry valign="middle"><literal>timestamp_bloom_ops</literal></entry>
621 <entry><literal>= (timestamp,timestamp)</literal></entry>
622 </row>
623
624 <row>
625 <entry valign="middle" morerows="4"><literal>timestamp_minmax_ops</literal></entry>
626 <entry><literal>= (timestamp,timestamp)</literal></entry>
627 </row>
628 <row><entry><literal>&lt; (timestamp,timestamp)</literal></entry></row>
629 <row><entry><literal>&lt;= (timestamp,timestamp)</literal></entry></row>
630 <row><entry><literal>&gt; (timestamp,timestamp)</literal></entry></row>
631 <row><entry><literal>&gt;= (timestamp,timestamp)</literal></entry></row>
632
633 <row>
634 <entry valign="middle" morerows="4"><literal>timestamp_minmax_multi_ops</literal></entry>
635 <entry><literal>= (timestamp,timestamp)</literal></entry>
636 </row>
637 <row><entry><literal>&lt; (timestamp,timestamp)</literal></entry></row>
638 <row><entry><literal>&lt;= (timestamp,timestamp)</literal></entry></row>
639 <row><entry><literal>&gt; (timestamp,timestamp)</literal></entry></row>
640 <row><entry><literal>&gt;= (timestamp,timestamp)</literal></entry></row>
641
642 <row>
643 <entry valign="middle"><literal>timestamptz_bloom_ops</literal></entry>
644 <entry><literal>= (timestamptz,timestamptz)</literal></entry>
645 </row>
646
647 <row>
648 <entry valign="middle" morerows="4"><literal>timestamptz_minmax_ops</literal></entry>
649 <entry><literal>= (timestamptz,timestamptz)</literal></entry>
650 </row>
651 <row><entry><literal>&lt; (timestamptz,timestamptz)</literal></entry></row>
652 <row><entry><literal>&lt;= (timestamptz,timestamptz)</literal></entry></row>
653 <row><entry><literal>&gt; (timestamptz,timestamptz)</literal></entry></row>
654 <row><entry><literal>&gt;= (timestamptz,timestamptz)</literal></entry></row>
655
656 <row>
657 <entry valign="middle" morerows="4"><literal>timestamptz_minmax_multi_ops</literal></entry>
658 <entry><literal>= (timestamptz,timestamptz)</literal></entry>
659 </row>
660 <row><entry><literal>&lt; (timestamptz,timestamptz)</literal></entry></row>
661 <row><entry><literal>&lt;= (timestamptz,timestamptz)</literal></entry></row>
662 <row><entry><literal>&gt; (timestamptz,timestamptz)</literal></entry></row>
663 <row><entry><literal>&gt;= (timestamptz,timestamptz)</literal></entry></row>
664
665 <row>
666 <entry valign="middle"><literal>time_bloom_ops</literal></entry>
667 <entry><literal>= (time,time)</literal></entry>
668 </row>
669
670 <row>
671 <entry valign="middle" morerows="4"><literal>time_minmax_ops</literal></entry>
672 <entry><literal>= (time,time)</literal></entry>
673 </row>
674 <row><entry><literal>&lt; (time,time)</literal></entry></row>
675 <row><entry><literal>&lt;= (time,time)</literal></entry></row>
676 <row><entry><literal>&gt; (time,time)</literal></entry></row>
677 <row><entry><literal>&gt;= (time,time)</literal></entry></row>
678
679 <row>
680 <entry valign="middle" morerows="4"><literal>time_minmax_multi_ops</literal></entry>
681 <entry><literal>= (time,time)</literal></entry>
682 </row>
683 <row><entry><literal>&lt; (time,time)</literal></entry></row>
684 <row><entry><literal>&lt;= (time,time)</literal></entry></row>
685 <row><entry><literal>&gt; (time,time)</literal></entry></row>
686 <row><entry><literal>&gt;= (time,time)</literal></entry></row>
687
688 <row>
689 <entry valign="middle"><literal>timetz_bloom_ops</literal></entry>
690 <entry><literal>= (timetz,timetz)</literal></entry>
691 </row>
692
693 <row>
694 <entry valign="middle" morerows="4"><literal>timetz_minmax_ops</literal></entry>
695 <entry><literal>= (timetz,timetz)</literal></entry>
696 </row>
697 <row><entry><literal>&lt; (timetz,timetz)</literal></entry></row>
698 <row><entry><literal>&lt;= (timetz,timetz)</literal></entry></row>
699 <row><entry><literal>&gt; (timetz,timetz)</literal></entry></row>
700 <row><entry><literal>&gt;= (timetz,timetz)</literal></entry></row>
701
702 <row>
703 <entry valign="middle" morerows="4"><literal>timetz_minmax_multi_ops</literal></entry>
704 <entry><literal>= (timetz,timetz)</literal></entry>
705 </row>
706 <row><entry><literal>&lt; (timetz,timetz)</literal></entry></row>
707 <row><entry><literal>&lt;= (timetz,timetz)</literal></entry></row>
708 <row><entry><literal>&gt; (timetz,timetz)</literal></entry></row>
709 <row><entry><literal>&gt;= (timetz,timetz)</literal></entry></row>
710
711 <row>
712 <entry valign="middle"><literal>uuid_bloom_ops</literal></entry>
713 <entry><literal>= (uuid,uuid)</literal></entry>
714 </row>
715
716 <row>
717 <entry valign="middle" morerows="4"><literal>uuid_minmax_ops</literal></entry>
718 <entry><literal>= (uuid,uuid)</literal></entry>
719 </row>
720 <row><entry><literal>&lt; (uuid,uuid)</literal></entry></row>
721 <row><entry><literal>&gt; (uuid,uuid)</literal></entry></row>
722 <row><entry><literal>&lt;= (uuid,uuid)</literal></entry></row>
723 <row><entry><literal>&gt;= (uuid,uuid)</literal></entry></row>
724
725 <row>
726 <entry valign="middle" morerows="4"><literal>uuid_minmax_multi_ops</literal></entry>
727 <entry><literal>= (uuid,uuid)</literal></entry>
728 </row>
729 <row><entry><literal>&lt; (uuid,uuid)</literal></entry></row>
730 <row><entry><literal>&gt; (uuid,uuid)</literal></entry></row>
731 <row><entry><literal>&lt;= (uuid,uuid)</literal></entry></row>
732 <row><entry><literal>&gt;= (uuid,uuid)</literal></entry></row>
733
734 <row>
735 <entry valign="middle" morerows="4"><literal>varbit_minmax_ops</literal></entry>
736 <entry><literal>= (varbit,varbit)</literal></entry>
737 </row>
738 <row><entry><literal>&lt; (varbit,varbit)</literal></entry></row>
739 <row><entry><literal>&gt; (varbit,varbit)</literal></entry></row>
740 <row><entry><literal>&lt;= (varbit,varbit)</literal></entry></row>
741 <row><entry><literal>&gt;= (varbit,varbit)</literal></entry></row>
742 </tbody>
743 </tgroup>
744 </table>
745
746 <sect3 id="brin-builtin-opclasses--parameters">
747 <title>Operator Class Parameters</title>
748
749 <para>
750 Some of the built-in operator classes allow specifying parameters affecting
751 behavior of the operator class. Each operator class has its own set of
752 allowed parameters. Only the <literal>bloom</literal> and <literal>minmax-multi</literal>
753 operator classes allow specifying parameters:
754 </para>
755
756 <para>
757 bloom operator classes accept these parameters:
758 </para>
759
760 <variablelist>
761 <varlistentry>
762 <term><literal>n_distinct_per_range</literal></term>
763 <listitem>
764 <para>
765 Defines the estimated number of distinct non-null values in the block
766 range, used by <acronym>BRIN</acronym> bloom indexes for sizing of the
767 Bloom filter. It behaves similarly to <literal>n_distinct</literal> option
768 for <xref linkend="sql-altertable"/>. When set to a positive value,
769 each block range is assumed to contain this number of distinct non-null
770 values. When set to a negative value, which must be greater than or
771 equal to -1, the number of distinct non-null values is assumed to grow linearly with
772 the maximum possible number of tuples in the block range (about 290
773 rows per block). The default value is <literal>-0.1</literal>, and
774 the minimum number of distinct non-null values is <literal>16</literal>.
775 </para>
776 </listitem>
777 </varlistentry>
778
779 <varlistentry>
780 <term><literal>false_positive_rate</literal></term>
781 <listitem>
782 <para>
783 Defines the desired false positive rate used by <acronym>BRIN</acronym>
784 bloom indexes for sizing of the Bloom filter. The values must be
785 between 0.0001 and 0.25. The default value is 0.01, which is 1% false
786 positive rate.
787 </para>
788 </listitem>
789 </varlistentry>
790
791 </variablelist>
792
793 <para>
794 minmax-multi operator classes accept these parameters:
795 </para>
796
797 <variablelist>
798 <varlistentry>
799 <term><literal>values_per_range</literal></term>
800 <listitem>
801 <para>
802 Defines the maximum number of values stored by <acronym>BRIN</acronym>
803 minmax indexes to summarize a block range. Each value may represent
804 either a point, or a boundary of an interval. Values must be between
805 8 and 256, and the default value is 32.
806 </para>
807 </listitem>
808 </varlistentry>
809
810 </variablelist>
811 </sect3>
812
813 </sect2>
814
815 <sect2 id="brin-extensibility">
816 <title>Extensibility</title>
817
818 <para>
819 The <acronym>BRIN</acronym> interface has a high level of abstraction,
820 requiring the access method implementer only to implement the semantics
821 of the data type being accessed. The <acronym>BRIN</acronym> layer
822 itself takes care of concurrency, logging and searching the index structure.
823 </para>
824
825 <para>
826 All it takes to get a <acronym>BRIN</acronym> access method working is to
827 implement a few user-defined methods, which define the behavior of
828 summary values stored in the index and the way they interact with
829 scan keys.
830 In short, <acronym>BRIN</acronym> combines
831 extensibility with generality, code reuse, and a clean interface.
832 </para>
833
834 <para>
835 There are four methods that an operator class for <acronym>BRIN</acronym>
836 must provide:
837
838 <variablelist>
839 <varlistentry>
840 <term><function>BrinOpcInfo *opcInfo(Oid type_oid)</function></term>
841 <listitem>
842 <para>
843 Returns internal information about the indexed columns' summary data.
844 The return value must point to a palloc'd <structname>BrinOpcInfo</structname>,
845 which has this definition:
846 <programlisting>
847 typedef struct BrinOpcInfo
848 {
849 /* Number of columns stored in an index column of this opclass */
850 uint16 oi_nstored;
851
852 /* Opaque pointer for the opclass' private use */
853 void *oi_opaque;
854
855 /* Type cache entries of the stored columns */
856 TypeCacheEntry *oi_typcache[FLEXIBLE_ARRAY_MEMBER];
857 } BrinOpcInfo;
858 </programlisting>
859 <structname>BrinOpcInfo</structname>.<structfield>oi_opaque</structfield> can be used by the
860 operator class routines to pass information between support functions
861 during an index scan.
862 </para>
863 </listitem>
864 </varlistentry>
865
866 <varlistentry>
867 <term><function>bool consistent(BrinDesc *bdesc, BrinValues *column,
868 ScanKey *keys, int nkeys)</function></term>
869 <listitem>
870 <para>
871 Returns whether all the ScanKey entries are consistent with the given
872 indexed values for a range.
873 The attribute number to use is passed as part of the scan key.
874 Multiple scan keys for the same attribute may be passed at once; the
875 number of entries is determined by the <literal>nkeys</literal> parameter.
876 </para>
877 </listitem>
878 </varlistentry>
879
880 <varlistentry>
881 <term><function>bool consistent(BrinDesc *bdesc, BrinValues *column,
882 ScanKey key)</function></term>
883 <listitem>
884 <para>
885 Returns whether the ScanKey is consistent with the given indexed
886 values for a range.
887 The attribute number to use is passed as part of the scan key.
888 This is an older backward-compatible variant of the consistent function.
889 </para>
890 </listitem>
891 </varlistentry>
892
893 <varlistentry>
894 <term><function>bool addValue(BrinDesc *bdesc, BrinValues *column,
895 Datum newval, bool isnull)</function></term>
896 <listitem>
897 <para>
898 Given an index tuple and an indexed value, modifies the indicated
899 attribute of the tuple so that it additionally represents the new value.
900 If any modification was done to the tuple, <literal>true</literal> is
901 returned.
902 </para>
903 </listitem>
904 </varlistentry>
905
906 <varlistentry>
907 <term><function>bool unionTuples(BrinDesc *bdesc, BrinValues *a,
908 BrinValues *b)</function></term>
909 <listitem>
910 <para>
911 Consolidates two index tuples. Given two index tuples, modifies the
912 indicated attribute of the first of them so that it represents both tuples.
913 The second tuple is not modified.
914 </para>
915 </listitem>
916 </varlistentry>
917 </variablelist>
918
919 An operator class for <acronym>BRIN</acronym> can optionally specify the
920 following method:
921
922 <variablelist>
923 <varlistentry>
924 <term><function>void options(local_relopts *relopts)</function></term>
925 <listitem>
926 <para>
927 Defines a set of user-visible parameters that control operator class
928 behavior.
929 </para>
930
931 <para>
932 The <function>options</function> function is passed a pointer to a
933 <structname>local_relopts</structname> struct, which needs to be
934 filled with a set of operator class specific options. The options
935 can be accessed from other support functions using the
936 <literal>PG_HAS_OPCLASS_OPTIONS()</literal> and
937 <literal>PG_GET_OPCLASS_OPTIONS()</literal> macros.
938 </para>
939
940 <para>
941 Since both key extraction of indexed values and representation of the
942 key in <acronym>BRIN</acronym> are flexible, they may depend on
943 user-specified parameters.
944 </para>
945 </listitem>
946 </varlistentry>
947 </variablelist>
948
949 The core distribution includes support for four types of operator classes:
950 minmax, minmax-multi, inclusion and bloom. Operator class definitions
951 using them are shipped for in-core data types as appropriate. Additional
952 operator classes can be defined by the user for other data types using
953 equivalent definitions, without having to write any source code;
954 appropriate catalog entries being declared is enough. Note that
955 assumptions about the semantics of operator strategies are embedded in the
956 support functions' source code.
957 </para>
958
959 <para>
960 Operator classes that implement completely different semantics are also
961 possible, provided implementations of the four main support functions
962 described above are written. Note that backwards compatibility across major
963 releases is not guaranteed: for example, additional support functions might
964 be required in later releases.
965 </para>
966
967 <para>
968 To write an operator class for a data type that implements a totally
969 ordered set, it is possible to use the minmax support functions
970 alongside the corresponding operators, as shown in
971 <xref linkend="brin-extensibility-minmax-table"/>.
972 All operator class members (functions and operators) are mandatory.
973 </para>
974
975 <table id="brin-extensibility-minmax-table">
976 <title>Function and Support Numbers for Minmax Operator Classes</title>
977 <tgroup cols="2">
978 <colspec colname="col1" colwidth="1*"/>
979 <colspec colname="col2" colwidth="2*"/>
980 <thead>
981 <row>
982 <entry>Operator class member</entry>
983 <entry>Object</entry>
984 </row>
985 </thead>
986 <tbody>
987 <row>
988 <entry>Support Function 1</entry>
989 <entry>internal function <function>brin_minmax_opcinfo()</function></entry>
990 </row>
991 <row>
992 <entry>Support Function 2</entry>
993 <entry>internal function <function>brin_minmax_add_value()</function></entry>
994 </row>
995 <row>
996 <entry>Support Function 3</entry>
997 <entry>internal function <function>brin_minmax_consistent()</function></entry>
998 </row>
999 <row>
1000 <entry>Support Function 4</entry>
1001 <entry>internal function <function>brin_minmax_union()</function></entry>
1002 </row>
1003 <row>
1004 <entry>Operator Strategy 1</entry>
1005 <entry>operator less-than</entry>
1006 </row>
1007 <row>
1008 <entry>Operator Strategy 2</entry>
1009 <entry>operator less-than-or-equal-to</entry>
1010 </row>
1011 <row>
1012 <entry>Operator Strategy 3</entry>
1013 <entry>operator equal-to</entry>
1014 </row>
1015 <row>
1016 <entry>Operator Strategy 4</entry>
1017 <entry>operator greater-than-or-equal-to</entry>
1018 </row>
1019 <row>
1020 <entry>Operator Strategy 5</entry>
1021 <entry>operator greater-than</entry>
1022 </row>
1023 </tbody>
1024 </tgroup>
1025 </table>
1026
1027 <para>
1028 To write an operator class for a complex data type which has values
1029 included within another type, it's possible to use the inclusion support
1030 functions alongside the corresponding operators, as shown
1031 in <xref linkend="brin-extensibility-inclusion-table"/>. It requires
1032 only a single additional function, which can be written in any language.
1033 More functions can be defined for additional functionality. All operators
1034 are optional. Some operators require other operators, as shown as
1035 dependencies on the table.
1036 </para>
1037
1038 <table id="brin-extensibility-inclusion-table">
1039 <title>Function and Support Numbers for Inclusion Operator Classes</title>
1040 <tgroup cols="3">
1041 <colspec colname="col1" colwidth="1*"/>
1042 <colspec colname="col2" colwidth="2*"/>
1043 <colspec colname="col3" colwidth="1*"/>
1044 <thead>
1045 <row>
1046 <entry>Operator class member</entry>
1047 <entry>Object</entry>
1048 <entry>Dependency</entry>
1049 </row>
1050 </thead>
1051 <tbody>
1052 <row>
1053 <entry>Support Function 1</entry>
1054 <entry>internal function <function>brin_inclusion_opcinfo()</function></entry>
1055 <entry></entry>
1056 </row>
1057 <row>
1058 <entry>Support Function 2</entry>
1059 <entry>internal function <function>brin_inclusion_add_value()</function></entry>
1060 <entry></entry>
1061 </row>
1062 <row>
1063 <entry>Support Function 3</entry>
1064 <entry>internal function <function>brin_inclusion_consistent()</function></entry>
1065 <entry></entry>
1066 </row>
1067 <row>
1068 <entry>Support Function 4</entry>
1069 <entry>internal function <function>brin_inclusion_union()</function></entry>
1070 <entry></entry>
1071 </row>
1072 <row>
1073 <entry>Support Function 11</entry>
1074 <entry>function to merge two elements</entry>
1075 <entry></entry>
1076 </row>
1077 <row>
1078 <entry>Support Function 12</entry>
1079 <entry>optional function to check whether two elements are mergeable</entry>
1080 <entry></entry>
1081 </row>
1082 <row>
1083 <entry>Support Function 13</entry>
1084 <entry>optional function to check if an element is contained within another</entry>
1085 <entry></entry>
1086 </row>
1087 <row>
1088 <entry>Support Function 14</entry>
1089 <entry>optional function to check whether an element is empty</entry>
1090 <entry></entry>
1091 </row>
1092 <row>
1093 <entry>Operator Strategy 1</entry>
1094 <entry>operator left-of</entry>
1095 <entry>Operator Strategy 4</entry>
1096 </row>
1097 <row>
1098 <entry>Operator Strategy 2</entry>
1099 <entry>operator does-not-extend-to-the-right-of</entry>
1100 <entry>Operator Strategy 5</entry>
1101 </row>
1102 <row>
1103 <entry>Operator Strategy 3</entry>
1104 <entry>operator overlaps</entry>
1105 <entry></entry>
1106 </row>
1107 <row>
1108 <entry>Operator Strategy 4</entry>
1109 <entry>operator does-not-extend-to-the-left-of</entry>
1110 <entry>Operator Strategy 1</entry>
1111 </row>
1112 <row>
1113 <entry>Operator Strategy 5</entry>
1114 <entry>operator right-of</entry>
1115 <entry>Operator Strategy 2</entry>
1116 </row>
1117 <row>
1118 <entry>Operator Strategy 6, 18</entry>
1119 <entry>operator same-as-or-equal-to</entry>
1120 <entry>Operator Strategy 7</entry>
1121 </row>
1122 <row>
1123 <entry>Operator Strategy 7, 16, 24, 25</entry>
1124 <entry>operator contains-or-equal-to</entry>
1125 <entry></entry>
1126 </row>
1127 <row>
1128 <entry>Operator Strategy 8, 26, 27</entry>
1129 <entry>operator is-contained-by-or-equal-to</entry>
1130 <entry>Operator Strategy 3</entry>
1131 </row>
1132 <row>
1133 <entry>Operator Strategy 9</entry>
1134 <entry>operator does-not-extend-above</entry>
1135 <entry>Operator Strategy 11</entry>
1136 </row>
1137 <row>
1138 <entry>Operator Strategy 10</entry>
1139 <entry>operator is-below</entry>
1140 <entry>Operator Strategy 12</entry>
1141 </row>
1142 <row>
1143 <entry>Operator Strategy 11</entry>
1144 <entry>operator is-above</entry>
1145 <entry>Operator Strategy 9</entry>
1146 </row>
1147 <row>
1148 <entry>Operator Strategy 12</entry>
1149 <entry>operator does-not-extend-below</entry>
1150 <entry>Operator Strategy 10</entry>
1151 </row>
1152 <row>
1153 <entry>Operator Strategy 20</entry>
1154 <entry>operator less-than</entry>
1155 <entry>Operator Strategy 5</entry>
1156 </row>
1157 <row>
1158 <entry>Operator Strategy 21</entry>
1159 <entry>operator less-than-or-equal-to</entry>
1160 <entry>Operator Strategy 5</entry>
1161 </row>
1162 <row>
1163 <entry>Operator Strategy 22</entry>
1164 <entry>operator greater-than</entry>
1165 <entry>Operator Strategy 1</entry>
1166 </row>
1167 <row>
1168 <entry>Operator Strategy 23</entry>
1169 <entry>operator greater-than-or-equal-to</entry>
1170 <entry>Operator Strategy 1</entry>
1171 </row>
1172 </tbody>
1173 </tgroup>
1174 </table>
1175
1176 <para>
1177 Support function numbers 1 through 10 are reserved for the BRIN internal
1178 functions, so the SQL level functions start with number 11. Support
1179 function number 11 is the main function required to build the index.
1180 It should accept two arguments with the same data type as the operator class,
1181 and return the union of them. The inclusion operator class can store union
1182 values with different data types if it is defined with the
1183 <literal>STORAGE</literal> parameter. The return value of the union
1184 function should match the <literal>STORAGE</literal> data type.
1185 </para>
1186
1187 <para>
1188 Support function numbers 12 and 14 are provided to support
1189 irregularities of built-in data types. Function number 12
1190 is used to support network addresses from different families which
1191 are not mergeable. Function number 14 is used to support
1192 empty ranges. Function number 13 is an optional but
1193 recommended one, which allows the new value to be checked before
1194 it is passed to the union function. As the BRIN framework can shortcut
1195 some operations when the union is not changed, using this
1196 function can improve index performance.
1197 </para>
1198
1199 <para>
1200 To write an operator class for a data type that implements only an equality
1201 operator and supports hashing, it is possible to use the bloom support procedures
1202 alongside the corresponding operators, as shown in
1203 <xref linkend="brin-extensibility-bloom-table"/>.
1204 All operator class members (procedures and operators) are mandatory.
1205 </para>
1206
1207 <table id="brin-extensibility-bloom-table">
1208 <title>Procedure and Support Numbers for Bloom Operator Classes</title>
1209 <tgroup cols="2">
1210 <thead>
1211 <row>
1212 <entry>Operator class member</entry>
1213 <entry>Object</entry>
1214 </row>
1215 </thead>
1216 <tbody>
1217 <row>
1218 <entry>Support Procedure 1</entry>
1219 <entry>internal function <function>brin_bloom_opcinfo()</function></entry>
1220 </row>
1221 <row>
1222 <entry>Support Procedure 2</entry>
1223 <entry>internal function <function>brin_bloom_add_value()</function></entry>
1224 </row>
1225 <row>
1226 <entry>Support Procedure 3</entry>
1227 <entry>internal function <function>brin_bloom_consistent()</function></entry>
1228 </row>
1229 <row>
1230 <entry>Support Procedure 4</entry>
1231 <entry>internal function <function>brin_bloom_union()</function></entry>
1232 </row>
1233 <row>
1234 <entry>Support Procedure 5</entry>
1235 <entry>internal function <function>brin_bloom_options()</function></entry>
1236 </row>
1237 <row>
1238 <entry>Support Procedure 11</entry>
1239 <entry>function to compute hash of an element</entry>
1240 </row>
1241 <row>
1242 <entry>Operator Strategy 1</entry>
1243 <entry>operator equal-to</entry>
1244 </row>
1245 </tbody>
1246 </tgroup>
1247 </table>
1248
1249 <para>
1250 Support procedure numbers 1-10 are reserved for the BRIN internal
1251 functions, so the SQL level functions start with number 11. Support
1252 function number 11 is the main function required to build the index.
1253 It should accept one argument with the same data type as the operator class,
1254 and return a hash of the value.
1255 </para>
1256
1257 <para>
1258 The minmax-multi operator class is also intended for data types implementing
1259 a totally ordered set, and may be seen as a simple extension of the minmax
1260 operator class. While minmax operator class summarizes values from each block
1261 range into a single contiguous interval, minmax-multi allows summarization
1262 into multiple smaller intervals to improve handling of outlier values.
1263 It is possible to use the minmax-multi support procedures alongside the
1264 corresponding operators, as shown in
1265 <xref linkend="brin-extensibility-minmax-multi-table"/>.
1266 All operator class members (procedures and operators) are mandatory.
1267 </para>
1268
1269 <table id="brin-extensibility-minmax-multi-table">
1270 <title>Procedure and Support Numbers for minmax-multi Operator Classes</title>
1271 <tgroup cols="2">
1272 <thead>
1273 <row>
1274 <entry>Operator class member</entry>
1275 <entry>Object</entry>
1276 </row>
1277 </thead>
1278 <tbody>
1279 <row>
1280 <entry>Support Procedure 1</entry>
1281 <entry>internal function <function>brin_minmax_multi_opcinfo()</function></entry>
1282 </row>
1283 <row>
1284 <entry>Support Procedure 2</entry>
1285 <entry>internal function <function>brin_minmax_multi_add_value()</function></entry>
1286 </row>
1287 <row>
1288 <entry>Support Procedure 3</entry>
1289 <entry>internal function <function>brin_minmax_multi_consistent()</function></entry>
1290 </row>
1291 <row>
1292 <entry>Support Procedure 4</entry>
1293 <entry>internal function <function>brin_minmax_multi_union()</function></entry>
1294 </row>
1295 <row>
1296 <entry>Support Procedure 5</entry>
1297 <entry>internal function <function>brin_minmax_multi_options()</function></entry>
1298 </row>
1299 <row>
1300 <entry>Support Procedure 11</entry>
1301 <entry>function to compute distance between two values (length of a range)</entry>
1302 </row>
1303 <row>
1304 <entry>Operator Strategy 1</entry>
1305 <entry>operator less-than</entry>
1306 </row>
1307 <row>
1308 <entry>Operator Strategy 2</entry>
1309 <entry>operator less-than-or-equal-to</entry>
1310 </row>
1311 <row>
1312 <entry>Operator Strategy 3</entry>
1313 <entry>operator equal-to</entry>
1314 </row>
1315 <row>
1316 <entry>Operator Strategy 4</entry>
1317 <entry>operator greater-than-or-equal-to</entry>
1318 </row>
1319 <row>
1320 <entry>Operator Strategy 5</entry>
1321 <entry>operator greater-than</entry>
1322 </row>
1323 </tbody>
1324 </tgroup>
1325 </table>
1326
1327 <para>
1328 Both minmax and inclusion operator classes support cross-data-type
1329 operators, though with these the dependencies become more complicated.
1330 The minmax operator class requires a full set of operators to be
1331 defined with both arguments having the same data type. It allows
1332 additional data types to be supported by defining extra sets
1333 of operators. Inclusion operator class operator strategies are dependent
1334 on another operator strategy as shown in
1335 <xref linkend="brin-extensibility-inclusion-table"/>, or the same
1336 operator strategy as themselves. They require the dependency
1337 operator to be defined with the <literal>STORAGE</literal> data type as the
1338 left-hand-side argument and the other supported data type to be the
1339 right-hand-side argument of the supported operator. See
1340 <literal>float4_minmax_ops</literal> as an example of minmax, and
1341 <literal>box_inclusion_ops</literal> as an example of inclusion.
1342 </para>
1343 </sect2>
1344 </sect1>