F.30. pgstattuple

• F.30.1. Functions

• F.30.2. Authors

pgstattuple模块提供各种功能来获取 Tuples 级别的统计信息。

由于这些函数返回详细的页面级信息，因此默认情况下限制访问。默认情况下，只有角色pg_stat_scan_tables拥有EXECUTE特权。超级用户当然会绕过此限制。安装扩展后，用户可以发出GRANT命令来更改功能的特权，以允许其他人执行它们。但是，最好将这些用户添加到pg_stat_scan_tables角色。

F.30.1. Functions

• pgstattuple(regclass) returns record

  • pgstattuple返回关系的物理长度，“死”Tuples 的百分比以及其他信息。这可以帮助用户确定是否需要真空。参数是目标关系的名称(可选为模式限定)或 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

输出列在Table F.22中描述。

表 F.22.pgstattuple输出列

Column	Type	Description
table_len	bigint	物理关系长度(以字节为单位)
tuple_count	bigint	活动 Tuples 数
tuple_len	bigint	活动 Tuples 的总长度(以字节为单位)
tuple_percent	float8	活动 Tuples 的百分比
dead_tuple_count	bigint	死 Tuples 数
dead_tuple_len	bigint	死 Tuples 的总长度(以字节为单位)
dead_tuple_percent	float8	死 Tuples 的百分比
free_space	bigint	总可用空间(以字节为单位)
free_percent	float8	可用空间百分比

pgstattuple仅获得该关系的读取锁。因此，结果不会反映即时快照。并发更新将影响它们。

如果HeapTupleSatisfiesDirty返回 false，则pgstattuple判断 Tuples 为“死”。

• pgstattuple(text) returns record

  • 与pgstattuple(regclass)相同，除了将目标关系指定为 TEXT。到目前为止，由于向后兼容而保留了此功能，在将来的某些发行版中将不推荐使用此功能。

• pgstatindex(regclass) returns record

  • pgstatindex返回一条记录，该记录显示有关 B 树索引的信息。例如：

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

输出列为：

Column	Type	Description
version	integer	B 树版本号
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所占页面多一页，因为它还包含索引的元页面。

与pgstattuple一样，结果是逐页累积的，不应期望代表整个索引的瞬时快照。

• pgstatindex(text) returns record

  • 与pgstatindex(regclass)相同，除了目标索引指定为 TEXT。到目前为止，由于向后兼容而保留了此功能，在将来的某些发行版中将不推荐使用此功能。

• pgstatginindex(regclass) returns record

  • pgstatginindex返回一条记录，该记录显示有关 GIN 索引的信息。例如：

test=> SELECT * FROM pgstatginindex('test_gin_index');
-[ RECORD 1 ]--+--
version        | 1
pending_pages  | 0
pending_tuples | 0

输出列为：

Column	Type	Description
version	integer	GIN 版本号
pending_pages	integer	待处理列表中的页数
pending_tuples	bigint	待处理列表中的 Tuples 数

• 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

输出列为：

Column	Type	Description
version	integer	哈希版本号
bucket_pages	bigint	存储桶页数
overflow_pages	bigint	溢出页数
bitmap_pages	bigint	位图页数
unused_pages	bigint	未使用的页数
live_items	bigint	活动 Tuples 数
dead_tuples	bigint	死 Tuples 数
free_percent	float	可用空间百分比

• pg_relpages(regclass) returns bigint

  • pg_relpages返回关系中的页数。

• pg_relpages(text) returns bigint

  • 与pg_relpages(regclass)相同，除了将目标关系指定为 TEXT。到目前为止，由于向后兼容而保留了此功能，在将来的某些发行版中将不推荐使用此功能。

• 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

输出列在Table F.23中描述。

pgstattuple始终执行全表扫描并返回活动和死 Tuples(及其大小)和可用空间的准确计数，而pgstattuple_approx尝试避免进行全表扫描，并返回精确的死 Tuples 统计信息以及该数目的近似值 Tuples 的大小和可用空间。

它通过根据可见性图跳过仅具有可见 Tuples 的页面来完成此操作(如果页面设置了相应的 VM 位，则假定该页面不包含无效 Tuples)。对于此类页面，它从自由空间 Map 中得出自由空间值，并假定页面上的其余空间已被活动 Tuples 占用。

对于无法跳过的页面，它将扫描每个 Tuples，并在适当的计数器中记录其存在和大小，并累加页面上的可用空间。最后，它根据扫描的页面和 Tuples 的数量来估计活动 Tuples 的总数(与 VACUUM 估计 pg_class.reltuples 的方式相同)。

表 F.23.pgstattuple_approx输出列

Column	Type	Description
table_len	bigint	物理关系长度(以字节为单位)(精确)
scanned_percent	float8	扫描表的百分比
approx_tuple_count	bigint	活动 Tuples 数(估计)
approx_tuple_len	bigint	活动 Tuples 的总长度(以字节为单位)(估计)
approx_tuple_percent	float8	活动 Tuples 的百分比
dead_tuple_count	bigint	死 Tuples 数(准确)
dead_tuple_len	bigint	死 Tuples 的总长度(以字节为单位)(精确)
dead_tuple_percent	float8	死 Tuples 的百分比
approx_free_space	bigint	总可用空间(以字节为单位)(估计)
approx_free_percent	float8	可用空间百分比

在上面的输出中，可用空间数字可能与pgstattuple输出不完全匹配，因为可用空间 Map 为我们提供了精确的数字，但不能保证精确到该字节。

F.30.2. Authors

石井达男，永安聪和阿比 Git·梅农森