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
func ClampRows(rows float64) float64func Register(name string, m Method)- type Method
- type Random
- type Relation
- type Scan
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.