gopgext/gist

import "gopgext/gist"

Package gist writes the support functions of GiST operator classes in Go: the index method PostGIS, ltree, cube, pg_trgm, range types and many others use. An operator class decides how its keys summarize the values below them; GiST does the rest (the tree, concurrency, WAL, vacuum).

The extension registers an OpClass under the name of its operator class (in main or a package initializer):

gist.Register("box_ops", gist.OpClass{
	Compress:   toBox,      // indexed value -> key (nil: the value is the key)
	Consistent: boxMatches, // can key (or keys below it) match the query?
	Union:      boxUnion,   // the key covering some keys
	Penalty:    boxGrowth,  // the cost of adding a key to a subtree
	PickSplit:  boxSplit,   // splits the keys of a full page in two
	Distance:   boxDist,    // optional: ORDER BY col <-> query (k-NN)
})

and its sql/ files declare the support functions, which all use the C symbols of this package, and the operator class itself:

CREATE FUNCTION shape_gist_consistent(internal, shape, smallint, oid, internal)
	RETURNS boolean AS 'MODULE_PATHNAME', 'gopgext_gist_consistent' LANGUAGE C STRICT;
CREATE FUNCTION shape_gist_union(internal, internal) RETURNS bytea
	AS 'MODULE_PATHNAME', 'gopgext_gist_union' LANGUAGE C STRICT;
CREATE FUNCTION shape_gist_compress(internal) RETURNS internal
	AS 'MODULE_PATHNAME', 'gopgext_gist_compress' LANGUAGE C STRICT;
CREATE FUNCTION shape_gist_penalty(internal, internal, internal) RETURNS internal
	AS 'MODULE_PATHNAME', 'gopgext_gist_penalty' LANGUAGE C STRICT;
CREATE FUNCTION shape_gist_picksplit(internal, internal) RETURNS internal
	AS 'MODULE_PATHNAME', 'gopgext_gist_picksplit' LANGUAGE C STRICT;
CREATE FUNCTION shape_gist_same(bytea, bytea, internal) RETURNS internal
	AS 'MODULE_PATHNAME', 'gopgext_gist_same' LANGUAGE C STRICT;
CREATE FUNCTION shape_gist_distance(internal, shape, smallint, oid, internal)
	RETURNS float8 AS 'MODULE_PATHNAME', 'gopgext_gist_distance' LANGUAGE C STRICT;

CREATE OPERATOR CLASS box_ops DEFAULT FOR TYPE shape USING gist AS
	OPERATOR 3 && , OPERATOR 7 ~ , OPERATOR 8 @ ,
	OPERATOR 15 <-> FOR ORDER BY float_ops,
	FUNCTION 1 shape_gist_consistent (internal, shape, smallint, oid, internal),
	FUNCTION 2 shape_gist_union (internal, internal),
	FUNCTION 3 shape_gist_compress (internal),
	FUNCTION 5 shape_gist_penalty (internal, internal, internal),
	FUNCTION 6 shape_gist_picksplit (internal, internal),
	FUNCTION 7 shape_gist_same (bytea, bytea, internal),
	FUNCTION 8 shape_gist_distance (internal, shape, smallint, oid, internal),
	STORAGE bytea;

The functions find their OpClass through the operator family they belong to (named like the operator class, unless it was created with FAMILY): a support function must belong to one family only.

Indexed values, keys and queries are bytes, which are only valid during the call (copy them to keep them): variable-length values (types stored like bytea, e.g. declared with //gopgext:type over pg.Varlena) as they are, fixed-size ones copied (a //gopgext:type over [N]byte: N bytes; a by-value type: its bytes, little-endian, e.g. 4 for an int4 query). A query has the type of the operator’s right-hand argument. The functions return new keys, of the key type: STORAGE (usually bytea), or the indexed type without one (no Compress). NULLs never reach the functions: GiST handles them. gopgext_gist_decompress, which does nothing, is there for install scripts written for a C operator class (see //gopgext:alias).

An operator class with parameters (OpClass.Options, e.g. a signature length) adds the options support function, and one that declares a decompress function (support function 4) can use the identity:

CREATE FUNCTION shape_gist_options(internal) RETURNS void
	AS 'MODULE_PATHNAME', 'gopgext_gist_options' LANGUAGE C;
CREATE FUNCTION shape_gist_decompress(internal) RETURNS internal
	AS 'MODULE_PATHNAME', 'gopgext_gist_decompress' LANGUAGE C STRICT;
-- FUNCTION 4 shape_gist_decompress (internal), FUNCTION 10 shape_gist_options (internal)

Strategy numbers are the operator numbers of the operator class (3 for && above). Results are exact unless the function asks for a recheck: PostgreSQL then evaluates the operator on the row (so a lossy key, e.g. a bounding box of a polygon, can still answer exact operators).

Index#

Functions#

func Option#

func Option(name string) int

Option returns the value of the operator class parameter name for the index the current support function works on (its Default if the index has none, e.g. it was created before the parameter existed). It must be called from the OpClass’s functions.

func Register#

func Register(family string, oc OpClass)

Register registers the operator class whose support functions belong to the operator family family (the name of the operator class, unless it was created with FAMILY).

Types#

type IntOption#

type IntOption struct {
	Name, Desc        string
	Default, Min, Max int
}

IntOption is an integer parameter of an operator class.

type OpClass#

type OpClass struct {
	// Compress returns the key stored for an indexed value (a leaf key).
	// nil: the value itself is the key (STORAGE must then be its type).
	Compress func(value []byte) ([]byte, error)

	// Consistent reports whether key may match query with the operator of
	// the given strategy number: on a leaf, key is the key of one row; on
	// an inner page, it covers all the keys below it, and match means some
	// of them may match. recheck (leaves only) asks PostgreSQL to evaluate
	// the operator on the row to confirm a match.
	Consistent func(key, query []byte, strategy int, leaf bool) (match, recheck bool)

	// Union returns a key that covers all the keys.
	Union func(keys [][]byte) []byte

	// Penalty returns how much worse key gets as a cover for added (e.g. the
	// growth of a bounding box): new rows go where the penalty is lowest.
	// It must be 0 or more.
	Penalty func(key, added []byte) float64

	// PickSplit splits the keys of a full page in two non-empty groups:
	// the indexes of the keys going left and right (each index once).
	PickSplit func(keys [][]byte) (left, right []int)

	// Same reports whether two keys are equal (nil: bytes.Equal).
	Same func(a, b []byte) bool

	// Distance returns the distance from key to query for the ordering
	// operator of the given strategy (ORDER BY col <-> query uses the
	// index): on an inner page, a lower bound of the distance of the rows
	// below. recheck (leaves only) means the distance is a lower bound:
	// PostgreSQL then computes the exact one with the operator. nil: the
	// operator class has no ordering operators.
	Distance func(key, query []byte, strategy int, leaf bool) (distance float64, recheck bool)

	// Options are the operator class's integer parameters, set per index:
	// CREATE INDEX ... USING gist (col opclass(name = value)). The
	// functions read them with Option. They need the options support
	// function (10) in the operator family (see the package doc).
	Options []IntOption
}

OpClass is a GiST operator class. Consistent, Union, Penalty and PickSplit are required.