第56章 テーブルサンプリングメソッドの書き方

目次

56.1. サンプリングメソッドサポート関数
<title>Writing A Table Sampling Method</title>

<productname>PostgreSQL</>'s implementation of the <literal>TABLESAMPLE</> clause supports custom table sampling methods, in addition to the <literal>BERNOULLI</> and <literal>SYSTEM</> methods that are required by the SQL standard. The sampling method determines which rows of the table will be selected when the <literal>TABLESAMPLE</> clause is used. PostgreSQLによるTABLESAMPLE句の実装は、SQL標準が求めるBERNOULLISYSTEMのメソッドに加え、ユーザ定義のテーブルサンプリングメソッドをサポートしています。 サンプリングメソッドは、TABLESAMPLE句が使用された際にどの行が選択されるかを決定します。

At the SQL level, a table sampling method is represented by a single SQL function, typically implemented in C, having the signature SQLレベルでは、テーブルサンプリングメソッドは、以下の呼び出し形式を持ち、典型的にはCで実装された単一のSQLの関数で表現されます。

method_name(internal) RETURNS tsm_handler

The name of the function is the same method name appearing in the <literal>TABLESAMPLE</> clause. The <type>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 <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 <xref linkend="tablesample-support-functions">. 関数の名前はTABLESAMPLE句に現れるメソッド名と同じです。 internal引数は、ダミー(常に0の値を持つ)で、単にこの関数がSQLコマンドから直接呼ばれるのを防ぐために用意されています。 関数の戻り値は、pallocされたTsmRoutine型の構造体でなければなりません。 その構造体の中には、サンプリングメソッド用のサポート関数へのポインタが含まれています。 サポート関数は普通のC関数で、SQLレベルからは見ることも呼び出すこともできません。 サポート関数は56.1. サンプリングメソッドサポート関数で説明されています。

In addition to function pointers, the <type>TsmRoutine</> struct must provide these additional fields: 関数へのポインタに加え、TsmRoutine構造体は以下の追加のフィールドを提供しなければなりません。

List *parameterTypes

This is an OID list containing the data type OIDs of the parameter(s) that will be accepted by the <literal>TABLESAMPLE</> clause when this sampling method is used. For example, for the built-in methods, this list contains a single item with value <literal>FLOAT4OID</>, which represents the sampling percentage. Custom sampling methods can have more or different parameters. このサンプリングメソッドが使用される際に、TABLESAMPLE句が受け付ける引数のデータ型のOIDが格納された、OIDのリストです。 たとえば、組み込みのメソッドに対しては、このリストは、サンプリングのパーセンテージを表すFLOAT4OIDという値を持つ単一の要素が含まれています。 カスタムサンプリングメソッドは、複数の異なるパラメータを持つことができます。

bool repeatable_across_queries

If <literal>true</>, the sampling method can deliver identical samples across successive queries, if the same parameters and <literal>REPEATABLE</> seed value are supplied each time and the table contents have not changed. When this is <literal>false</>, the <literal>REPEATABLE</> clause is not accepted for use with the sampling method. trueの場合、もし毎回同じ引数とREPEATABLEシード値が提供され、テーブル内容に変更がないならば、サンプリングメソッドは実行されたどの問い合わせに対しても、同一のサンプルを出力することができます。 falsetrueの場合は、サンプリングメソッドを使用する際にREPEATABLE句を受け付けません。

bool repeatable_across_scans

If <literal>true</>, the sampling method can deliver identical samples across successive scans in the same query (assuming unchanging parameters, seed value, and snapshot). When this is <literal>false</>, the planner will not select plans that would require scanning the sampled table more than once, since that might result in inconsistent query output. trueの場合、サンプリングメソッドは同じ問い合わせ内で実行されたどのスキャンに対しても、同一のサンプルを出力することができます(パラメータ、シード値、スナップショットに変更がない、という前提で)。 falseの場合、プランナは、サンプル対象のテーブルを2度以上スキャンする必要のあるようなプランは選択しません。 問い合わせの結果に不整合が発生する可能性があるからです。

The <type>TsmRoutine</> struct type is declared in <filename>src/include/access/tsmapi.h</>, which see for additional details. TsmRoutine構造体はsrc/include/access/tsmapi.hで宣言されています。 詳細はそちらをご覧ください。

The table sampling methods included in the standard distribution are good references when trying to write your own. Look into the <filename>src/backend/access/tablesample</> subdirectory of the source tree for the built-in sampling methods, and into the <filename>contrib</> subdirectory for add-on methods. 標準配布物に含まれるテーブルサンプリングメソッドは、自分でサンプリングメソッドを書く際に良いお手本になります。 組み込みのサンプリングメソッドに関しては、ソースツリー中のsrc/backend/access/tablesampleサブディレクトリを見てください。 追加のメソッドに関してはcontribサブディレクトリを見てください。