From 741667c34d40aee3dd5fbca2054643017a7069af Mon Sep 17 00:00:00 2001 From: Emre Hasegeli 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 Operator class member Object 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 operator less-than Operator Strategy 2 operator less-than-or-equal-to @@ -596,12 +596,198 @@ typedef struct BrinOpcInfo Operator Strategy 4 operator greater-than-or-equal-to Operator Strategy 5 operator greater-than + + + 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 . 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. + + + + 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 two elements are mergeable or not + + + + Support Procedure 13 + optional function to check an element is contained within another + + + + Support Procedure 14 + optional function to check an element is empty or not + + + + 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 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. + + + + 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. + + + + 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 + , 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. + -- 2.3.2