pgsql: Improve BRIN documentation somewhat
Started by Alvaro Herreraover 10 years ago3 messages
Improve BRIN documentation somewhat
This removes some info about support procedures being used, which was
obsoleted by commit db5f98ab4f, as well as add some more documentation
on how to create new opclasses using the Minmax infrastructure.
(Hopefully we can get something similar for Inclusion as well.)
In passing, fix some obsolete mentions of "mmtuples" in source code
comments.
Backpatch to 9.5, where BRIN was introduced.
Branch
------
master
Details
-------
http://git.postgresql.org/pg/commitdiff/8d9073692430a222939e7f2e436c80f0c271f116
Modified Files
--------------
doc/src/sgml/brin.sgml | 81 +++++++++++++++++++++++++++++++----
src/backend/access/brin/brin.c | 2 +-
src/backend/access/brin/brin_xlog.c | 6 +--
3 files changed, 77 insertions(+), 12 deletions(-)
--
Sent via pgsql-committers mailing list (pgsql-committers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-committers
Re: [COMMITTERS] pgsql: Improve BRIN documentation somewhat
Alvaro Herrera wrote:
Improve BRIN documentation somewhat
This removes some info about support procedures being used, which was
obsoleted by commit db5f98ab4f, as well as add some more documentation
on how to create new opclasses using the Minmax infrastructure.
(Hopefully we can get something similar for Inclusion as well.)
Emre Hasegeli told me on IM he's going to submit a patch to add
something similar for the inclusion opclass framework.
--
�lvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
Re: [COMMITTERS] pgsql: Improve BRIN documentation somewhat
Emre Hasegeli told me on IM he's going to submit a patch to add
something similar for the inclusion opclass framework.
It is attached. Thank you for pushing forward to improve the documentation.
Attachments:
0001-Improve-BRIN-documentation-for-Inclusion-opclass.patchapplication/octet-stream; name=0001-Improve-BRIN-documentation-for-Inclusion-opclass.patchDownload
From 741667c34d40aee3dd5fbca2054643017a7069af Mon Sep 17 00:00:00 2001
From: Emre Hasegeli <emre@hasegeli.com>
Date: Tue, 21 Jul 2015 11:02:41 +0200
Subject: [PATCH] Improve BRIN documentation for Inclusion opclass
---
doc/src/sgml/brin.sgml | 194 ++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 190 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index c8c3de7..3a52a8c 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -559,33 +559,33 @@ typedef struct BrinOpcInfo
<tgroup cols="2">
<thead>
<row>
<entry>Operator class member</entry>
<entry>Object</entry>
</row>
</thead>
<tbody>
<row>
<entry>Support Procedure 1</entry>
- <entry>function <function>brin_minmax_opcinfo()</function></entry>
+ <entry>internal function <function>brin_minmax_opcinfo()</function></entry>
</row>
<row>
<entry>Support Procedure 2</entry>
- <entry>function <function>brin_minmax_add_value()</function></entry>
+ <entry>internal function <function>brin_minmax_add_value()</function></entry>
</row>
<row>
<entry>Support Procedure 3</entry>
- <entry>function <function>brin_minmax_consistent()</function></entry>
+ <entry>internal function <function>brin_minmax_consistent()</function></entry>
</row>
<row>
<entry>Support Procedure 4</entry>
- <entry>function <function>brin_minmax_union()</function></entry>
+ <entry>internal function <function>brin_minmax_union()</function></entry>
</row>
<row>
<entry>Operator Strategy 1</entry>
<entry>operator less-than</entry>
</row>
<row>
<entry>Operator Strategy 2</entry>
<entry>operator less-than-or-equal-to</entry>
</row>
<row>
@@ -596,12 +596,198 @@ typedef struct BrinOpcInfo
<entry>Operator Strategy 4</entry>
<entry>operator greater-than-or-equal-to</entry>
</row>
<row>
<entry>Operator Strategy 5</entry>
<entry>operator greater-than</entry>
</row>
</tbody>
</tgroup>
</table>
+
+ <para>
+ To write an operator class for a complicated datatype that has values
+ included within another, it is possible to use the Inclusion support
+ procedures alongside the corresponding operators, as shown
+ in <xref linkend="brin-extensibility-inclusion-table">. It requires
+ only a single additional function written in any language. More
+ functions can be defined for more functionality. All operators are
+ optional. Some operators require other operators as shown as
+ dependencies on the table.
+ </para>
+
+ <table id="brin-extensibility-inclusion-table">
+ <title>Procedure and Support Numbers for Inclusion Operator Classes</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Operator class member</entry>
+ <entry>Object</entry>
+ <entry>Dependency</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Support Procedure 1</entry>
+ <entry>internal function <function>brin_inclusion_opcinfo()</function></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Support Procedure 2</entry>
+ <entry>internal function <function>brin_inclusion_add_value()</function></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Support Procedure 3</entry>
+ <entry>internal function <function>brin_inclusion_consistent()</function></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Support Procedure 4</entry>
+ <entry>internal function <function>brin_inclusion_union()</function></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Support Procedure 11</entry>
+ <entry>function to merge two elements</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Support Procedure 12</entry>
+ <entry>optional function to check two elements are mergeable or not</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Support Procedure 13</entry>
+ <entry>optional function to check an element is contained within another</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Support Procedure 14</entry>
+ <entry>optional function to check an element is empty or not</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 1</entry>
+ <entry>operator left-of</entry>
+ <entry>Operator Strategy 4</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 2</entry>
+ <entry>operator does-not-extend-to-the-right-of</entry>
+ <entry>Operator Strategy 5</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 3</entry>
+ <entry>operator overlaps</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 4</entry>
+ <entry>operator right-of</entry>
+ <entry>Operator Strategy 2</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 5</entry>
+ <entry>operator does-not-extend-to-the-right-of</entry>
+ <entry>Operator Strategy 1</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 6, 18</entry>
+ <entry>operator same-as-or-equal-to</entry>
+ <entry>Operator Strategy 7</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 7, 13, 16, 24, 25</entry>
+ <entry>operator contains-or-equal-to</entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 8, 14, 26, 27</entry>
+ <entry>operator is-contained-by-or-equal-to</entry>
+ <entry>Operator Strategy 3</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 9</entry>
+ <entry>operator does-not-extend-above</entry>
+ <entry>Operator Strategy 11</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 10</entry>
+ <entry>operator is-below</entry>
+ <entry>Operator Strategy 12</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 11</entry>
+ <entry>operator is-above</entry>
+ <entry>Operator Strategy 9</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 12</entry>
+ <entry>operator does-not-extend-below</entry>
+ <entry>Operator Strategy 10</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 20</entry>
+ <entry>operator less-than</entry>
+ <entry>Operator Strategy 4</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 21</entry>
+ <entry>operator less-than-or-equal-to</entry>
+ <entry>Operator Strategy 4</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 22</entry>
+ <entry>operator greater-than</entry>
+ <entry>Operator Strategy 1</entry>
+ </row>
+ <row>
+ <entry>Operator Strategy 23</entry>
+ <entry>operator greater-than-or-equal-to</entry>
+ <entry>Operator Strategy 1</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ Support procedure numbers 1-10 are reserved for the BRIN internal
+ functions, so the SQL level functions start with number 11. Support
+ function number 11 is the main function which is required to
+ build the index. It should accept two arguments with the same
+ datatype as the opclass and return the union of them. Inclusion
+ opclass can store the union values with different datatype, when
+ it is defined with STORAGE parameter. The return value of the union
+ function should match the STORAGE datatype.
+ </para>
+
+ <para>
+ Support procedure numbers 12 and 14 are provided to support
+ irregularities of built-in datatypes. The procedure number 12
+ is used to support network address with different families which
+ are not mergeable. The procedure number 14 is used to support
+ empty ranges. The procedure number 13 is an optional but
+ recommended one. It allows the new value to be checked before
+ it passed to the union function. BRIN framework would shortcut
+ some operations when the union is not changed. Therefore, this
+ function would improve the index performance.
+ </para>
+
+ <para>
+ Both Minmax and Inclusion opclasses support cross-datatype
+ operators, though the dependencies get more complicated with
+ them. The Minmax opclass requires full set of operators to be
+ defined with both arguments with the same datatype. It allows
+ additional datatypes to be supported by defining extra sets
+ of operators. Inclusion opclass operator strategies are dependent
+ to another operator strategy as shown on
+ <xref linkend="brin-extensibility-inclusion-table">, or the same
+ operator strategy as themselves. They require the dependency
+ operator to be defined with the STORAGE datatype as the left-hand-side
+ argument and the other supported datatype to be the right-hand-side
+ argument of the supported operator. See <literal>float4_minmax_ops</>
+ as an example of Minmax, and <literal>box_inclusion_ops</>
+ as an example of Inclusion.
+ </para>
</sect1>
</chapter>
--
2.3.2