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)