F.31. pgstattuple

Модуль pgstattuple предоставляет различные функции для получения статистики на уровне кортежей.

Так как эти функции возвращают подробную информацию, относящуюся к уровню страницы, доступ к ним по умолчанию ограничен. Право EXECUTE для них имеет только роль pg_stat_scan_tables. Разумеется, суперпользователи могут обойти это ограничение. После того как это расширение установлено, можно поменять права доступа к этим функциям командами GRANT и разрешить их выполнение другим пользователям. Однако предпочтительнее будет добавить этих пользователей в роль pg_stat_scan_tables.

F.31.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.23.

Таблица F.23. Столбцы результата 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 получает блокировку отношения только для чтения. Таким образом, её результаты отражают не мгновенный снимок; на них будут влиять параллельные изменения.

pgstattuple считает кортеж «мёртвым», если HeapTupleSatisfiesDirty возвращает false.

pgstattuple(text) returns record

Эта функция равнозначна функции pgstattuple(regclass) за исключением того, что для неё целевое отношение задаётся в текстовом виде. Данная функция оставлена для обратной совместимости, в будущем она может перейти в разряд устаревших.

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

Столбцы результата:

СтолбецТипОписание
versionintegerНомер версии B-дерева
tree_levelintegerУровень корневой страницы в дереве
index_sizebigintОбщий объём индекса в байтах
root_block_nobigintРасположение страницы корня (0, если её нет)
internal_pagesbigintКоличество «внутренних» страниц (верхнего уровня)
leaf_pagesbigintКоличество страниц на уровне листьев
empty_pagesbigintКоличество пустых страниц
deleted_pagesbigintКоличество удалённых страниц
avg_leaf_densityfloat8Средняя плотность страниц на уровне листьев
leaf_fragmentationfloat8Фрагментация на уровне листьев

Выдаваемый размер индекса (index_size) обычно вычисляется по формуле internal_pages + leaf_pages + empty_pages + deleted_pages плюс одна страница, так как в нём учитывается и метастраница индекса.

Как и pgstattuple, эта функция собирает данные страница за страницей и не следует ожидать, что её результат представляет мгновенный снимок всего индекса.

pgstatindex(text) returns record

Эта функция равнозначна функции pgstatindex(regclass) за исключением того, что для неё целевое отношение задаётся в текстовом виде. Данная функция оставлена для обратной совместимости, в будущем она может перейти в разряд устаревших.

pgstatginindex(regclass) returns record

Функция pgstatginindex возвращает запись с информацией об индексе типа GIN. Например:

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

Столбцы результата:

СтолбецТипОписание
versionintegerНомер версии GIN
pending_pagesintegerКоличество страниц в списке ожидающих обработки
pending_tuplesbigintКоличество кортежей в списке ожидающих обработки
pgstathashindex(regclass) returns record

Функция pgstathashindex возвращает запись с информацией о хеш-индексе. Например:

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

Столбцы результата:

СтолбецТипОписание
versionintegerНомер версии HASH
bucket_pagesbigintКоличество страниц групп
overflow_pagesbigintКоличество страниц переполнения
bitmap_pagesbigintКоличество страниц битовой карты
unused_pagesbigintКоличество неиспользованных страниц
live_itemsbigintКоличество «живых» кортежей
dead_tuplesbigintКоличество «мёртвых» кортежей
free_percentfloatПроцент свободного пространства
pg_relpages(regclass) returns bigint

Функция pg_relpages возвращает число страниц в отношении.

pg_relpages(text) returns bigint

Эта функция равнозначна функции pg_relpages(regclass) за исключением того, что для неё целевое отношение задаётся в текстовом виде. Данная функция оставлена для обратной совместимости, в будущем она может перейти в разряд устаревших.

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 всегда производит полное сканирование таблицы и возвращает точное число живых и мёртвых кортежей (и их размер), а также точный объём свободного пространства, функция pgstattuple_approx пытается избежать полного сканирования и возвращает точную статистику только по мёртвым кортежам, а количество и объём живых кортежей, как и объём свободного пространства определяет приблизительно.

Она делает это, пропуская страницы, в которых, согласно карте видимости, есть только видимые кортежи (если для страницы установлен соответствующий бит, предполагается, что она не содержит мёртвых кортежей). Для таких страниц эта функция узнаёт объём свободного пространства из карты свободного пространства и предполагает, что остальное пространство на странице занято живыми кортежами.

На страницах, которые нельзя пропустить, она сканирует каждый кортеж, отражает его наличие и размер в соответствующих счётчиках и суммирует свободное пространство на странице. В конце она оценивает приблизительно общее число живых кортежей, исходя из числа просканированных страниц и кортежей (так же, как VACUUM рассчитывает значение pg_class.reltuples).

Таблица F.24. Столбцы результата 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.31.2. Авторы

Тацуо Исии, Сатоши Нагаясу и Абхиджит Менон-Сен