pgstattuple

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

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


Функции

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

Выходные столбцы описаны в Таблице 23.

Таблица 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

Выходные столбцы описаны в Таблице 24.

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

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

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

Таблица 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, потому что карта свободного пространства выдает правильное значение, но не гарантирует, что оно будет точным до байта.


Авторы

Тацуо Ишии (Tatsuo Ishii), Сатоши Нагаясу (Satoshi Nagayasu) и Абхиджит Менон-Сен (Abhijit Menon-Sen)