From 8d9073692430a222939e7f2e436c80f0c271f116 Mon Sep 17 00:00:00 2001 From: Alvaro Herrera Date: Mon, 20 Jul 2015 12:16:40 +0200 Subject: [PATCH] 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. --- 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(-) diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml index cdfe5dec56..c8c3de72e3 100644 --- a/doc/src/sgml/brin.sgml +++ b/doc/src/sgml/brin.sgml @@ -529,14 +529,79 @@ typedef struct BrinOpcInfo - To implement these methods in a generic way, the operator class - defines its own internal support functions. - (For instance, the min/max operator classes implement - support functions for the four inequality operators for their data type.) - Additionally, the operator class must supply appropriate - operator entries, - to enable the optimizer to use the index when those operators are - used in queries. + The core distribution includes support for two types of operator classes: + minmax and inclusion. Operator class definitions using them are shipped for + in-core data types as appropriate. Additional operator classes can be + defined by the user for other datatypes 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. + + + Operator classes that implement completely different semantics are also + possible, provided implementations of the four main support procedures + described above are written. Note that backwards compatibility across major + releases is not guaranteed: for example, additional support procedures might + be required in later releases. + + + + To write an operator class for a datatype that implements a totally + ordered set, it is possible to use the Minmax support procedures + alongside the corresponding operators, as shown in + . + All operator class members (procedures and operators) are mandatory. + + + + Procedure and Support Numbers for Minmax Operator Classes + + + + Operator class member + Object + + + + + Support Procedure 1 + function brin_minmax_opcinfo() + + + Support Procedure 2 + function brin_minmax_add_value() + + + Support Procedure 3 + function brin_minmax_consistent() + + + Support Procedure 4 + function brin_minmax_union() + + + Operator Strategy 1 + operator less-than + + + Operator Strategy 2 + operator less-than-or-equal-to + + + Operator Strategy 3 + operator equal-to + + + Operator Strategy 4 + operator greater-than-or-equal-to + + + Operator Strategy 5 + operator greater-than + + + +
diff --git a/src/backend/access/brin/brin.c b/src/backend/access/brin/brin.c index ff18b220c2..268a55e71f 100644 --- a/src/backend/access/brin/brin.c +++ b/src/backend/access/brin/brin.c @@ -688,7 +688,7 @@ brinbuildempty(PG_FUNCTION_ARGS) * * XXX we could mark item tuples as "dirty" (when a minimum or maximum heap * tuple is deleted), meaning the need to re-run summarization on the affected - * range. Need to an extra flag in mmtuples for that. + * range. Need to an extra flag in brintuples for that. */ Datum brinbulkdelete(PG_FUNCTION_ARGS) diff --git a/src/backend/access/brin/brin_xlog.c b/src/backend/access/brin/brin_xlog.c index 0900155292..760f0daf02 100644 --- a/src/backend/access/brin/brin_xlog.c +++ b/src/backend/access/brin/brin_xlog.c @@ -180,11 +180,11 @@ brin_xlog_samepage_update(XLogReaderState *record) if (action == BLK_NEEDS_REDO) { Size tuplen; - BrinTuple *mmtuple; + BrinTuple *brintuple; Page page; OffsetNumber offnum; - mmtuple = (BrinTuple *) XLogRecGetBlockData(record, 0, &tuplen); + brintuple = (BrinTuple *) XLogRecGetBlockData(record, 0, &tuplen); page = (Page) BufferGetPage(buffer); @@ -193,7 +193,7 @@ brin_xlog_samepage_update(XLogReaderState *record) elog(PANIC, "brin_xlog_samepage_update: invalid max offset number"); PageIndexDeleteNoCompact(page, &offnum, 1); - offnum = PageAddItem(page, (Item) mmtuple, tuplen, offnum, true, false); + offnum = PageAddItem(page, (Item) brintuple, tuplen, offnum, true, false); if (offnum == InvalidOffsetNumber) elog(PANIC, "brin_xlog_samepage_update: failed to add tuple");