gopgext/brin
import "gopgext/brin"
Package brin writes BRIN operator classes in Go. A BRIN index keeps one small summary per block range (a group of consecutive table pages, 128 by default): scans skip the ranges whose summary can’t match. It suits large tables whose values correlate with their physical order (timestamps, sequences, data loaded in order), at a tiny fraction of a btree’s size.
The extension registers an OpClass under the name of its operator class (in main or a package initializer):
brin.Register("epoch_minmax_ops", brin.OpClass{
Add: addValue, // summary of a range, with one more value
Consistent: mayMatch, // can a range with this summary match the query?
Union: merge, // summary of two ranges
})
and its sql/ files declare the support functions, which all use the C symbols of this package, and the operator class itself:
CREATE FUNCTION epoch_brin_opcinfo(internal) RETURNS internal
AS 'MODULE_PATHNAME', 'gopgext_brin_opcinfo' LANGUAGE C STRICT;
CREATE FUNCTION epoch_brin_add_value(internal, internal, internal, internal) RETURNS boolean
AS 'MODULE_PATHNAME', 'gopgext_brin_add_value' LANGUAGE C STRICT;
CREATE FUNCTION epoch_brin_consistent(internal, internal, internal, integer) RETURNS boolean
AS 'MODULE_PATHNAME', 'gopgext_brin_consistent' LANGUAGE C STRICT;
CREATE FUNCTION epoch_brin_union(internal, internal, internal) RETURNS boolean
AS 'MODULE_PATHNAME', 'gopgext_brin_union' LANGUAGE C STRICT;
CREATE OPERATOR CLASS epoch_minmax_ops DEFAULT FOR TYPE epoch USING brin AS
OPERATOR 1 < , OPERATOR 2 <= , OPERATOR 3 = , OPERATOR 4 >= , OPERATOR 5 > ,
FUNCTION 1 epoch_brin_opcinfo(internal),
FUNCTION 2 epoch_brin_add_value(internal, internal, internal, internal),
FUNCTION 3 epoch_brin_consistent(internal, internal, internal, integer),
FUNCTION 4 epoch_brin_union(internal, internal, internal);
The functions find their OpClass through the operator family of the index column (named like the operator class, unless it was created with FAMILY).
A summary is a []byte the OpClass defines (stored as bytea: keep it small, it’s stored once per range). Values and queries are bytes too: the contents of a variable-size value (a type stored like bytea, e.g. a //gopgext:type over pg.Varlena or string), or the bytes of a fixed-size one (a //gopgext:type over int64 is its 8 bytes, little-endian). All of them are only valid during the call: copy them to keep them. NULLs never reach the functions: BRIN tracks them itself (IS NULL and IS NOT NULL work without the OpClass).
Strategy numbers are the operator numbers of the operator class (3 for = above). Consistent may say a range matches when it doesn’t (a lossy summary, like a Bloom filter): PostgreSQL checks every row of the ranges it returns. It must never say a range doesn’t match when it might: rows would be missing from the results.
Index#
Functions#
func Register#
func Register(family string, oc OpClass)
Register registers the operator class of the operator family family (the name of the operator class, unless it was created with FAMILY).
Types#
type OpClass#
type OpClass struct {
// Add returns the summary of a block range with value added: summary
// is nil for a range without values yet. changed is false if summary
// already covers value (the range isn't rewritten).
Add func(summary, value []byte) (newSummary []byte, changed bool)
// Consistent reports whether a range with this summary may hold rows
// matching query with the operator of the given strategy number. False
// positives are fine (rows are rechecked); false negatives lose rows.
Consistent func(summary []byte, strategy int, query []byte) bool
// Union returns a summary covering the ranges of two summaries.
Union func(a, b []byte) []byte
}
OpClass is a BRIN operator class. All functions are required.