doc/src/sgml/brin.sgml

   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>