Глава 52. Написание метода извлечения выборки таблицы
Реализация предложения TABLESAMPLE в Postgres Pro поддерживает подключение собственных методов извлечения выборки таблицы, в дополнение к методам BERNOULLI и SYSTEM, которые требуются стандартом SQL. Метод выборки определяет, какие строки таблицы будут выбираться, когда используется предложение TABLESAMPLE.
На уровне SQL метод извлечения выборки таблицы представляется одной функцией SQL, обычно реализуемой на C, имеющей сигнатуру
method_name(internal) RETURNS tsm_handler
Имя функции будет совпадать с именем метода, указываемым в предложении TABLESAMPLE. Аргумент internal является фиктивным (в нём всегда передаётся ноль) и введён только для того, чтобы эту функцию нельзя было вызывать напрямую из команд SQL. Возвращать эта функция должна структуру типа TsmRoutine (выделенную вызовом palloc), содержащую указатели на опорные функции для метода извлечения выборки. Эти опорные функции представляют собой простые функции на C, которые не видны и не могут вызываться на уровне SQL. Эти опорные функции описаны в Разделе 52.1.
В дополнение к указателям на функции в структуре TsmRoutine должны задаваться следующие дополнительные поля:
List *parameterTypesЭто список OID, содержащий OID типов данных параметров, которые будут приниматься предложением
TABLESAMPLEпри использовании этого метода извлечения выборки. Например, для встроенных методов этот список содержит один элемент со значениемFLOAT4OID, представляющий процент выборки. Другие методы могут иметь дополнительные или иные параметры.bool repeatable_across_queriesЕсли это поле равно
true, данный метод извлечения выборки может выдавать одинаковые выборки при последовательных запросах с одними и теми же параметрами и значением затравкиREPEATABLEпри условии неизменности содержимого таблицы. Если равноfalse, предложениеREPEATABLEне будет приниматься с этим методом извлечения выборки.bool repeatable_across_scansЕсли это поле равно
true, метод извлечения выборки может выдавать одинаковые выборки при последовательном сканировании в рамках одного запроса (предполагается неизменность параметров, значения затравки и снимка данных). Если равноfalse, планировщик не будет выбирать планы, требующие неоднократного сканирования выборки, так как это может привести к несогласованному результату запроса.
Тип структуры TsmRoutine объявлен в src/include/access/tsmapi.h, где можно найти дополнительную информацию.
Методы извлечения выборки, включённые в стандартный дистрибутив, могут послужить хорошим примером, если вы хотите написать свой метод. Код встроенных методов вы можете найти в подкаталоге src/backend/access/tablesample дерева исходного кода, а код дополнительных методов — в подкаталоге contrib.
Chapter 52. Writing A Table Sampling Method
Postgres Pro's implementation of the TABLESAMPLE clause supports custom table sampling methods, in addition to the BERNOULLI and SYSTEM methods that are required by the SQL standard. The sampling method determines which rows of the table will be selected when the TABLESAMPLE clause is used.
At the SQL level, a table sampling method is represented by a single SQL function, typically implemented in C, having the signature
method_name(internal) RETURNS tsm_handler
The name of the function is the same method name appearing in the TABLESAMPLE clause. The internal argument is a dummy (always having value zero) that simply serves to prevent this function from being called directly from a SQL command. The result of the function must be a palloc'd struct of type TsmRoutine, which contains pointers to support functions for the sampling method. These support functions are plain C functions and are not visible or callable at the SQL level. The support functions are described in Section 52.1.
In addition to function pointers, the TsmRoutine struct must provide these additional fields:
List *parameterTypesThis is an OID list containing the data type OIDs of the parameter(s) that will be accepted by the
TABLESAMPLEclause when this sampling method is used. For example, for the built-in methods, this list contains a single item with valueFLOAT4OID, which represents the sampling percentage. Custom sampling methods can have more or different parameters.bool repeatable_across_queriesIf
true, the sampling method can deliver identical samples across successive queries, if the same parameters andREPEATABLEseed value are supplied each time and the table contents have not changed. When this isfalse, theREPEATABLEclause is not accepted for use with the sampling method.bool repeatable_across_scansIf
true, the sampling method can deliver identical samples across successive scans in the same query (assuming unchanging parameters, seed value, and snapshot). When this isfalse, the planner will not select plans that would require scanning the sampled table more than once, since that might result in inconsistent query output.
The TsmRoutine struct type is declared in src/include/access/tsmapi.h, which see for additional details.
The table sampling methods included in the standard distribution are good references when trying to write your own. Look into the src/backend/access/tablesample subdirectory of the source tree for the built-in sampling methods, and into the contrib subdirectory for add-on methods.
