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

   1
   2 Chapter 59. Writing a Table Sampling Method
   3
   4    Table of Contents
   5
   6    59.1. Sampling Method Support Functions
   7
   8    PostgreSQL's implementation of the TABLESAMPLE clause supports custom
   9    table sampling methods, in addition to the BERNOULLI and SYSTEM methods
  10    that are required by the SQL standard. The sampling method determines
  11    which rows of the table will be selected when the TABLESAMPLE clause is
  12    used.
  13
  14    At the SQL level, a table sampling method is represented by a single
  15    SQL function, typically implemented in C, having the signature
  16 method_name(internal) RETURNS tsm_handler
  17
  18    The name of the function is the same method name appearing in the
  19    TABLESAMPLE clause. The internal argument is a dummy (always having
  20    value zero) that simply serves to prevent this function from being
  21    called directly from an SQL command. The result of the function must be
  22    a palloc'd struct of type TsmRoutine, which contains pointers to
  23    support functions for the sampling method. These support functions are
  24    plain C functions and are not visible or callable at the SQL level. The
  25    support functions are described in Section 59.1.
  26
  27    In addition to function pointers, the TsmRoutine struct must provide
  28    these additional fields:
  29
  30    List *parameterTypes
  31           This is an OID list containing the data type OIDs of the
  32           parameter(s) that will be accepted by the TABLESAMPLE clause
  33           when this sampling method is used. For example, for the built-in
  34           methods, this list contains a single item with value FLOAT4OID,
  35           which represents the sampling percentage. Custom sampling
  36           methods can have more or different parameters.
  37
  38    bool repeatable_across_queries
  39           If true, the sampling method can deliver identical samples
  40           across successive queries, if the same parameters and REPEATABLE
  41           seed value are supplied each time and the table contents have
  42           not changed. When this is false, the REPEATABLE clause is not
  43           accepted for use with the sampling method.
  44
  45    bool repeatable_across_scans
  46           If true, the sampling method can deliver identical samples
  47           across successive scans in the same query (assuming unchanging
  48           parameters, seed value, and snapshot). When this is false, the
  49           planner will not select plans that would require scanning the
  50           sampled table more than once, since that might result in
  51           inconsistent query output.
  52
  53    The TsmRoutine struct type is declared in src/include/access/tsmapi.h,
  54    which see for additional details.
  55
  56    The table sampling methods included in the standard distribution are
  57    good references when trying to write your own. Look into the
  58    src/backend/access/tablesample subdirectory of the source tree for the
  59    built-in sampling methods, and into the contrib subdirectory for add-on
  60    methods.