Перейти к основному содержимому

pgstattuple. Функции для получения статистики на уровне кортежей

В исходном дистрибутиве установлено по умолчанию: да.

Связанные компоненты: отсутствуют.

Схема размещения: ext.

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

Функции​

pgstattuple​

Применение функции возможно для принятия решения о необходимости очистки.

Функция получает блокировку отношения только для чтения.

Формат:

pgstattuple(
    REGCLASS
) RETURNS RECORD
pgstattuple(
    TEXT
) RETURNS RECORD

Входные параметры:

В качестве аргумента могут передаваться:

  • имя отношения;
  • схема.имя;
  • OID отношения.

Возвращаемые значения:

СтолбецТипОписание
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. Разница объясняется:

  • фиксированными издержками;
  • внутристраничной таблицей указателей на кортежи;
  • пропусками, добавляемыми для выравнивания кортежей.

pgstatindex​

Функция pgstatindex возвращает запись с информацией об индексе типа B-дерево.

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

Формат:

pgstatindex(
    REGCLASS
) RETURNS RECORD
pgstatindex(
    TEXT
) RETURNS RECORD

Входные параметры:

В качестве аргумента могут передаваться:

  • имя отношения;
  • схема.имя;
  • OID отношения.

Возвращаемые значения:

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

pgstatginindex​

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

Формат:

pgstatginindex(
    REGCLASS
) RETURNS RECORD

Входные параметры:

В качестве аргумента могут передаваться:

  • имя отношения;
  • схема.имя;
  • OID отношения.

Возвращаемые значения:

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

pgstathashindex​

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

Формат:

pgstathashindex(
    REGCLASS
) RETURNS RECORD

Входные параметры:

В качестве аргумента могут передаваться:

  • имя отношения;
  • схема.имя;
  • OID отношения.

Возвращаемые значения:

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

pg_relpages​

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

Формат:

pg_relpages(
    REGCLASS
) RETURNS BIGINT
pg_relpages(
    TEXT
) RETURNS BIGINT

Входные параметры:

В качестве аргумента могут передаваться:

  • имя отношения;
  • схема.имя;
  • OID отношения.

Возвращаемые значения:

Число страниц в заданном отношении.

pgstattuple_approx​

Функция возвращает приблизительные значения физической длины отношения, процента «мертвых» кортежей и другую информацию и является более быстрой альтернативой pgstattuple.

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

Различия функций pgstattuple и pgstattuple_approx:

Параметрpgstattuplepgstattuple_approx
Полное сканирование таблицыВсегдаНет
Количество «живых» кортежейТочноПриблизительно
Количество «мертвых» кортежейТочноТочно
Размер «живых» кортежейТочноПриблизительно
Размер «мертвых» кортежейТочноТочно
Объем свободного пространстваТочноПриблизительно

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

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

Формат:

pgstattuple_approx(
    REGCLASS
) RETURNS RECORD

Входные параметры:

В качестве аргумента могут передаваться:

  • имя отношения;
  • схема.имя;
  • OID отношения.

Возвращаемые значения:

СтолбецТипОписание
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Процент свободного пространства

Доработка​

Доработка не проводилась.

Ограничения​

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

Установка​

При наличии прав администратора СУБД включение модуля выполняется запросом:

CREATE EXTENSION pgstattuple SCHEMA ext;

Настройка​

Настройка не требуется.

Использование модуля​

SELECT * FROM pgstattuple('pg_catalog.pg_proc') \gx

Пример результата выполнения функции:

-[ RECORD 1 ]------+--------
table_len          | 1294336
tuple_count        | 3779
tuple_len          | 1110651
tuple_percent      | 85.81
dead_tuple_count   | 14
dead_tuple_len     | 5080
dead_tuple_percent | 0.39
free_space         | 144716
free_percent       | 11.18

Пример функции с переданным текстовым именем в качестве аргумента:

SELECT * FROM pgstattuple ('message') \gx

Пример функции с переданным OID в качестве аргумента:

SELECT 'message'::regclass::oid;
-[ RECORD 1 ]
oid | 165575
SELECT * FROM pgstattuple (165575) \gx

Пример результата выполнения функции:

-[ RECORD 1 ]------+------
table_len          | 8192
tuple_count        | 4
tuple_len          | 280
tuple_percent      | 3.42
dead_tuple_count   | 4
dead_tuple_len     | 265
dead_tuple_percent | 3.23
free_space         | 7556
free_percent       | 92.24

Функция pgstatindex возвращает запись с информацией об индексе типа B-дерево:

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

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

SELECT * FROM ext.pgstatginindex('testidx');

Пример результата выполнения функции:

 version | pending_pages | pending_tuples 
---------+---------------+----------------
       2 |             0 |              0
(1 row)

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

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

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

SELECT * FROM pg_relpages('message');

Пример результата выполнения функции:

 pg_relpages 
-------------
           1
(1 row)

Функция pgstattuple_approx возвращает приблизительные значения физической длины отношения, процента «мертвых» кортежей и другую информацию:

SELECT * FROM pgstattuple_approx('ext.message'::regclass) \gx

Пример результата выполнения функции:

-[ RECORD 1 ]--------+--------------
table_len            | 8192
scanned_percent      | 100
approx_tuple_count   | 4
approx_tuple_len     | 280
approx_tuple_percent | 3.41796875
dead_tuple_count     | 4
dead_tuple_len       | 265
dead_tuple_percent   | 3.23486328125
approx_free_space    | 7556
approx_free_percent  | 92.236328125

Ссылки на документацию разработчика​

Исходная документация PosgreSQL по модулю pgstattuple: https://www.postgresql.org/docs/15/pgstattuple.html