begriffs open source - ai-pg/blob - full-docs/txt/tablesample-support-functions.txt

   1
   2 59.1. Sampling Method Support Functions #
   3
   4    The TSM handler function returns a palloc'd TsmRoutine struct
   5    containing pointers to the support functions described below. Most of
   6    the functions are required, but some are optional, and those pointers
   7    can be NULL.
   8
   9 void
  10 SampleScanGetSampleSize (PlannerInfo *root,
  11                          RelOptInfo *baserel,
  12                          List *paramexprs,
  13                          BlockNumber *pages,
  14                          double *tuples);
  15
  16    This function is called during planning. It must estimate the number of
  17    relation pages that will be read during a sample scan, and the number
  18    of tuples that will be selected by the scan. (For example, these might
  19    be determined by estimating the sampling fraction, and then multiplying
  20    the baserel->pages and baserel->tuples numbers by that, being sure to
  21    round the results to integral values.) The paramexprs list holds the
  22    expression(s) that are parameters to the TABLESAMPLE clause. It is
  23    recommended to use estimate_expression_value() to try to reduce these
  24    expressions to constants, if their values are needed for estimation
  25    purposes; but the function must provide size estimates even if they
  26    cannot be reduced, and it should not fail even if the values appear
  27    invalid (remember that they're only estimates of what the run-time
  28    values will be). The pages and tuples parameters are outputs.
  29
  30 void
  31 InitSampleScan (SampleScanState *node,
  32                 int eflags);
  33
  34    Initialize for execution of a SampleScan plan node. This is called
  35    during executor startup. It should perform any initialization needed
  36    before processing can start. The SampleScanState node has already been
  37    created, but its tsm_state field is NULL. The InitSampleScan function
  38    can palloc whatever internal state data is needed by the sampling
  39    method, and store a pointer to it in node->tsm_state. Information about
  40    the table to scan is accessible through other fields of the
  41    SampleScanState node (but note that the node->ss.ss_currentScanDesc
  42    scan descriptor is not set up yet). eflags contains flag bits
  43    describing the executor's operating mode for this plan node.
  44
  45    When (eflags & EXEC_FLAG_EXPLAIN_ONLY) is true, the scan will not
  46    actually be performed, so this function should only do the minimum
  47    required to make the node state valid for EXPLAIN and EndSampleScan.
  48
  49    This function can be omitted (set the pointer to NULL), in which case
  50    BeginSampleScan must perform all initialization needed by the sampling
  51    method.
  52
  53 void
  54 BeginSampleScan (SampleScanState *node,
  55                  Datum *params,
  56                  int nparams,
  57                  uint32 seed);
  58
  59    Begin execution of a sampling scan. This is called just before the
  60    first attempt to fetch a tuple, and may be called again if the scan
  61    needs to be restarted. Information about the table to scan is
  62    accessible through fields of the SampleScanState node (but note that
  63    the node->ss.ss_currentScanDesc scan descriptor is not set up yet). The
  64    params array, of length nparams, contains the values of the parameters
  65    supplied in the TABLESAMPLE clause. These will have the number and
  66    types specified in the sampling method's parameterTypes list, and have
  67    been checked to not be null. seed contains a seed to use for any random
  68    numbers generated within the sampling method; it is either a hash
  69    derived from the REPEATABLE value if one was given, or the result of
  70    random() if not.
  71
  72    This function may adjust the fields node->use_bulkread and
  73    node->use_pagemode. If node->use_bulkread is true, which it is by
  74    default, the scan will use a buffer access strategy that encourages
  75    recycling buffers after use. It might be reasonable to set this to
  76    false if the scan will visit only a small fraction of the table's
  77    pages. If node->use_pagemode is true, which it is by default, the scan
  78    will perform visibility checking in a single pass for all tuples on
  79    each visited page. It might be reasonable to set this to false if the
  80    scan will select only a small fraction of the tuples on each visited
  81    page. That will result in fewer tuple visibility checks being
  82    performed, though each one will be more expensive because it will
  83    require more locking.
  84
  85    If the sampling method is marked repeatable_across_scans, it must be
  86    able to select the same set of tuples during a rescan as it did
  87    originally, that is a fresh call of BeginSampleScan must lead to
  88    selecting the same tuples as before (if the TABLESAMPLE parameters and
  89    seed don't change).
  90
  91 BlockNumber
  92 NextSampleBlock (SampleScanState *node, BlockNumber nblocks);
  93
  94    Returns the block number of the next page to be scanned, or
  95    InvalidBlockNumber if no pages remain to be scanned.
  96
  97    This function can be omitted (set the pointer to NULL), in which case
  98    the core code will perform a sequential scan of the entire relation.
  99    Such a scan can use synchronized scanning, so that the sampling method
 100    cannot assume that the relation pages are visited in the same order on
 101    each scan.
 102
 103 OffsetNumber
 104 NextSampleTuple (SampleScanState *node,
 105                  BlockNumber blockno,
 106                  OffsetNumber maxoffset);
 107
 108    Returns the offset number of the next tuple to be sampled on the
 109    specified page, or InvalidOffsetNumber if no tuples remain to be
 110    sampled. maxoffset is the largest offset number in use on the page.
 111
 112 Note
 113
 114    NextSampleTuple is not explicitly told which of the offset numbers in
 115    the range 1 .. maxoffset actually contain valid tuples. This is not
 116    normally a problem since the core code ignores requests to sample
 117    missing or invisible tuples; that should not result in any bias in the
 118    sample. However, if necessary, the function can use node->donetuples to
 119    examine how many of the tuples it returned were valid and visible.
 120
 121 Note
 122
 123    NextSampleTuple must not assume that blockno is the same page number
 124    returned by the most recent NextSampleBlock call. It was returned by
 125    some previous NextSampleBlock call, but the core code is allowed to
 126    call NextSampleBlock in advance of actually scanning pages, so as to
 127    support prefetching. It is OK to assume that once sampling of a given
 128    page begins, successive NextSampleTuple calls all refer to the same
 129    page until InvalidOffsetNumber is returned.
 130
 131 void
 132 EndSampleScan (SampleScanState *node);
 133
 134    End the scan and release resources. It is normally not important to
 135    release palloc'd memory, but any externally-visible resources should be
 136    cleaned up. This function can be omitted (set the pointer to NULL) in
 137    the common case where no such resources exist.