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ファイルのスキーマ定義をチェックするためのイベントトリガ関数です。通常、ユーザがこの関数を使用する必要はありません。
text pgstrom.arrow_fdw_check_pattern(text, text): 第一引数で与えたファイル名が、第二引数で与えたパターンにマッチするかどうかを検査します。Arrow_Fdwのpatternオプションを用いる場合に、ワイルドカードがどのように働くのかを検査するのに便利です。

=# select pgstrom.arrow_fdw_check_pattern('data_202408_tokyo.data', 'data__${region}.data');
          arrow_fdw_check_pattern
-------------------------------------------
 true {@ymd]=[202408], $[region]=[tokyo]}
(1 row)

上記の例では、ファイル名data_202408_tokyo.dataに対して、パターン'data_@ymd_${region}.data'のうち、ワイルドカードに相当する部分が`202408`にマッチし、`${region}`に相当する部分が`tokyo`にマッチしています。 } _${region}.data'` that corresponds to the wildcard matches 202408, and the part that corresponds to ${region} matches tokyo. }

record pgstrom.arrow_fdw_metadata_info(regclass): Arrowファイルに埋め込まれているメタデータ（CustomMetadata）を表示します。

postgres=# select relid, filename, field, key, substring(value, 0, 64) from pgstrom.arrow_fdw_metadata_info('f_lineorder');
    relid    |              filename               |    field     |     key     |                            substring
-------------+-------------------------------------+--------------+-------------+-----------------------------------------------------------------
 f_lineorder | /opt/arrow/f_lineorder_sorted.arrow |              | sql_command | select * from v_lineorder order by lo_orderdate
 f_lineorder | /opt/arrow/f_lineorder_sorted.arrow | lo_orderdate | min_values  | 19920101,19920102,19920103,19920104,19920105,19920107,19920108,
 f_lineorder | /opt/arrow/f_lineorder_sorted.arrow | lo_orderdate | max_values  | 19920102,19920103,19920104,19920105,19920107,19920108,19920109,
(3 rows)

上記の例では、Arrow_Fdw管理下の外部テーブルであるf_lineorderに埋め込まれているメタデータ（CustomMetadata）を、それぞれKEY=VALUE形式で出力しています。スキーマに埋め込まれたメタデータはfield列がNULLとなっています。そうでなければ列名が表示され、この場合、sql_commandメタデータがスキーマに埋め込まれ、また、min_valuesおよびmax_valuesがlo_orderdate列に埋め込まれている事がわかります。

json pgstrom.arrow_fdw_metadata_stats(): Arrow_Fdwのメタデータキャッシュの統計情報を表示します

Arrow_Fdwは何らかの形で一度参照したArrowファイルのメタデータ（スキーマ定義やデータ配置など）を共有メモリ上に記憶しており、次回以降にArrow_Fdw外部テーブルを参照する際の応答性を改善する事ができます。

この関数は、共有メモリ上のメタデータキャッシュに関する統計情報を表示する事ができます。メタデータキャッシュが不足すると、Arrow_Fdw外部テーブルの参照応答性が低下する事がありますので、その場合はarrow_fdw.metadata_cache_sizeを拡大してメタデータキャッシュを拡大する事が必要になります。

s=# select pgstrom.arrow_fdw_metadata_stats();

       arrow_fdw_metadata_stats

-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 { "total_cache_sz" : 536870912, "total_cache_allocated" : 9568256, "total_cache_usage" : 9354072, "num_file_entries" : 2, "cache_usage_efficiency" : 0.977615, "cache_num_blocks" : 4096, "cache_active_blocks" : 73, "cache_free_blocks" : 4023, "cache_used_ratio" : 0.017822 "last_allocate_timestamp" : "2025-03-29 13:24:44.447" }
(1 row)

上記の例のように統計情報はJSON形式で表示され、各フィールドの意味は以下の通りです。

total_cache_sz
- メタデータキャッシュの総容量（バイト単位）
total_cache_allocated
- 割り当て済みのメタデータキャッシュサイズ（バイト単位）
total_cache_usage
- 使用済みのメタデータキャッシュサイズ（バイト単位）
num_file_entries
- キャッシュが保持されているArrowファイルの個数
cache_usage_efficiency
- 割り当て済みメタデータキャッシュに占める使用済みメタデータキャッシュの比率
cache_num_blocks
- メタデータキャッシュのブロック数（128kB単位）
cache_active_blocks
- 割り当て済みのメタデータキャッシュブロック数
cache_free_blocks
- 空いているメタデータキャッシュブロック数
cache_used_ratio
- 割り当て済みのメタデータキャッシュブロックの比率
last_allocate_timestamp
- 最後にメタデータキャッシュを割り当てた時のタイムスタンプ
last_reclaim_timestamp
- 最後にメタデータキャッシュが回収された時のタイムスタンプ

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)