2024年9月26日: PostgreSQL 17 发布!
支持的版本:当前 (17) / 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

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

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

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

F.31.1. 函数 #

pgstattuple(regclass) returns record

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.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 空闲空间的百分比

注意

table_len 将始终大于 tuple_lendead_tuple_lenfree_space 的总和。差异由固定的页面开销、指向元组的页面内指针表以及确保元组正确对齐的填充来解释。

pgstattuple 仅获取关系上的读锁。因此,结果不会反映瞬时快照;并发更新会影响它们。

pgstattuple 判断元组是否“已删除”,如果 HeapTupleSatisfiesDirty 返回 false。

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

输出列为

类型 描述
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

输出列为

类型 描述
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

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

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.24中描述。

虽然 pgstattuple 始终执行全表扫描并返回活动和已删除元组(及其大小)以及空闲空间的确切计数,但 pgstattuple_approx 尝试避免全表扫描并返回确切的已删除元组统计信息以及活动元组数量和大小以及空闲空间的近似值。

它通过跳过仅包含可见元组的页面来实现此目的(如果页面设置了相应的 VM 位,则假定它不包含任何已删除元组)。对于此类页面,它从空闲空间映射派生空闲空间值,并假设页面上的其余空间被活动元组占用。

对于无法跳过的页面,它会扫描每个元组,将元组的存在和大小记录在相应的计数器中,并将页面上的空闲空间加起来。最后,它根据扫描的页面和元组数量估计活动元组的总数(与 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 空闲空间的百分比

在上面的输出中,空闲空间数据可能与 pgstattuple 输出不完全匹配,因为空闲空间映射为我们提供了精确的数据,但不能保证其准确到字节。

F.31.2. 作者 #

石井辰雄、永安聪和 Abhijit Menon-Sen

提交更正

如果您在文档中看到任何不正确的内容、与您对特定功能的体验不符的内容或需要进一步说明的内容,请使用此表单报告文档问题。