8000 Document BRIN a bit more thoroughly · prmdeveloper/postgres@c84c87c · GitHub
[go: up one dir, main page]
Skip to content

Commit c84c87c

Browse files
alvherrealvherre
committed
Document BRIN a bit more thoroughly
The chapter "Interfacing Extensions To Indexes" and CREATE OPERATOR CLASS reference page were missed when BRIN was added. We document all our other index access methods there, so make sure BRIN complies. Author: Álvaro Herrera Reported-By: Julien Rouhaud, Tom Lane Reviewed-By: Emre Hasegeli Discussion: https://www.postgresql.org/message-id/56CF604E.9000303%40dalibo.com Backpatch: 9.5, where BRIN was introduced
1 parent ad9a15d commit c84c87c

File tree

2 files changed

+106
-4
lines changed

2 files changed

+106
-4
lines changed

‎doc/src/sgml/ref/create_opclass.sgml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL
172172
the input data type(s) of the function (for B-tree comparison functions
173173
and hash functions)
174174
or the class's data type (for B-tree sort support functions and all
175-
functions in GiST, SP-GiST and GIN operator classes). These defaults
175+
functions in GiST, SP-GiST, GIN and BRIN operator classes). These defaults
176176
are correct, and so <replaceable
177177
class="parameter">op_type</replaceable> need not be specified in
178178
<literal>FUNCTION</> clauses, except for the case of a B-tree sort
@@ -232,7 +232,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL
232232
<para>
233233
The data type actually stored in the index. Normally this is
234234
the same as the column data type, but some index methods
235-
(currently GiST and GIN) allow it to be different. The
235+
(currently GiST, GIN and BRIN) allow it to be different. The
236236
<literal>STORAGE</> clause must be omitted unless the index
237237
method allows a different type to be used.
238238
</para>

‎doc/src/sgml/xindex.sgml

Lines changed: 104 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,49 @@
322322
</tgroup>
323323
</table>
324324

325+
<para>
326+
BRIN indexes are similar to GiST, SP-GiST and GIN indexes in that they
327+
don't have a fixed set of strategies either. Instead the support routines
328+
of each operator class interpret the strategy numbers according to the
329+
operator class's definition. As an example, the strategy numbers used by
330+
the built-in <literal>Minmax</> operator classes are shown in
331+
<xref linkend="xindex-brin-minmax-strat-table">.
332+
</para>
333+
334+
<table tocentry="1" id="xindex-brin-minmax-strat-table">
335+
<title>BRIN Minmax Strategies</title>
336+
<tgroup cols="2">
337+
<thead>
338+
<row>
339+
<entry>Operation</entry>
340+
<entry>Strategy Number</entry>
341+
</row>
342+
</thead>
343+
<tbody>
344+
<row>
345+
<entry>less than</entry>
346+
<entry>1</entry>
347+
</row>
348+
<row>
349+
<entry>less than or equal</entry>
350+
<entry>2</entry>
351+
</row>
352+
<row>
353+
<entry>equal</entry>
354+
<entry>3</entry>
355+
</row>
356+
<row>
357+
<entry>greater than or equal</entry>
358+
<entry>4</entry>
359+
</row>
360+
<row>
361+
<entry>greater than</entry>
362+
<entry>5</entry>
363+
</row>
364+
</tbody>
365+
</tgroup>
366+
</table>
367+
325368
<para>
326369
Notice that all the operators listed above return Boolean values. In
327370
practice, all operators defined as index method search operators must
@@ -601,6 +644,53 @@
601644
</tgroup>
602645
</table>
603646

647+
<para>
648+
BRIN indexes have four basic support functions, as shown in
649+
<xref linkend="xindex-brin-support-table">; those basic functions
650+
may require additional support functions to be provided.
651+
(For more information see <xref linkend="brin-extensibility">.)
652+
</para>
653+
654+
<table tocentry="1" id="xindex-brin-support-table">
655+
<title>GIN Support Functions</title>
656+
<tgroup cols="3">
657+
<thead>
658+
<row>
659+
<entry>Function</entry>
660+
<entry>Description</entry>
661+
<entry>Support Number</entry>
662+
</row>
663+
</thead>
664+
<tbody>
665+
<row>
666+
<entry><function>opcInfo</></entry>
667+
<entry>
668+
return internal information describing the indexed columns'
669+
summary data
670+
</entry>
671+
<entry>1</entry>
672+
</row>
673+
<row>
674+
<entry><function>add_value</></entry>
675+
<entry>add a new value to an existing summary index tuple</entry>
676+
<entry>2</entry>
677+
</row>
678+
<row>
679+
<entry><function>consistent</></entry>
680+
<entry>determine whether value matches query condition</entry>
681+
<entry>3</entry>
682+
</row>
683+
<row>
684+
<entry><function>union</></entry>
685+
<entry>
686+
compute union of two summary tuples
687+
</entry>
688+
<entry>4</entry>
689+
</row>
690+
</tbody>
691+
</tgroup>
692+
</table>
693+
604694
<para>
605695
Unlike search operators, support functions return whichever data
606696
type the particular index method expects; for example in the case
@@ -609,7 +699,7 @@
609699
dependent on the index method. For B-tree and hash the comparison and
610700
hashing support functions take the same input data types as do the
611701
operators included in the operator class, but this is not the case for
612-
most GiST, SP-GiST, and GIN support functions.
702+
most GiST, SP-GiST, GIN, and BRIN support functions.
613703
</para>
614704
</sect2>
615705

@@ -994,6 +1084,14 @@ ALTER OPERATOR FAMILY integer_ops USING btree ADD
9941084
handle.
9951085
</para>
9961086

1087+
<para>
1088+
In BRIN, the requirements depends on the framework that provides the
1089+
operator classes. For operator classes based on <literal>minmax</>,
1090+
the behavior required is the same as for B-tree operator families:
1091+
all the operators in the family must sort compatibly, and casts must
1092+
not change the associated sort ordering.
1093+
</para>
1094+
9971095
<note>
9981096
<para>
9991097
Prior to <productname>PostgreSQL</productname> 8.3, there was no concept
@@ -1178,7 +1276,7 @@ CREATE OPERATOR CLASS polygon_ops
11781276
STORAGE box;
11791277
</programlisting>
11801278

1181-
At present, only the GiST and GIN index methods support a
1279+
At present, only the GiST, GIN and BRIN index methods support a
11821280
<literal>STORAGE</> type that's different from the column data type.
11831281
The GiST <function>compress</> and <function>decompress</> support
11841282
routines must deal with data-type conversion when <literal>STORAGE</>
@@ -1188,6 +1286,10 @@ CREATE OPERATOR CLASS polygon_ops
11881286
integer-array columns might have keys that are just integers. The
11891287
GIN <function>extractValue</> and <function>extractQuery</> support
11901288
routines are responsible for extracting keys from indexed values.
1289+
BRIN is similar to GIN: the <literal>STORAGE</> type identifies the
1290+
type of the stored summary values, and operator classes' support
1291+
procedures are responsible for interpreting the summary values
1292+
correctly.
11911293
</para>
11921294
</sect2>
11931295

0 commit comments

Comments
 (0)
0