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_len、dead_tuple_len和free_space之和。差值来自固定的页开销、每页的元组指针表，以及为保证元组正确对齐而产生的填充。pgstattuple只会在该关系上获取读锁。因此，结果并不代表一个瞬时快照；并发更新会影响结果。如果
HeapTupleSatisfiesDirty返回 false，pgstattuple就会将该元组判定为“死”。-
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输出列如下：
列 类型 描述 versionintegerB-树版本号 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 页，因为它还包含索引的元页。与
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输出列如下：
列 类型 描述 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_itemsbigint死元组数量 free_percentfloat空闲空间百分比 -
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输出列的说明见表 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