gopgext/tablesample
TABLESAMPLE methods.
API reference: gopgext/tablesample.
TABLESAMPLE methods in Go: which blocks of a table a sample scan reads,
and which tuple offsets of each block it returns. The extension registers
a tablesample.Method under the method’s name, and declares its handler
function (with this package’s C symbol) in sql/:
func main() {
tablesample.Register("system_rows", tablesample.Method{
Params: []pg.Oid{tablesample.Int8}, // TABLESAMPLE system_rows (100)
RepeatableAcrossScans: true,
SampleSize: func(rel tablesample.Relation, params []any) (pages, tuples float64) { ... }, // planner
Begin: func(s *tablesample.Scan, params []any, seed uint32) error { ... }, // (re)scan starts
NextBlock: func(s *tablesample.Scan, nblocks uint32) (uint32, bool) { ... }, // optional
NextTuple: func(s *tablesample.Scan, block uint32, maxOffset uint16) (uint16, bool) { ... },
})
}
CREATE FUNCTION system_rows(internal) RETURNS tsm_handler
AS 'MODULE_PATHNAME', 'gopgext_tablesample_handler' LANGUAGE C STRICT;
A Scan keeps the method’s State across a scan’s rescans and counts the
tuples returned so far (DoneTuples, visible ones); PostgreSQL reads the
pages and checks visibility. SampleSize gets the table’s size estimates,
its tablespace’s random_page_cost and the parameters known at planning
time; tablesample.ClampRows is the planner’s clamp_row_est, and
tablesample.NewRandom(seed) PostgreSQL’s sampling random generator (the
same samples as the built-in methods for a seed). A scan’s Go state is
dropped when the query ends, also after errors. contrib/tsm_system_rows
and contrib/tsm_system_time are built on it.