★PostgreSQLカンファレンス2024 12月6日開催/チケット販売中★
他のバージョンの文書 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

F.30. pgstattuple

pgstattupleモジュールはタプルレベルの統計情報を入手するための各種関数を提供します。

これらの関数は詳細なページレベルの情報を返しますので、デフォルトではアクセスが制限されています。 デフォルトではpg_stat_scan_tablesロールだけがEXECUTE権限を持っています。 スーパーユーザは、当然、この制限を無視します。 拡張がインストールされた後、ユーザはGRANTコマンドを発行して他のユーザがそれらを実行できるよう関数に対する権限を変更できます。 しかしながら、その代わりにpg_stat_scan_tablesロールにそのユーザを追加する方が好ましいでしょう。

F.30.1. 関数

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_lenbigintリレーションのバイト単位の物理長
tuple_countbigint有効なタプル数
tuple_lenbigint有効なタプルの物理長(バイト単位)
tuple_percentfloat8有効タプルの割合
dead_tuple_countbigint無効なタプル数
dead_tuple_lenbigintバイト単位の総無効タプル長
dead_tuple_percentfloat8無効タプルの割合
free_spacebigintバイト単位の総空き領域
free_percentfloat8空き領域の割合

注記

table_lenは、tuple_lendead_tuple_lenfree_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

出力列は以下の通りです。

説明
versionintegerB-treeバージョン番号
tree_levelintegerルートページのツリーレベル
index_sizebigintバイト単位のインデックスサイズ
root_block_nobigintルートページの場所(存在しない場合はゼロ)
internal_pagesbigint内部(上位レベル)ページ数
leaf_pagesbigintリーフページ数
empty_pagesbigint空ページ数
deleted_pagesbigint削除ページ数
avg_leaf_densityfloat8リーフページの平均密度
leaf_fragmentationfloat8リーフページの断片化

報告される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

出力列は以下の通りです。

説明
versionintegerGINバージョン番号
pending_pagesinteger待機中リスト内のページ数
pending_tuplesbigint待機中リスト内のタプル数

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

出力列は以下の通りです。

説明
versionintegerHASHバージョン番号
bucket_pagesbigintバケットページの数
overflow_pagesbigintオーバーフローページの数
bitmap_pagesbigintビットマップページの数
unused_pagesbigint使われていないページの数
live_itemsbigint有効なタプルの数
dead_tuplesbigint無効なタプルの数
free_percentfloat空き領域の割合

pg_relpages(regclass) returns bigint

pg_relpagesはリレーション内のページ数を返します。

pg_relpages(text) returns bigint

TEXTで対象リレーションを指定する点を除き、これはpg_relpages(regclass)と同じです。 この関数は今までのところ後方互換のために残されており、近い将来のリリースでは廃止予定になるでしょう。

pgstattuple_approx(regclass) returns record

pgstattuple_approxpgstattupleの代わりとなる高速なバージョンで、近似の結果を返します。 引数は対象のリレーションの名前または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_lenbigintリレーションの物理的なバイト長(正確)
scanned_percentfloat8スキャンしたテーブルの割合
approx_tuple_countbigint有効タプル数(推定)
approx_tuple_lenbigint有効タプルの合計のバイト長(推定)
approx_tuple_percentfloat8有効タプルの割合
dead_tuple_countbigint無効タプル数(正確)
dead_tuple_lenbigint無効タプルの合計のバイト長(正確)
dead_tuple_percentfloat8無効タプルの割合
approx_free_spacebigint空き領域の合計バイト数(推定)
approx_free_percentfloat8空き領域の割合

上記の出力で、空き領域の数字はpgstattupleの出力と正確には一致しないかもしれません。 これは空き領域マップは正確な数字を提供しますが、バイト単位で正確であることまでは保証されていないためです。

F.30.2. 作者

Tatsuo Ishii、Satoshi Nagayasu、Abhijit Menon-Sen