The <filename>pgstattuple</filename> module provides various functions to
obtain tuple-level statistics.
pgstattupleモジュールはタプルレベルの統計情報を入手するための各種関数を提供します。
Because these functions return detailed page-level information, access is
restricted by default. By default, only the
role <literal>pg_stat_scan_tables</literal> has <literal>EXECUTE</literal>
privilege. Superusers of course bypass this restriction. After the
extension has been installed, users may issue <command>GRANT</command>
commands to change the privileges on the functions to allow others to
execute them. However, it might be preferable to add those users to
the <literal>pg_stat_scan_tables</literal> role instead.
これらの関数は詳細なページレベルの情報を返しますので、デフォルトではアクセスが制限されています。
デフォルトではpg_stat_scan_tablesロールだけがEXECUTE権限を持っています。
スーパーユーザは、当然、この制限を無視します。
拡張がインストールされた後、ユーザはGRANTコマンドを発行して他のユーザがそれらを実行できるよう関数に対する権限を変更できます。
しかしながら、その代わりにpg_stat_scan_tablesロールにそのユーザを追加する方が好ましいでしょう。
pgstattuple(regclass) returns record
<function>pgstattuple</function> returns a relation's physical length,
percentage of <quote>dead</quote> tuples, and other info. This may help users
to determine whether vacuum is necessary or not. The argument is the
target relation's name (optionally schema-qualified) or OID.
For example:
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
The output columns are described in <xref linkend="pgstattuple-columns"/>. 出力列を表 F.23で説明します。
表F.23 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 | 空き領域の割合 |
The <literal>table_len</literal> will always be greater than the sum
of the <literal>tuple_len</literal>, <literal>dead_tuple_len</literal>
and <literal>free_space</literal>. The difference is accounted for by
fixed page overhead, the per-page table of pointers to tuples, and
padding to ensure that tuples are correctly aligned.
table_lenは、tuple_len、dead_tuple_len、free_spaceの合計よりも常に大きいです。
違いの原因は、固定ページのオーバーヘッド、ページ毎のタプルへのポインタのテーブル、タプルが正しく整列することを確実にするためのパディングです。
<function>pgstattuple</function> acquires only a read lock on the
relation. So the results do not reflect an instantaneous snapshot;
concurrent updates will affect them.
pgstattuple はリレーション上で読み取りロックのみを獲得します。
ですので、結果はこの瞬間のスナップショットを考慮しません。つまり、同時実行の更新がその結果に影響を与えます。
<function>pgstattuple</function> judges a tuple is <quote>dead</quote> if
<function>HeapTupleSatisfiesDirty</function> returns false.
pgstattupleは、HeapTupleSatisfiesDirtyが偽を返すかどうかで、タプルが「無効」かどうか判定します。
pgstattuple(text) returns record
This is the same as <function>pgstattuple(regclass)</function>, except
that the target relation is specified as TEXT. This function is kept
because of backward-compatibility so far, and will be deprecated in
some future release.
TEXTで対象リレーションを指定する点を除き、これはpgstattuple(regclass)と同じです。
この関数は今までのところ後方互換のために残されており、近い将来のリリースでは廃止予定になるでしょう。
pgstatindex(regclass) returns record
<function>pgstatindex</function> returns a record showing information
about a B-tree index. For example:
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
The output columns are: 出力列は以下の通りです。
| 列 | 型 | 説明 |
|---|---|---|
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 | リーフページの断片化 |
The reported <literal>index_size</literal> will normally correspond to one more
page than is accounted for by <literal>internal_pages + leaf_pages +
empty_pages + deleted_pages</literal>, because it also includes the
index's metapage.
報告されるindex_sizeは、通常、internal_pages + leaf_pages + empty_pages + deleted_pagesが占めるより1多いページに相当するでしょう。
これは、index_sizeがインデックスメタページも含むためです。
As with <function>pgstattuple</function>, the results are accumulated
page-by-page, and should not be expected to represent an
instantaneous snapshot of the whole index.
pgstattuple同様、結果はページ毎に累積されます。
この瞬間のインデックス全体のスナップショットが存在すると想定してはいけません。
pgstatindex(text) returns record
This is the same as <function>pgstatindex(regclass)</function>, except
that the target index is specified as TEXT. This function is kept
because of backward-compatibility so far, and will be deprecated in
some future release.
TEXTで対象インデックスを指定する点を除き、これはpgstatindex(regclass)と同じです。
この関数は今までのところ後方互換のために残されており、近い将来のリリースでは廃止予定になるでしょう。
pgstatginindex(regclass) returns record
<function>pgstatginindex</function> returns a record showing information
about a GIN index. For example:
pgstatginindexは、GINインデックスに関する情報を示すレコードを返します。
以下に例を示します。
test=> SELECT * FROM pgstatginindex('test_gin_index');
-[ RECORD 1 ]--+--
version | 1
pending_pages | 0
pending_tuples | 0
The output columns are: 出力列は以下の通りです。
| 列 | 型 | 説明 |
|---|---|---|
version | integer | GINバージョン番号 |
pending_pages | integer | 待機中リスト内のページ数 |
pending_tuples | bigint | 待機中リスト内のタプル数 |
pgstathashindex(regclass) returns record
<function>pgstathashindex</function> returns a record showing information
about a HASH index. For example:
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
The output columns are: 出力列は以下の通りです。
| 列 | 型 | 説明 |
|---|---|---|
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
<function>pg_relpages</function> returns the number of pages in the
relation.
pg_relpagesはリレーション内のページ数を返します。
pg_relpages(text) returns bigint
This is the same as <function>pg_relpages(regclass)</function>, except
that the target relation is specified as TEXT. This function is kept
because of backward-compatibility so far, and will be deprecated in
some future release.
TEXTで対象リレーションを指定する点を除き、これはpg_relpages(regclass)と同じです。
この関数は今までのところ後方互換のために残されており、近い将来のリリースでは廃止予定になるでしょう。
pgstattuple_approx(regclass) returns record
<function>pgstattuple_approx</function> is a faster alternative to
<function>pgstattuple</function> that returns approximate results.
The argument is the target relation's name or OID.
For example:
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
The output columns are described in <xref linkend="pgstatapprox-columns"/>. 出力列については表 F.24で説明します。
Whereas <function>pgstattuple</function> always performs a
full-table scan and returns an exact count of live and dead tuples
(and their sizes) and free space, <function>pgstattuple_approx</function>
tries to avoid the full-table scan and returns exact dead tuple
statistics along with an approximation of the number and
size of live tuples and free space.
pgstattupleが常に全件スキャンを実行し、有効タプルと無効タプルの正確な数（およびそのサイズ）と空き領域を返すのに対し、pgstattuple_approxは全件スキャンを避けようとし、無効タプルの正確な統計情報および有効タプルと空き領域の数とサイズの近似値を返します。
It does this by skipping pages that have only visible tuples according to the visibility map (if a page has the corresponding VM bit set, then it is assumed to contain no dead tuples). For such pages, it derives the free space value from the free space map, and assumes that the rest of the space on the page is taken up by live tuples. 可視性マップに従えば可視のタプルしかないページ（ページに対応するVMビットがセットされているなら、無効タプルが含まれていないとみなします）についてスキップすることで、これを実現します。 そのようなページについて空き領域の値を空き領域マップから導き、ページ上の残りのスペースは有効タプルによって占められているとみなします。
For pages that cannot be skipped, it scans each tuple, recording its presence and size in the appropriate counters, and adding up the free space on the page. At the end, it estimates the total number of live tuples based on the number of pages and tuples scanned (in the same way that VACUUM estimates pg_class.reltuples). スキップできないページについては、各タプルをスキャンし、その存在とサイズを適切なカウンタに記録し、ページ上の空き領域を加算します。 最後に有効タプルの合計数をスキャンしたページとタプルの数に基づいて推定します（VACUUMがpg_class.reltuplesを推定するのと同じ方法です）。
表F.24 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 | 空き領域の割合 |
In the above output, the free space figures may not match the
<function>pgstattuple</function> output exactly, because the free
space map gives us an exact figure, but is not guaranteed to be
accurate to the byte.
上記の出力で、空き領域の数字はpgstattupleの出力と正確には一致しないかもしれません。
これは空き領域マップは正確な数字を提供しますが、バイト単位で正確であることまでは保証されていないためです。
Tatsuo Ishii, Satoshi Nagayasu and Abhijit Menon-Sen Tatsuo Ishii、Satoshi Nagayasu、Abhijit Menon-Sen