SQLオブジェクト

本章ではPG-Stromが独自に提供するSQLオブジェクトについて説明します。

システム情報

pgstrom.device_info システムビュー: PG-Strom用にインストールされたGPUデバイスのプロパティを表示します。; このビューのスキーマ定義は以下の通りです。

name	type	description
gpu_id	`int`	GPUデバイス番号
att_name	`text`	デバイス属性名
att_value	`text`	デバイス属性値
att_desc	`text`	デバイス属性の説明

GPUデバイスのプロパティは非常に数が多く、またCUDAドライバのバージョンによっても対応しているプロパティの数はまちまちです。そのため、pgstrom.device_infoシステムビューでは、GPUデバイス番号(gpu_id)と、デバイス属性名(att_name)によって対象となるプロパティを特定します。

以下はpgstrom.device_infoシステムビューの出力例です。

postgres=# select * from pgstrom.gpu_device_info limit 10;
 gpu_id |       att_name        |                att_value                 |              att_desc
--------+-----------------------+------------------------------------------+-------------------------------------
      0 | DEV_NAME              | NVIDIA A100-PCIE-40GB                    | GPU Device Name
      0 | DEV_ID                | 0                                        | GPU Device ID
      0 | DEV_UUID              | GPU-13943bfd-5b30-38f5-0473-78979c134606 | GPU Device UUID
      0 | DEV_TOTAL_MEMSZ       | 39.39GB                                  | GPU Total RAM Size
      0 | DEV_BAR1_MEMSZ        | 64.00GB                                  | GPU PCI Bar1 Size
      0 | NUMA_NODE_ID          | -1                                       | GPU NUMA Node Id
      0 | MAX_THREADS_PER_BLOCK | 1024                                     | Maximum number of threads per block
      0 | MAX_BLOCK_DIM_X       | 1024                                     | Maximum block dimension X
      0 | MAX_BLOCK_DIM_Y       | 1024                                     | Maximum block dimension Y
      0 | MAX_BLOCK_DIM_Z       | 64                                       | Maximum block dimension Z
(10 rows)

Arrow_Fdw

fdw_handler pgstrom.arrow_fdw_handler(): Arrow_FdwのFDWハンドラ関数です。通常、ユーザがこの関数を使用する必要はありません。
void pgstrom.arrow_fdw_validator(text[], oid): Arrow_FdwのFDWオプション検証用関数です。通常、ユーザがこの関数を使用する必要はありません。
event_trigger pgstrom.arrow_fdw_precheck_schema(): Arrowファイルのスキーマ定義をチェックするためのイベントトリガ関数です。通常、ユーザがこの関数を使用する必要はありません。
void pgstrom.arrow_fdw_import_file(text, text, text = null): Apache Arrow形式ファイルをインポートし、新たに外部テーブル(foreign table)を定義します。第一引数は外部テーブルの名前、第二引数はApache Arrow形式ファイルのパス、省略可能な第三引数はスキーマ名です。; この関数はIMPORT FOREIGN SCHEMA構文に似ていますが、PostgreSQLにおけるテーブルの列数制限（MaxTupleAttributeNumber = 1664）を越える列が定義されたApache Arrow形式ファイルをインポートできます。つまり、これに該当しない大半のユースケースではIMPORT FOREIGN SCHEMA構文を利用すべきです。; 以下の例は、pgstrom.arrow_fdw_import_fileを用いて2000個のInt16列を持つApache Arrowファイルをインポートしたものです。\d mytestの実行結果より、新たに作成された外部テーブルmytestが2000個のフィールドを持っている事が分かります。; PostgreSQL内部表現の都合上、全ての列を一度に読み出す事はできませんが、最後の例のように一部の列だけを参照するワークロードであれば実行可能です。

=# select pgstrom.arrow_fdw_import_file('mytest', '/tmp/wide2000.arrow');
 arrow_fdw_import_file
-----------------------

(1 row)

=# \d
            List of relations
 Schema |  Name  |     Type      | Owner
--------+--------+---------------+--------
 public | mytest | foreign table | kaigai
(1 row)


=# \d mytest
                    Foreign table "public.mytest"
  Column   |   Type   | Collation | Nullable | Default | FDW options
-----------+----------+-----------+----------+---------+-------------
 object_id | integer  |           |          |         |
 c000      | smallint |           |          |         |
 c001      | smallint |           |          |         |
 c002      | smallint |           |          |         |
 c003      | smallint |           |          |         |
   :             :          :          :          :            :
 c1997     | smallint |           |          |         |
 c1998     | smallint |           |          |         |
 c1999     | smallint |           |          |         |
Server: arrow_fdw
FDW options: (file '/tmp/wide2000.arrow')

=# select * from mytest ;
ERROR:  target lists can have at most 1664 entries

=# select c0010,c1234,c1999 from mytest limit 3;
 c0010 | c1234 | c1999
-------+-------+-------
   232 |   232 |   232
   537 |   537 |   537
   219 |   219 |   219
(3 rows)

GPUキャッシュ

pgstrom.gpucache_info システムビュー: GPUキャッシュの現在の状態を表示します。
このビューのスキーマ定義は以下の通りです。

name	type	description
`database_oid`	`oid`	GPUキャッシュを設定したテーブルの属するデータベースのOIDです
`database_name`	`text`	GPUキャッシュを設定したテーブルの属するデータベースの名前です
`table_oid`	`oid`	GPUキャッシュを設定したテーブルのOIDです。必ずしも現在のデータベースとは限らない事に留意してください。
`table_name`	`text`	GPUキャッシュを設定したテーブルの名前です。必ずしも現在のデータベースとは限らない事に留意してください。
`signature`	`int8`	GPUキャッシュの一意性を示すハッシュ値です。例えば`ALTER TABLE`の前後などでこの値が変わる場合があります。
`phase`	`text`	GPUキャッシュ構築の段階を示します。`not_built`, `is_empty`, `is_loading`, `is_ready`, `corrupted`のいずれかです。
`rowid_num_used`	`int8`	割当て済みの行IDの数です。
`rowid_num_free`	`int8`	未割当の行IDの数です。
`gpu_main_sz`	`int8`	GPUキャッシュ上の固定長データ用の領域のサイズです。
`gpu_main_nitems`	`int8`	GPUキャッシュ上のタプル数です。
`gpu_extra_sz`	`int8`	GPUキャッシュ上の可変長データ用の領域のサイズです。
`gpu_extra_usage`	`int8`	GPUキャッシュ上の可変長データ領域の使用済みサイズです。
`gpu_extra_dead`	`int8`	GPUキャッシュ上の可変長データ領域の未使用サイズです。
`redo_write_ts`	`timestamptz`	REDOログバッファを最後に更新した時刻です。
`redo_write_nitems`	`int8`	REDOログバッファに書き込まれたREDOログの総数です。
`redo_write_pos`	`int8`	REDOログバッファに書き込まれたREDOログの総バイト数です。
`redo_read_nitems`	`int8`	REDOログバッファから読み出し、GPUに適用されたREDOログの総数です。
`redo_read_pos`	`int8`	REDOログバッファから読み出し、GPUに適用されたREDOログの総バイト数です。
`redo_sync_pos`	`int8`	REDOログバッファ書き込まれたREDOログのうち、既にGPUキャッシュへの適用をバックグラウンドワーカにリクエストした位置です。REDOログバッファの残り容量が逼迫してきた際に、多数のセッションが同時に非同期のリクエストを発生させる事を避けるため、内部的に使用されます。
`config_options`	`text`	GPUキャッシュのオプション文字列です。

以下はpgstrom.gpucache_infoシステムビューの出力例です。

=# select * from pgstrom.gpucache_info ;
 database_oid | database_name | table_oid |    table_name    | signature  |  phase   | rowid_num_used | rowid_num_free | gpu_main_sz | gpu_main_nitems | gpu_extra_sz | gpu_extra_usage | gpu_extra_dead |         redo_write_ts         | redo_write_nitems | redo_write_pos | redo_read_nitems | redo_read_pos |
redo_sync_pos |                                                   config_options
--------------+---------------+-----------+------------------+------------+----------+----------------+----------------+-------------+-----------------+--------------+-----------------+----------------+-------------------------------+-------------------+----------------+------------------+---------------+---------------+---------------------------------------------------------------------------------------------------------------------
       193450 | hoge          |    603029 | cache_test_table | 4529357070 | is_ready |           4000 |           6000 |      439904 |            4000 |      3200024 |          473848 |              0 | 2023-12-18 01:25:42.850193+09 |              4000 |         603368 |             4000 |        603368 |       603368 | gpu_device_id=0,max_num_rows=10000,redo_buffer_size=157286400,gpu_sync_interval=4000000,gpu_sync_threshold=10485760
(1 row)

trigger pgstrom.gpucache_sync_trigger(): テーブル更新の際にGPUキャッシュを同期するためのトリガ関数です。詳しくはGPUキャッシュの章を参照してください。
bigint pgstrom.gpucache_apply_redo(regclass): 引数で指定されたテーブルにGPUキャッシュが設定されている場合、未適用のREDOログを強制的にGPUキャッシュに適用します。
bigint pgstrom.gpucache_compaction(regclass): 引数で指定されたテーブルにGPUキャッシュが設定されている場合、可変長データバッファを強制的にコンパクト化します。
bigint pgstrom.gpucache_recovery(regclass): 破損（corrupted）状態となったGPUキャッシュを復元しようと試みます。

テストデータ生成

void pgstrom.random_setseed(int): 乱数の系列を初期化します。
bigint pgstrom.random_int(float=0.0, bigint=0, bigint=INT_MAX): bigint型のランダムデータを指定の範囲内で生成します。
float pgstrom.random_float(float=0.0, float=0.0, float=1.0): float型のランダムデータを指定の範囲内で生成します。
date pgstrom.random_date(float=0.0, date='2015-01-01', date='2025-12-31'): date型のランダムデータを指定の範囲内で生成します。
time pgstrom.random_time(float=0.0, time='00:00:00', time='23:59:59'): time型のランダムデータを指定の範囲内で生成します。
timetz pgstrom.random_timetz(float=0.0, time='00:00:00', time='23:59:59'): timetz型のランダムデータを指定の範囲内で生成します。
timestamp pgstrom.random_timestamp(float=0.0, timestamp='2015-01-01', timestamp='2025-01-01'): timestamp型のランダムデータを指定の範囲内で生成します。
macaddr pgstrom.random_macaddr(float=0.0, macaddr='ab:cd:00:00:00', macaddr='ab:cd:ff:ff:ff:ff'): macaddr型のランダムデータを指定の範囲内で生成します。
inet pgstrom.random_inet(float=0.0, inet='192.168.0.1/16'): inet型のランダムデータを指定の範囲内で生成します。
text pgstrom.random_text(float=0.0, text='test_**'): text型のランダムデータを生成します。第二引数の'*'文字をランダムに置き換えます。
text pgstrom.random_text_len(float=0.0, int=10): text型のランダムデータを指定文字列長の範囲内で生成します。
int4range pgstrom.random_int4range(float=0.0, bigint=0, bigint=INT_MAX): int4range型のランダムデータを指定の範囲内で生成します。}
int8range pgstrom.random_int8range(float=0.0, bigint=0, bigint=LONG_MAX): int8range型のランダムデータを指定の範囲内で生成します。
tsrange pgstrom.random_tsrange(float=0.0, timestamp='2015-01-01', timestamp='2025-01-01'): tsrange型のランダムデータを指定の範囲内で生成します。
tstzrange pgstrom.random_tstzrange(float=0.0, timestamptz='2015-01-01', timestamptz='2025-01-01'): tstzrange型のランダムデータを指定の範囲内で生成します。
daterange pgstrom.random_daterange(float=0.0, date='2015-01-01', date='2025-12-31'): daterange型のランダムデータを指定の範囲内で生成します。

その他の関数

text pgstrom.githash(): 現在ロードされているPG-Stromモジュールの元となったソースコードリビジョンのハッシュ値を表示します。この値は、障害時にソフトウェアのリビジョンを特定するのに有用です。

postgres=# select pgstrom.githash();
                 githash
------------------------------------------
 103984be24cafd1e7ce6330a050960d97675c196

text pgstrom.license_query(): ロードされていれば、現在ロードされている商用サブスクリプションを表示します。

=# select pgstrom.license_query();
                                                                               license_query
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 { "version" : 2, "serial_nr" : "HDB-TRIAL", "issued_at" : "2020-11-24", "expired_at" : "2025-12-31", "gpus" : [ { "uuid" : "GPU-8ba149db-53d8-c5f3-0f55-97ce8cfadb28" } ]}
(1 row)