pgstattuple
モジュールはタプルレベルの統計情報を入手するための各種関数を提供します。
これらの関数は詳細なページレベルの情報を返しますので、デフォルトではアクセスが制限されています。
デフォルトではpg_stat_scan_tables
ロールだけがEXECUTE
権限を持っています。
スーパーユーザは、当然、この制限を無視します。
拡張がインストールされた後、ユーザはGRANT
コマンドを発行して他のユーザがそれらを実行できるよう関数に対する権限を変更できます。
しかしながら、その代わりにpg_stat_scan_tables
ロールにそのユーザを追加する方が好ましいでしょう。
pgstattuple(regclass) returns record
pgstattuple
はリレーションの物理的な長さ、「無効」なタプルの割合、およびその他の情報を返します。
これはバキュームが必要かどうかユーザが判断する時に有用かもしれません。
引数は対象とするリレーションの名前(スキーマ修飾可)もしくはOIDです。
以下に例を示します。
test=> SELECT * FROM pgstattuple('pg_catalog.pg_proc'); -[ RECORD 1 ]------+------- table_len | 458752 tuple_count | 1470 tuple_len | 438896 tuple_percent | 95.67 dead_tuple_count | 11 dead_tuple_len | 3157 dead_tuple_percent | 0.69 free_space | 8932 free_percent | 1.95
出力列を表 F.22で説明します。
表F.22 pgstattuple
の出力列
列 | 型 | 説明 |
---|---|---|
table_len | bigint | リレーションのバイト単位の物理長 |
tuple_count | bigint | 有効なタプル数 |
tuple_len | bigint | 有効なタプルの物理長(バイト単位) |
tuple_percent | float8 | 有効タプルの割合 |
dead_tuple_count | bigint | 無効なタプル数 |
dead_tuple_len | bigint | バイト単位の総無効タプル長 |
dead_tuple_percent | float8 | 無効タプルの割合 |
free_space | bigint | バイト単位の総空き領域 |
free_percent | float8 | 空き領域の割合 |
table_len
は、tuple_len
、dead_tuple_len
、free_space
の合計よりも常に大きいです。
違いの原因は、固定ページのオーバヘッド、ページ毎のタプルへのポインタのテーブル、タプルが正しく整列することを確実にするためのパディングです。
pgstattuple
はリレーション上で読み取りロックのみを獲得します。
ですので、結果はこの瞬間のスナップショットを考慮しません。つまり、同時実行の更新がその結果に影響を与えます。
pgstattuple
は、HeapTupleSatisfiesDirty
が偽を返すかどうかで、タプルが「無効」かどうか判定します。
pgstattuple(text) returns record
TEXTで対象リレーションを指定する点を除き、これはpgstattuple(regclass)
と同じです。
この関数は今までのところ後方互換のために残されており、近い将来のリリースでは廃止予定になるでしょう。
pgstatindex(regclass) returns record
pgstatindex
はB-treeインデックスに関する情報を示すレコードを返します。
以下は例です。
test=> SELECT * FROM pgstatindex('pg_cast_oid_index'); -[ RECORD 1 ]------+------ version | 2 tree_level | 0 index_size | 16384 root_block_no | 1 internal_pages | 0 leaf_pages | 1 empty_pages | 0 deleted_pages | 0 avg_leaf_density | 54.27 leaf_fragmentation | 0
出力列は以下の通りです。
列 | 型 | 説明 |
---|---|---|
version | integer | B-treeバージョン番号 |
tree_level | integer | ルートページのツリーレベル |
index_size | bigint | バイト単位のインデックスサイズ |
root_block_no | bigint | ルートページの場所(存在しない場合はゼロ) |
internal_pages | bigint | 「内部」(上位レベル)ページ数 |
leaf_pages | bigint | リーフページ数 |
empty_pages | bigint | 空ページ数 |
deleted_pages | bigint | 削除ページ数 |
avg_leaf_density | float8 | リーフページの平均密度 |
leaf_fragmentation | float8 | リーフページの断片化 |
報告されるindex_size
は、通常、internal_pages + leaf_pages + empty_pages + deleted_pages
が占めるより1多いページに相当するでしょう。
これは、index_sizeがインデックスメタページも含むためです。
pgstattuple
同様、結果はページ毎に累積されます。
この瞬間のインデックス全体のスナップショットが存在すると想定してはいけません。
pgstatindex(text) returns record
TEXTで対象インデックスを指定する点を除き、これはpgstatindex(regclass)
と同じです。
この関数は今までのところ後方互換のために残されており、近い将来のリリースでは廃止予定になるでしょう。
pgstatginindex(regclass) returns record
pgstatginindex
は、GINインデックスに関する情報を示すレコードを返します。
以下に例を示します。
test=> SELECT * FROM pgstatginindex('test_gin_index'); -[ RECORD 1 ]--+-- version | 1 pending_pages | 0 pending_tuples | 0
出力列は以下の通りです。
列 | 型 | 説明 |
---|---|---|
version | integer | GINバージョン番号 |
pending_pages | integer | 待機中リスト内のページ数 |
pending_tuples | bigint | 待機中リスト内のタプル数 |
pgstathashindex(regclass) returns record
pgstathashindex
は、HASHインデックスに関する情報を示すレコードを返します。
以下に例を示します。
test=> select * from pgstathashindex('con_hash_index'); -[ RECORD 1 ]--+----------------- version | 4 bucket_pages | 33081 overflow_pages | 0 bitmap_pages | 1 unused_pages | 32455 live_items | 10204006 dead_items | 0 free_percent | 61.8005949100872
出力列は以下の通りです。
列 | 型 | 説明 |
---|---|---|
version | integer | HASHバージョン番号 |
bucket_pages | bigint | バケットページの数 |
overflow_pages | bigint | オーバーフローページの数 |
bitmap_pages | bigint | ビットマップページの数 |
unused_pages | bigint | 使われていないページの数 |
live_items | bigint | 有効なタプルの数 |
dead_tuples | bigint | 無効なタプルの数 |
free_percent | float | 空き領域の割合 |
pg_relpages(regclass) returns bigint
pg_relpages
はリレーション内のページ数を返します。
pg_relpages(text) returns bigint
TEXTで対象リレーションを指定する点を除き、これはpg_relpages(regclass)
と同じです。
この関数は今までのところ後方互換のために残されており、近い将来のリリースでは廃止予定になるでしょう。
pgstattuple_approx(regclass) returns record
pgstattuple_approx
はpgstattuple
の代わりとなる高速なバージョンで、近似の結果を返します。
引数は対象のリレーションの名前またはOIDです。
以下に例を示します。
test=> SELECT * FROM pgstattuple_approx('pg_catalog.pg_proc'::regclass); -[ RECORD 1 ]--------+------- table_len | 573440 scanned_percent | 2 approx_tuple_count | 2740 approx_tuple_len | 561210 approx_tuple_percent | 97.87 dead_tuple_count | 0 dead_tuple_len | 0 dead_tuple_percent | 0 approx_free_space | 11996 approx_free_percent | 2.09
出力列については表 F.23で説明します。
pgstattuple
が常に全件走査を実行し、有効タプルと無効タプルの正確な数(およびそのサイズ)と空き領域を返すのに対し、pgstattuple_approx
は全件走査を避けようとし、無効タプルの正確な統計情報および有効タプルと空き領域の数とサイズの近似値を返します。
可視性マップに従えば可視のタプルしかないページ(ページに対応するVMビットがセットされているなら、無効タプルが含まれていないとみなします)についてスキップすることで、これを実現します。 そのようなページについて空き領域の値を空き領域マップから導き、ページ上の残りのスペースは有効タプルによって占められているとみなします。
スキップできないページについては、各タプルをスキャンし、その存在とサイズを適切なカウンターに記録し、ページ上の空き領域を加算します。 最後に有効タプルの合計数をスキャンしたページとタプルの数に基づいて推定します(VACUUMがpg_class.reltuplesを推定するのと同じ方法です)。
表F.23 pgstattuple_approx
の出力列
列 | 型 | 説明 |
---|---|---|
table_len | bigint | リレーションの物理的なバイト長(正確) |
scanned_percent | float8 | スキャンしたテーブルの割合 |
approx_tuple_count | bigint | 有効タプル数(推定) |
approx_tuple_len | bigint | 有効タプルの合計のバイト長(推定) |
approx_tuple_percent | float8 | 有効タプルの割合 |
dead_tuple_count | bigint | 無効タプル数(正確) |
dead_tuple_len | bigint | 無効タプルの合計のバイト長(正確) |
dead_tuple_percent | float8 | 無効タプルの割合 |
approx_free_space | bigint | 空き領域の合計バイト数(推定) |
approx_free_percent | float8 | 空き領域の割合 |
上記の出力で、空き領域の数字はpgstattuple
の出力と正確には一致しないかもしれません。
これは空き領域マップは正確な数字を提供しますが、バイト単位で正確であることまでは保証されていないためです。
Tatsuo Ishii、Satoshi Nagayasu、Abhijit Menon-Sen