PostgreSQL：文件：17：F.31. pgstattuple — 取得 Tuple 層級統計資訊

支援的版本：目前 (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.31. pgstattuple — 取得 Tuple 層級統計資訊
上一個	上方	附錄 F. 其他提供的模組和擴充功能	首頁	下一個

F.31. pgstattuple — 取得 Tuple 層級統計資訊 #

F.31.1. 函式
F.31.2. 作者

pgstattuple 模組提供各種函式來取得 tuple 層級的統計資訊。

因為這些函式會傳回詳細的頁面層級資訊，所以預設會限制存取。預設情況下，只有角色 pg_stat_scan_tables 具有 EXECUTE 權限。當然，超級使用者可以繞過此限制。安裝擴充功能後，使用者可以發出 GRANT 指令來變更函式的權限，以允許其他人執行它們。但是，最好將這些使用者新增到 pg_stat_scan_tables 角色中。

F.31.1. 函式 #

pgstattuple(regclass) returns record

pgstattuple 傳回關聯的實際長度、“dead” tuples 的百分比，以及其他資訊。這可以幫助使用者判斷是否需要 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`	有效 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`	可用空間的百分比

注意

table_len 將永遠大於 tuple_len、dead_tuple_len 和 free_space 的總和。差異是由固定的頁面開銷、每頁的 tuples 指標表，以及填充以確保 tuples 正確對齊所導致的。

pgstattuple 只取得關聯上的讀取鎖定。因此，結果並未反映即時快照；並行的更新會影響它們。

如果 HeapTupleSatisfiesDirty 傳回 false，pgstattuple 會判斷 tuple 為 “dead”。

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`	“internal” (上層) 頁面的數量
`leaf_pages`	`bigint`	Leaf 頁面的數量
`empty_pages`	`bigint`	空頁面的數量
`deleted_pages`	`bigint`	已刪除頁面的數量
`avg_leaf_density`	`float8`	Leaf 頁面的平均密度
`leaf_fragmentation`	`float8`	Leaf 頁面碎片

報告的 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`	暫止清單中的 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

輸出欄位為

欄位	類型	描述
`version`	`integer`	HASH 版本號
`bucket_pages`	`bigint`	Bucket 頁面的數量
`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

輸出欄位描述於表 F.24。

雖然 pgstattuple 始終執行完整表格掃描，並傳回 live 和 dead 元組（及其大小）和可用空間的精確計數，但 pgstattuple_approx 嘗試避免完整表格掃描，並傳回精確的 dead 元組統計資訊，以及 live 元組數量和大小以及可用空間的近似值。

它通過跳過根據可見性地圖 (visibility map) 僅具有可見元組的頁面來做到這一點（如果頁面具有相應的 VM 位元設定，則假定它不包含 dead 元組）。對於這些頁面，它從可用空間地圖 (free space map) 中導出可用空間值，並假定頁面上的其餘空間被 live 元組佔用。

對於無法跳過的頁面，它會掃描每個元組，將其存在和大小記錄在適當的計數器中，並將頁面上的可用空間加起來。最後，它根據掃描的頁面和元組數量估計 live 元組的總數（與 VACUUM 估計 pg_class.reltuples 的方式相同）。

表 F.24. pgstattuple_approx 輸出欄位

欄位	類型	描述
`table_len`	`bigint`	以位元組為單位的實體關係長度（精確）
`scanned_percent`	`float8`	掃描的表格百分比
`approx_tuple_count`	`bigint`	Live 元組的數量（估計）
`approx_tuple_len`	`bigint`	Live 元組的總長度（以位元組為單位）（估計）
`approx_tuple_percent`	`float8`	有效 tuples 的百分比
`dead_tuple_count`	`bigint`	Dead 元組的數量（精確）
`dead_tuple_len`	`bigint`	Dead 元組的總長度（以位元組為單位）（精確）
`dead_tuple_percent`	`float8`	無效 tuples 的百分比
`approx_free_space`	`bigint`	可用空間總量（以位元組為單位）（估計）
`approx_free_percent`	`float8`	可用空間的百分比

在上述輸出中，可用空間的數字可能與 pgstattuple 的輸出不完全匹配，因為可用空間地圖給我們一個精確的數字，但不保證字節的準確性。

F.31.2. 作者 #

Tatsuo Ishii、Satoshi Nagayasu 和 Abhijit Menon-Sen

上一個	上方	下一個
F.30. pg_stat_statements — 追蹤 SQL 計畫和執行的統計資訊	首頁	F.32. pg_surgery — 對關係資料執行低階手術

提交更正

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