TSM 处理器函数返回一个 palloc'd TsmRoutine
结构,其中包含指向下面描述的支持函数的指针。大多数函数都是必需的,但有些是可选的,这些指针可以为 NULL。
void SampleScanGetSampleSize (PlannerInfo *root, RelOptInfo *baserel, List *paramexprs, BlockNumber *pages, double *tuples);
此函数在规划期间调用。它必须估算在示例扫描期间将读取的关系页数,以及扫描将选择的元组数。(例如,这些可能通过估算抽样分数来确定,然后将 baserel->pages
和 baserel->tuples
数字乘以该分数,确保将结果四舍五入为整数。)paramexprs
列表保存作为 TABLESAMPLE
子句参数的表达式。建议使用 estimate_expression_value()
尝试将这些表达式简化为常量,如果其值对于估算目的而言是必需的;但该函数必须提供大小估算,即使它们无法简化,并且即使这些值似乎无效,它也不应失败(记住,它们只是对运行时值将是什么的估算)。pages
和 tuples
参数是输出。
void InitSampleScan (SampleScanState *node, int eflags);
初始化以执行 SampleScan 计划节点。这在执行程序启动期间调用。它应执行在处理开始前所需的任何初始化。SampleScanState
节点已创建,但其 tsm_state
字段为 NULL。InitSampleScan
函数可以 palloc 抽样方法所需的任何内部状态数据,并将指向它的指针存储在 node->tsm_state
中。有关要扫描的表的信息可以通过 SampleScanState
节点的其他字段访问(但请注意,node->ss.ss_currentScanDesc
扫描描述符尚未设置)。eflags
包含描述此计划节点的执行程序操作模式的标志位。
当 (eflags & EXEC_FLAG_EXPLAIN_ONLY)
为 true 时,扫描将不会实际执行,因此此函数应仅执行使节点状态对 EXPLAIN
和 EndSampleScan
有效所需的最小操作。
可以省略此函数(将指针设置为 NULL),在这种情况下,BeginSampleScan
必须执行抽样方法所需的所有初始化。
void BeginSampleScan (SampleScanState *node, Datum *params, int nparams, uint32 seed);
开始执行抽样扫描。这在首次尝试获取元组之前调用,并且如果需要重新启动扫描,则可以再次调用。有关要扫描的表的信息可以通过 SampleScanState
节点的字段访问(但请注意,node->ss.ss_currentScanDesc
扫描描述符尚未设置)。长度为 nparams
的 params
数组包含在 TABLESAMPLE
子句中提供的参数的值。这些将具有抽样方法的 parameterTypes
列表中指定的数量和类型,并且已检查为非空。seed
包含用于在抽样方法中生成的任何随机数的种子;如果给定 REPEATABLE
值,则它要么是源自该值的哈希,要么是 random()
的结果(如果没有)。
此函数可以调整字段 node->use_bulkread
和 node->use_pagemode
。如果 node->use_bulkread
为 true
(默认情况下为 true),则扫描将使用缓冲区访问策略,该策略鼓励在使用后回收缓冲区。如果扫描只访问表页面的很小一部分,则可以合理地将此设置为 false
。如果 node->use_pagemode
为 true
(默认情况下为 true),则扫描将在每个已访问页面上的所有元组中执行一次通过可见性检查。如果扫描只选择每个已访问页面上的一小部分元组,则可以合理地将此设置为 false
。这将导致执行更少的元组可见性检查,尽管每个检查的开销更大,因为它需要更多的锁定。
如果采样方法标记为 repeatable_across_scans
,则它必须能够在重新扫描期间选择与最初相同的元组集,即 BeginSampleScan
的新调用必须导致选择与之前相同的元组(如果 TABLESAMPLE
参数和种子没有更改)。
BlockNumber NextSampleBlock (SampleScanState *node, BlockNumber nblocks);
返回要扫描的下一页的块号,如果没有剩余要扫描的页面,则返回 InvalidBlockNumber
。
可以省略此函数(将指针设置为 NULL),在这种情况下,核心代码将对整个关系执行顺序扫描。此类扫描可以使用同步扫描,因此采样方法不能假设关系页面在每次扫描中都以相同的顺序访问。
OffsetNumber NextSampleTuple (SampleScanState *node, BlockNumber blockno, OffsetNumber maxoffset);
返回指定页面上要采样的下一个元组的偏移号,如果没有剩余要采样的元组,则返回 InvalidOffsetNumber
。 maxoffset
是页面上使用的最大偏移号。
NextSampleTuple
没有明确告知 1 .. maxoffset
范围内的哪些偏移号实际上包含有效元组。这通常不是问题,因为核心代码会忽略对采样丢失或不可见元组的请求;这不会导致样本中的任何偏差。但是,如果需要,函数可以使用 node->donetuples
来检查返回的元组中有多少是有效且可见的。
NextSampleTuple
必须 不 假设 blockno
是最近的 NextSampleBlock
调用返回的相同页号。它是由某个之前的 NextSampleBlock
调用返回的,但内核代码允许在实际扫描页面之前提前调用 NextSampleBlock
,以支持预取。可以假设,一旦给定页面的抽样开始,连续的 NextSampleTuple
调用都引用同一页面,直到返回 InvalidOffsetNumber
。
void EndSampleScan (SampleScanState *node);
结束扫描并释放资源。通常不必释放 palloc 分配的内存,但应清理任何外部可见的资源。在不存在此类资源的常见情况下,可以省略此函数(将指针设置为 NULL)。