Skip to content

Commit c15898c

Browse files
alvherrealvherre
committed
Document BRIN's inclusion opclass framework
Backpatch to 9.5 -- this should have been part of b0b7be6, but we didn't have 38b03ca 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/[email protected]
1 parent 21a4e4a commit c15898c

File tree

1 file changed

+191
-5
lines changed

1 file changed

+191
-5
lines changed

‎doc/src/sgml/brin.sgml‎

Lines changed: 191 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -535,7 +535,7 @@ typedef struct BrinOpcInfo
535535
defined by the user for other data types using equivalent definitions,
536536
without having to write any source code; appropriate catalog entries being
537537
declared is enough. Note that assumptions about the semantics of operator
538-
strategies are embedded in the support procedures's source code.
538+
strategies are embedded in the support procedures' source code.
539539
</para>
540540

541541
<para>
@@ -566,19 +566,19 @@ typedef struct BrinOpcInfo
566566
<tbody>
567567
<row>
568568
<entry>Support Procedure 1</entry>
569-
<entry>function <function>brin_minmax_opcinfo()</function></entry>
569+
<entry>internal function <function>brin_minmax_opcinfo()</function></entry>
570570
</row>
571571
<row>
572572
<entry>Support Procedure 2</entry>
573-
<entry>function <function>brin_minmax_add_value()</function></entry>
573+
<entry>internal function <function>brin_minmax_add_value()</function></entry>
574574
</row>
575575
<row>
576576
<entry>Support Procedure 3</entry>
577-
<entry>function <function>brin_minmax_consistent()</function></entry>
577+
<entry>internal function <function>brin_minmax_consistent()</function></entry>
578578
</row>
579579
<row>
580580
<entry>Support Procedure 4</entry>
581-
<entry>function <function>brin_minmax_union()</function></entry>
581+
<entry>internal function <function>brin_minmax_union()</function></entry>
582582
</row>
583583
<row>
584584
<entry>Operator Strategy 1</entry>
@@ -603,5 +603,191 @@ typedef struct BrinOpcInfo
603603
</tbody>
604604
</tgroup>
605605
</table>
606+
607+
<para>
608+
To write an operator class for a complex datatype which has values
609+
included within another type, it's possible to use the inclusion support
610+
procedures alongside the corresponding operators, as shown
611+
in <xref linkend="brin-extensibility-inclusion-table">. It requires
612+
only a single additional function, which can be written in any language.
613+
More functions can be defined for additional functionality. All operators
614+
are optional. Some operators require other operators, as shown as
615+
dependencies on the table.
616+
</para>
617+
618+
<table id="brin-extensibility-inclusion-table">
619+
<title>Procedure and Support Numbers for Inclusion Operator Classes</title>
620+
<tgroup cols="3">
621+
<thead>
622+
<row>
623+
<entry>Operator class member</entry>
624+
<entry>Object</entry>
625+
<entry>Dependency</entry>
626+
</row>
627+
</thead>
628+
<tbody>
629+
<row>
630+
<entry>Support Procedure 1</entry>
631+
<entry>internal function <function>brin_inclusion_opcinfo()</function></entry>
632+
<entry></entry>
633+
</row>
634+
<row>
635+
<entry>Support Procedure 2</entry>
636+
<entry>internal function <function>brin_inclusion_add_value()</function></entry>
637+
<entry></entry>
638+
</row>
639+
<row>
640+
<entry>Support Procedure 3</entry>
641+
<entry>internal function <function>brin_inclusion_consistent()</function></entry>
642+
<entry></entry>
643+
</row>
644+
<row>
645+
<entry>Support Procedure 4</entry>
646+
<entry>internal function <function>brin_inclusion_union()</function></entry>
647+
<entry></entry>
648+
</row>
649+
<row>
650+
<entry>Support Procedure 11</entry>
651+
<entry>function to merge two elements</entry>
652+
<entry></entry>
653+
</row>
654+
<row>
655+
<entry>Support Procedure 12</entry>
656+
<entry>optional function to check whether two elements are mergeable</entry>
657+
<entry></entry>
658+
</row>
659+
<row>
660+
<entry>Support Procedure 13</entry>
661+
<entry>optional function to check if an element is contained within another</entry>
662+
<entry></entry>
663+
</row>
664+
<row>
665+
<entry>Support Procedure 14</entry>
666+
<entry>optional function to check whether an element is empty</entry>
667+
<entry></entry>
668+
</row>
669+
<row>
670+
<entry>Operator Strategy 1</entry>
671+
<entry>operator left-of</entry>
672+
<entry>Operator Strategy 4</entry>
673+
</row>
674+
<row>
675+
<entry>Operator Strategy 2</entry>
676+
<entry>operator does-not-extend-to-the-right-of</entry>
677+
<entry>Operator Strategy 5</entry>
678+
</row>
679+
<row>
680+
<entry>Operator Strategy 3</entry>
681+
<entry>operator overlaps</entry>
682+
<entry></entry>
683+
</row>
684+
<row>
685+
<entry>Operator Strategy 4</entry>
686+
<entry>operator right-of</entry>
687+
<entry>Operator Strategy 2</entry>
688+
</row>
689+
<row>
690+
<entry>Operator Strategy 5</entry>
691+
<entry>operator does-not-extend-to-the-right-of</entry>
692+
<entry>Operator Strategy 1</entry>
693+
</row>
694+
<row>
695+
<entry>Operator Strategy 6, 18</entry>
696+
<entry>operator same-as-or-equal-to</entry>
697+
<entry>Operator Strategy 7</entry>
698+
</row>
699+
<row>
700+
<entry>Operator Strategy 7, 13, 16, 24, 25</entry>
701+
<entry>operator contains-or-equal-to</entry>
702+
<entry></entry>
703+
</row>
704+
<row>
705+
<entry>Operator Strategy 8, 14, 26, 27</entry>
706+
<entry>operator is-contained-by-or-equal-to</entry>
707+
<entry>Operator Strategy 3</entry>
708+
</row>
709+
<row>
710+
<entry>Operator Strategy 9</entry>
711+
<entry>operator does-not-extend-above</entry>
712+
<entry>Operator Strategy 11</entry>
713+
</row>
714+
<row>
715+
<entry>Operator Strategy 10</entry>
716+
<entry>operator is-below</entry>
717+
<entry>Operator Strategy 12</entry>
718+
</row>
719+
<row>
720+
<entry>Operator Strategy 11</entry>
721+
<entry>operator is-above</entry>
722+
<entry>Operator Strategy 9</entry>
723+
</row>
724+
<row>
725+
<entry>Operator Strategy 12</entry>
726+
<entry>operator does-not-extend-below</entry>
727+
<entry>Operator Strategy 10</entry>
728+
</row>
729+
<row>
730+
<entry>Operator Strategy 20</entry>
731+
<entry>operator less-than</entry>
732+
<entry>Operator Strategy 4</entry>
733+
</row>
734+
<row>
735+
<entry>Operator Strategy 21</entry>
736+
<entry>operator less-than-or-equal-to</entry>
737+
<entry>Operator Strategy 4</entry>
738+
</row>
739+
<row>
740+
<entry>Operator Strategy 22</entry>
741+
<entry>operator greater-than</entry>
742+
<entry>Operator Strategy 1</entry>
743+
</row>
744+
<row>
745+
<entry>Operator Strategy 23</entry>
746+
<entry>operator greater-than-or-equal-to</entry>
747+
<entry>Operator Strategy 1</entry>
748+
</row>
749+
</tbody>
750+
</tgroup>
751+
</table>
752+
753+
<para>
754+
Support procedure numbers 1-10 are reserved for the BRIN internal
755+
functions, so the SQL level functions start with number 11. Support
756+
function number 11 is the main function required to build the index.
757+
It should accept two arguments with the same datatype as the opclass,
758+
and return the union of them. The inclusion opclass can store union
759+
values with different datatypes if it is defined with the
760+
<literal>STORAGE</> parameter. The return value of the union
761+
function should match the <literal>STORAGE</> datatype.
762+
</para>
763+
764+
<para>
765+
Support procedure numbers 12 and 14 are provided to support
766+
irregularities of built-in datatypes. Procedure number 12
767+
is used to support network addresses from different families which
768+
are not mergeable. Procedure number 14 is used to support
769+
empty ranges. Procedure number 13 is an optional but
770+
recommended one, which allows the new value to be checked before
771+
it is passed to the union function. As the BRIN framework can shortcut
772+
some operations when the union is not changed, using this
773+
function can improve index performance.
774+
</para>
775+
776+
<para>
777+
Both minmax and inclusion opclasses support cross-datatype
778+
operators, though with these the dependencies become more complicated.
779+
The minmax opclass requires a full set of operators to be
780+
defined with both arguments having the same datatype. It allows
781+
additional datatypes to be supported by defining extra sets
782+
of operators. Inclusion opclass operator strategies are dependent
783+
on another operator strategy as shown in
784+
<xref linkend="brin-extensibility-inclusion-table">, or the same
785+
operator strategy as themselves. They require the dependency
786+
operator to be defined with the <literal>STORAGE</> datatype as the
787+
left-hand-side argument and the other supported datatype to be the
788+
right-hand-side argument of the supported operator. See
789+
<literal>float4_minmax_ops</> as an example of minmax, and
790+
<literal>box_inclusion_ops</> as an example of inclusion.
791+
</para>
606792
</sect1>
607793
</chapter>

0 commit comments

Comments
 (0)