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

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

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

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

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

Функции#

pgstattuple#

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

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

Формат:

pgstattuple(
    REGCLASS
) RETURNS RECORD

pgstattuple(
    TEXT
) RETURNS RECORD

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

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

• имя отношения;

• схема.имя;

• OID отношения.

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

Замечание:

Значение table_len всегда будет больше суммы tuple_len, dead_tuple_len и free_space. Разница объясняется:

• фиксированными издержками;

• внутристраничной таблицей указателей на кортежи;

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

pgstatindex#

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

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

Формат:

pgstatindex(
    REGCLASS
) RETURNS RECORD

pgstatindex(
    TEXT
) RETURNS RECORD

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

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

• имя отношения;

• схема.имя;

• OID отношения.

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

pgstatginindex#

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

Формат:

pgstatginindex(
    REGCLASS
) RETURNS RECORD

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

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

• имя отношения;

• схема.имя;

• OID отношения.

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

pgstathashindex#

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

Формат:

pgstathashindex(
    REGCLASS
) RETURNS RECORD

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

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

• имя отношения;

• схема.имя;

• OID отношения.

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

pg_relpages#

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

Формат:

pg_relpages(
    REGCLASS
) RETURNS BIGINT

pg_relpages(
    TEXT
) RETURNS BIGINT

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

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

• имя отношения;

• схема.имя;

• OID отношения.

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

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

pgstattuple_approx#

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

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

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

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

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

Формат:

pgstattuple_approx(
    REGCLASS
) RETURNS RECORD

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

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

• имя отношения;

• схема.имя;

• OID отношения.

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

Доработка#

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

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

Функции расширения возвращают подробную информацию, относящуюся к уровню страницы, поэтому доступ к ним по умолчанию ограничен. Право 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