F.33. pgstattuple — 获取元组级统计信息#

F.33.1. 函数

F.33.2. 作者

pgstattuple模块提供各种函数来获取元组级统计信息。

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

F.33.1. 函数#

pgstattuple(regclass) 返回记录

pgstattuple 返回关系的物理长度、“死”元组的百分比和其他信息。这可能有助于用户确定是否需要执行 vacuum。参数是目标关系的名称（可选地限定架构）或 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.24 中进行描述。

表 F.24. 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 返回 false。

pgstattuple(text) 返回记录

这与 pgstattuple(regclass) 相同，只是目标关系指定为 TEXT。到目前为止，此函数已保留，因为向后兼容，并且将在某些未来版本中弃用。

pgstatindex(regclass) 返回记录

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

输出列是

列	类型	描述
版本	整数	B 树版本号
tree_level	整数	根页面的树级别
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) 返回记录

这与 pgstatindex(regclass) 相同，只是目标索引指定为 TEXT。到目前为止，此函数因向后兼容性而保留，并且将在未来某个版本中弃用。

pgstatginindex(regclass) 返回记录

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

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

输出列是

列	类型	描述
版本	整数	GIN 版本号
pending_pages	整数	待处理列表中的页面数
pending_tuples	bigint	待处理列表中的元组数

pgstathashindex(regclass) 返回记录

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

输出列是

列	类型	描述
版本	整数	HASH 版本号
bucket_pages	bigint	存储桶页面的数量
overflow_pages	bigint	溢出页面的数量
bitmap_pages	bigint	位图页面的数量
unused_pages	bigint	未使用的页面的数量
live_items	bigint	活动元组数
dead_tuples	bigint	死元组数
free_percent	浮点数	可用空间的百分比

pg_relpages(regclass) 返回 bigint

pg_relpages 返回关系中的页面数。

pg_relpages(text) 返回 bigint

这与 pg_relpages(regclass) 相同，只是目标关系指定为 TEXT。到目前为止，此函数因向后兼容性而保留，并且将在未来某个版本中弃用。

pgstattuple_approx(regclass) 返回记录

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.25 中进行了描述。

虽然 pgstattuple 始终执行全表扫描并返回活动和死元组（以及它们的大小）和可用空间的确切计数，但 pgstattuple_approx 尝试避免全表扫描并返回确切的死元组统计信息以及活动元组和可用空间数量和大小的近似值。

它通过跳过根据可见性映射仅具有可见元组的页面来执行此操作（如果页面设置了相应的 VM 位，则假定它不包含死元组）。对于此类页面，它从可用空间映射中派生出可用空间值，并假定页面上的其余空间被活动元组占用。

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

表 F.25. 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 输出不完全匹配，因为可用空间映射为我们提供了精确的数字，但不能保证精确到字节。

F.33.2. 作者#

Tatsuo Ishii、Satoshi Nagayasu 和 Abhijit Menon-Sen