From: Alvaro Herrera Date: Tue, 27 Oct 2015 22:03:15 +0000 (-0300) Subject: Document BRIN's inclusion opclass framework X-Git-Tag: REL9_6_BETA1~1163 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c15898c1d5d53602de097905a90f3dd176e8e7fd;p=postgresql Document BRIN's inclusion opclass framework Backpatch to 9.5 -- this should have been part of b0b7be61337, but we didn't have 38b03caebc5de either at the time. Author: Emre Hasegeli Revised by: Ian Barwick Discussion: http://www.postgresql.org/message-id/CAE2gYzyB39Q9up_-TO6FKhH44pcAM1x6n_Cuj15qKoLoFihUVg@mail.gmail.com http://www.postgresql.org/message-id/562DA711.3020305@2ndquadrant.com --- diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml index dc5405e114..2202b7a099 100644 --- a/doc/src/sgml/brin.sgml +++ b/doc/src/sgml/brin.sgml @@ -535,7 +535,7 @@ typedef struct BrinOpcInfo defined by the user for other data types using equivalent definitions, without having to write any source code; appropriate catalog entries being declared is enough. Note that assumptions about the semantics of operator - strategies are embedded in the support procedures's source code. + strategies are embedded in the support procedures' source code. @@ -566,19 +566,19 @@ typedef struct BrinOpcInfo Support Procedure 1 - function brin_minmax_opcinfo() + internal function brin_minmax_opcinfo() Support Procedure 2 - function brin_minmax_add_value() + internal function brin_minmax_add_value() Support Procedure 3 - function brin_minmax_consistent() + internal function brin_minmax_consistent() Support Procedure 4 - function brin_minmax_union() + internal function brin_minmax_union() Operator Strategy 1 @@ -603,5 +603,191 @@ typedef struct BrinOpcInfo + + + To write an operator class for a complex datatype which has values + included within another type, it's possible to use the inclusion support + procedures alongside the corresponding operators, as shown + in . It requires + only a single additional function, which can be written in any language. + More functions can be defined for additional functionality. All operators + are optional. Some operators require other operators, as shown as + dependencies on the table. + + + + Procedure and Support Numbers for Inclusion Operator Classes + + + + Operator class member + Object + Dependency + + + + + Support Procedure 1 + internal function brin_inclusion_opcinfo() + + + + Support Procedure 2 + internal function brin_inclusion_add_value() + + + + Support Procedure 3 + internal function brin_inclusion_consistent() + + + + Support Procedure 4 + internal function brin_inclusion_union() + + + + Support Procedure 11 + function to merge two elements + + + + Support Procedure 12 + optional function to check whether two elements are mergeable + + + + Support Procedure 13 + optional function to check if an element is contained within another + + + + Support Procedure 14 + optional function to check whether an element is empty + + + + Operator Strategy 1 + operator left-of + Operator Strategy 4 + + + Operator Strategy 2 + operator does-not-extend-to-the-right-of + Operator Strategy 5 + + + Operator Strategy 3 + operator overlaps + + + + Operator Strategy 4 + operator right-of + Operator Strategy 2 + + + Operator Strategy 5 + operator does-not-extend-to-the-right-of + Operator Strategy 1 + + + Operator Strategy 6, 18 + operator same-as-or-equal-to + Operator Strategy 7 + + + Operator Strategy 7, 13, 16, 24, 25 + operator contains-or-equal-to + + + + Operator Strategy 8, 14, 26, 27 + operator is-contained-by-or-equal-to + Operator Strategy 3 + + + Operator Strategy 9 + operator does-not-extend-above + Operator Strategy 11 + + + Operator Strategy 10 + operator is-below + Operator Strategy 12 + + + Operator Strategy 11 + operator is-above + Operator Strategy 9 + + + Operator Strategy 12 + operator does-not-extend-below + Operator Strategy 10 + + + Operator Strategy 20 + operator less-than + Operator Strategy 4 + + + Operator Strategy 21 + operator less-than-or-equal-to + Operator Strategy 4 + + + Operator Strategy 22 + operator greater-than + Operator Strategy 1 + + + Operator Strategy 23 + operator greater-than-or-equal-to + Operator Strategy 1 + + + +
+ + + 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 required to build the index. + It should accept two arguments with the same datatype as the opclass, + and return the union of them. The inclusion opclass can store union + values with different datatypes if it is defined with the + STORAGE parameter. The return value of the union + function should match the STORAGE datatype. + + + + Support procedure numbers 12 and 14 are provided to support + irregularities of built-in datatypes. Procedure number 12 + is used to support network addresses from different families which + are not mergeable. Procedure number 14 is used to support + empty ranges. Procedure number 13 is an optional but + recommended one, which allows the new value to be checked before + it is passed to the union function. As the BRIN framework can shortcut + some operations when the union is not changed, using this + function can improve index performance. + + + + Both minmax and inclusion opclasses support cross-datatype + operators, though with these the dependencies become more complicated. + The minmax opclass requires a full set of operators to be + defined with both arguments having the same datatype. It allows + additional datatypes to be supported by defining extra sets + of operators. Inclusion opclass operator strategies are dependent + on another operator strategy as shown in + , 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 + float4_minmax_ops as an example of minmax, and + box_inclusion_ops as an example of inclusion. +