gopgext/tablesample

import "gopgext/tablesample"

Package tablesample writes TABLESAMPLE methods in Go: which blocks of a table a sample scan reads and which tuples of each block it returns (SELECT … FROM t TABLESAMPLE system_rows (100)).

The extension registers a Method under the name of the method (in main or a package initializer):

tablesample.Register("system_rows", tablesample.Method{
	Params:     []pg.Oid{tablesample.Int8}, // system_rows (n)
	SampleSize: estimate,  // planner: pages read, rows returned
	Begin:      begin,     // a scan (or rescan) starts: check the parameters
	NextBlock:  nextBlock, // optional: by default every block, in order
	NextTuple:  nextTuple, // the next tuple offset of a block
})

and its sql/ files declare the method’s handler function, named like it, with this package’s C symbol:

CREATE FUNCTION system_rows(internal) RETURNS tsm_handler
	AS 'MODULE_PATHNAME', 'gopgext_tablesample_handler' LANGUAGE C STRICT;

A Scan carries the method’s State across the calls of a scan and its rescans (e.g. the block order chosen at the first scan of a query), and how many tuples the scan has returned so far. PostgreSQL checks the visibility of the tuples: a method only picks positions (offsets past the last item of a block, or of unused items, are skipped).

Index#

Constants#

const (
	Bool   pg.Oid = 16
	Int8   pg.Oid = 20
	Int2   pg.Oid = 21
	Int4   pg.Oid = 23
	Text   pg.Oid = 25
	Float4 pg.Oid = 700
	Float8 pg.Oid = 701
)

Parameter types (Method.Params).

const CodeInvalidTablesampleArgument = "2202H"

CodeInvalidTablesampleArgument is the SQLSTATE of invalid parameters.

Functions#

func ClampRows#

func ClampRows(rows float64) float64

ClampRows is the planner’s clamp_row_est: at least 1, rounded.

func Register#

func Register(name string, m Method)

Register registers the method whose handler function is named name.

Types#

type Method#

type Method struct {
	// Params are the types of the method's parameters (at most 16).
	// Arguments are converted to them; they are never NULL.
	Params []pg.Oid

	// Can the method return the same sample for the same REPEATABLE seed
	// in different queries (REPEATABLE is rejected otherwise), and in
	// successive scans of the same query (else the planner materializes
	// the scan where it could be rescanned)?
	RepeatableAcrossQueries, RepeatableAcrossScans bool

	// SampleSize estimates the pages the scan reads and the rows it
	// returns, for the planner. params holds the parameters whose value is
	// known at planning time (constants), nil for others. Required.
	SampleSize func(rel Relation, params []any) (pages, tuples float64)

	// Begin starts a scan, or a rescan: params are the parameters' values
	// (int64 for integers, float64 for floats, bool, string, else a
	// pg.AnyElement) and seed the random seed (from REPEATABLE, or random).
	// An error (e.g. a pg.Error with CodeInvalidTablesampleArgument) aborts
	// the query. Required.
	Begin func(s *Scan, params []any, seed uint32) error

	// NextBlock returns the next block to read (of nblocks), or false when
	// the scan is done. Optional: without it, every block is read in order.
	NextBlock func(s *Scan, nblocks uint32) (block uint32, ok bool)

	// NextTuple returns the next tuple offset (1 to maxOffset) to return
	// from block, or false to go to the next block. Required.
	NextTuple func(s *Scan, block uint32, maxOffset uint16) (offset uint16, ok bool)
}

Method is a TABLESAMPLE method.

type Random#

type Random struct {
	// contains filtered or unexported fields
}

Random is PostgreSQL’s random generator for sampling methods (utils/sampling.h), so a method samples like the built-in ones.

func NewRandom#

func NewRandom(seed uint32) *Random

NewRandom returns a generator seeded with seed.

func (*Random) Fract#

func (r *Random) Fract() float64

Fract returns a random number in (0, 1) (sampler_random_fract).

type Relation#

type Relation struct {
	Pages, Tuples  float64 // size estimates (from VACUUM/ANALYZE)
	RandomPageCost float64 // random_page_cost of its tablespace
}

Relation is what the planner knows about the sampled table.

type Scan#

type Scan struct {
	// State is the method's: it lives as long as the scan, across its
	// rescans.
	State any
	// DoneTuples is the number of tuples the scan has returned so far
	// (visible ones).
	DoneTuples int64

}

Scan is a sample scan.