2025年9月25日: PostgreSQL 18 釋出!
支援的版本: 當前 (18) / 17 / 16 / 15 / 14 / 13
開發版本: devel
不支援的版本: 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3

F.33. pgstattuple — 獲取元組級統計資訊 #

pgstattuple 模組提供了各種用於獲取元組級統計資訊的函式。

由於這些函式返回詳細的頁面級資訊,預設情況下訪問受到限制。預設情況下,只有 pg_stat_scan_tables 角色擁有 EXECUTE 許可權。超級使用者當然可以繞過此限制。擴充套件安裝後,使用者可以發出 GRANT 命令來更改函式上的許可權,允許其他人執行它們。但是,將這些使用者新增到 pg_stat_scan_tables 角色可能更可取。

F.33.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.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_lendead_tuple_lenfree_space 的總和。差異是由固定頁面開銷、指向元組的每頁指標表以及填充以確保元組正確對齊造成的。

pgstattuple 只獲取關係的讀鎖。因此,結果不反映瞬時快照;併發更新會影響它們。

如果 HeapTupleSatisfiesDirty 返回 false,則 pgstattuple 將一個元組判斷為死元組

pgstattuple(text) returns record

這與 pgstattuple(regclass) 相同,只是目標關係指定為 TEXT。此函式因向後相容而保留,將在將來的某個版本中棄用。

pgstatindex(regclass) returns record

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

輸出列為

型別 描述
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 葉子頁面碎片

報告的 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.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 and Abhijit Menon-Sen

提交更正

如果您在文件中發現任何不正確、與您對特定功能的體驗不符或需要進一步澄清的內容,請使用 此表單 報告文件問題。