mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document BRIN a bit more thoroughly

Browse Source 
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
This commit is contained in:
Alvaro Herrera 2016-03-10 13:15:08 -03:00
parent 9d90388247
commit a3a8309d45
2 changed files with 106 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/sgml/ref/create_opclass.sgml
View File

@ -172,7 +172,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL
the input data type(s) of the function (for B-tree comparison functions
and hash functions)
or the class's data type (for B-tree sort support functions and all
functions in GiST, SP-GiST and GIN operator classes). These defaults
functions in GiST, SP-GiST, GIN and BRIN operator classes). These defaults
are correct, and so <replaceable
class="parameter">op_type</replaceable> need not be specified in
<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
<para>
The data type actually stored in the index. Normally this is
the same as the column data type, but some index methods
(currently GiST and GIN) allow it to be different. The
(currently GiST, GIN and BRIN) allow it to be different. The
<literal>STORAGE</> clause must be omitted unless the index
method allows a different type to be used.
</para>

106
doc/src/sgml/xindex.sgml
View File

@ -322,6 +322,49 @@
</tgroup>
</table>
<para>
BRIN indexes are similar to GiST, SP-GiST and GIN indexes in that they
don't have a fixed set of strategies either. Instead the support routines
of each operator class interpret the strategy numbers according to the
operator class's definition. As an example, the strategy numbers used by
the built-in <literal>Minmax</> operator classes are shown in
<xref linkend="xindex-brin-minmax-strat-table">.
</para>
<table tocentry="1" id="xindex-brin-minmax-strat-table">
<title>BRIN Minmax Strategies</title>
<tgroup cols="2">
<thead>
<row>
<entry>Operation</entry>
<entry>Strategy Number</entry>
</row>
</thead>
<tbody>
<row>
<entry>less than</entry>
<entry>1</entry>
</row>
<row>
<entry>less than or equal</entry>
<entry>2</entry>
</row>
<row>
<entry>equal</entry>
<entry>3</entry>
</row>
<row>
<entry>greater than or equal</entry>
<entry>4</entry>
</row>
<row>
<entry>greater than</entry>
<entry>5</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Notice that all the operators listed above return Boolean values. In
practice, all operators defined as index method search operators must
@ -601,6 +644,53 @@
</tgroup>
</table>
<para>
BRIN indexes have four basic support functions, as shown in
<xref linkend="xindex-brin-support-table">; those basic functions
may require additional support functions to be provided.
(For more information see <xref linkend="brin-extensibility">.)
</para>
<table tocentry="1" id="xindex-brin-support-table">
<title>GIN Support Functions</title>
<tgroup cols="3">
<thead>
<row>
<entry>Function</entry>
<entry>Description</entry>
<entry>Support Number</entry>
</row>
</thead>
<tbody>
<row>
<entry><function>opcInfo</></entry>
<entry>
return internal information describing the indexed columns'
summary data
</entry>
<entry>1</entry>
</row>
<row>
<entry><function>add_value</></entry>
<entry>add a new value to an existing summary index tuple</entry>
<entry>2</entry>
</row>
<row>
<entry><function>consistent</></entry>
<entry>determine whether value matches query condition</entry>
<entry>3</entry>
</row>
<row>
<entry><function>union</></entry>
<entry>
compute union of two summary tuples
</entry>
<entry>4</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Unlike search operators, support functions return whichever data
type the particular index method expects; for example in the case
@ -609,7 +699,7 @@
dependent on the index method. For B-tree and hash the comparison and
hashing support functions take the same input data types as do the
operators included in the operator class, but this is not the case for
most GiST, SP-GiST, and GIN support functions.
most GiST, SP-GiST, GIN, and BRIN support functions.
</para>
</sect2>
@ -994,6 +1084,14 @@ ALTER OPERATOR FAMILY integer_ops USING btree ADD
handle.
</para>
<para>
In BRIN, the requirements depends on the framework that provides the
operator classes. For operator classes based on <literal>minmax</>,
the behavior required is the same as for B-tree operator families:
all the operators in the family must sort compatibly, and casts must
not change the associated sort ordering.
</para>
<note>
<para>
Prior to <productname>PostgreSQL</productname> 8.3, there was no concept
@ -1178,7 +1276,7 @@ CREATE OPERATOR CLASS polygon_ops
STORAGE box;
</programlisting>
At present, only the GiST and GIN index methods support a
At present, only the GiST, GIN and BRIN index methods support a
<literal>STORAGE</> type that's different from the column data type.
The GiST <function>compress</> and <function>decompress</> support
routines must deal with data-type conversion when <literal>STORAGE</>
@ -1188,6 +1286,10 @@ CREATE OPERATOR CLASS polygon_ops
integer-array columns might have keys that are just integers. The
GIN <function>extractValue</> and <function>extractQuery</> support
routines are responsible for extracting keys from indexed values.
BRIN is similar to GIN: the <literal>STORAGE</> type identifies the
type of the stored summary values, and operator classes' support
procedures are responsible for interpreting the summary values
correctly.
</para>
</sect2>