PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 12.18 » Annexes » Modules supplémentaires fournis » pgstattuple

F.30. pgstattuple

Le module pgstattuple fournit plusieurs fonctions pour obtenir des statistiques au niveau ligne.

Comme ces fonctions renvoient des informations détaillées au niveau page, l'accès est restreint par défaut. Par défaut, seul le rôle pg_stat_scan_tables a le droit EXECUTE. Bien sûr, les superutilisateurs contournent cette restriction. Après l'installation de l'extension, les utilisateurs peuvent exécuter des commandes GRANT pour modifier les droits sur les fonctions, pour permettre à d'autres rôles de les exécuter. Néanmoins, il serait préférable d'ajouter ces utilisateurs au rôle pg_stat_scan_tables.

F.30.1. Fonctions

pgstattuple(regclass) returns record

pgstattuple renvoie la longueur physique d'une relation, le pourcentage des lignes « mortes », et d'autres informations. Ceci peut aider les utilisateurs à déterminer si une opération de VACUUM est nécessaire. L'argument est le nom de la relation cible (qui peut être qualifié par le nom du schéma) ou l'OID. Par exemple :

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
      

Les colonnes en sortie sont décrites dans Tableau F.22.

Tableau F.22. Colonnes de pgstattuple

ColonneTypeDescription
table_lenbigintLongueur physique de la relation en octets
tuple_countbigintNombre de lignes vivantes
tuple_lenbigintLongueur totale des lignes vivantes en octets
tuple_percentfloat8Pourcentage des lignes vivantes
dead_tuple_countbigintNombre de lignes mortes
dead_tuple_lenbigintLongueur totale des lignes mortes en octets
dead_tuple_percentfloat8Pourcentage des lignes mortes
free_spacebigintEspace libre total en octets
free_percentfloat8Pourcentage de l'espace libre

Note

La valeur de la colonne table_len sera toujours supérieure à la somme des colonnes tuple_len, dead_tuple_len et free_space. La différence correspond aux données systèmes comme la table de pointeurs vers les lignes (une table par bloc) et aux octets d'alignements permettant de s'assurer que les lignes sont correctement alignées.

pgstattuple acquiert seulement un verrou en lecture sur la relation. Les résultats ne reflètent donc pas une image instantanée, des mises à jour en parallèle pouvant en effet les affecter.

pgstattuple juge qu'une ligne est « morte » si HeapTupleSatisfiesDirty renvoie false.

pgstattuple(text) returns record

Identique à pgstattuple(regclass), sauf que la relation cible est désignée en tant que TEXT. Cette fonction est conservée pour raison de compatibilité ascendante, et sera dépréciée dans une prochaine version.

pgstatindex(regclass) returns record

pgstatindex renvoie un enregistrement affichant des informations sur un index B-Tree. Par exemple :

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
     

En voici les colonnes :

ColonneTypeDescription
versionintegerNuméro de version du B-tree
tree_levelintegerNiveau de l'arbre pour la page racine
index_sizebigintTaille totale de l'index en octets
root_block_nobigintEmplacement du bloc racine (0 si aucun)
internal_pagesbigintNombre de pages « internes » (niveau supérieur)
leaf_pagesbigintNombre de pages feuilles
empty_pagesbigintNombre de pages vides
deleted_pagesbigintNombre de pages supprimées
avg_leaf_densityfloat8Densité moyenne des pages feuilles
leaf_fragmentationfloat8Fragmentation des pages feuilles

L'information index_size rapportée correspondra normalement à un bloc de plus que ce qui est indiqué par la formule internal_pages + leaf_pages + empty_pages + deleted_pages car elle inclut aussi le bloc de méta-données de l'index.

Comme pour pgstattuple, les résultats sont accumulés page par page, et ne représentent pas forcément une image instantanée de l'index complet.

pgstatindex(text) returns record

Identique à pgstatindex(regclass), sauf que l'index cible est spécifié en tant que TEXT. Cette fonction est conservée pour raison de compatibilité ascendante, et sera dépréciée dans une prochaine version.

pgstatginindex(regclass) returns record

pgstatginindex renvoie un enregistrement montrant les informations sur un index GIN. Par exemple :

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

Les colonnes en sortie sont :

ColonneTypeDescription
versionintegerNuméro de version GIN
pending_pagesintegerNombre de pages dans la liste en attente
pending_tuplesbigintNombre de lignes dans la liste en attente

pgstathashindex(regclass) returns record

pgstathashindex retourne un enregistrement montrant des informations à propos d'un index HASH. Par exemple :

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
      

Les colonnes en sortie sont :

ColonneTypeDescription
versionintegerNuméro de version de HASH
bucket_pagesbigintNombre de pages bucket
overflow_pagesbigintNombre de pages overflow
bitmap_pagesbigintNombre de pages bitmap
unused_pagesbigintNombre de pages inutilisées
live_itemsbigintNombre de lignes vivantes
dead_tuplesbigintNombre de lignes mortes
free_percentfloatPourcentage d'espace libre

pg_relpages(regclass) returns bigint

pg_relpages renvoie le nombre de pages dans la relation.

pg_relpages(text) returns bigint

Identique à pg_relpages(regclass), sauf que la relation cible est spécifiée en tant que TEXT. Cette fonction est conservée pour raison de compatibilité ascendante, et sera dépréciée dans une prochaine version.

pgstattuple_approx(regclass) returns record

pgstattuple_approx est une alternative plus rapide à pgstattuple qui retourne des estimations. L'argument est le nom ou l'OID de la relation visée. Par exemple :

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
      

Les colonnes en sortie sont décrites dans Tableau F.23.

Alors que pgstattuple effectue toujours un parcours séquentiel complet de la table et renvoie un décompte exact des lignes vivantes et supprimées (et de leur taille) ainsi que de l'espace libre, pgstattuple_approx essaie d'éviter un parcours séquentiel complet et retourne un décompte exact des lignes supprimées avec une approximation du nombre de lignes et de la taille des lignes vivantes et de l'espace libre.

Il réalise ceci en sautant les pages qui n'ont que des lignes visibles selon la carte de visibilité (si une page a son bit positionné dans la carte de visibilité, elle est considérée comme ne possédant pas de lignes supprimées). Pour ces pages, il déduit l'espace libre correspondant à partir de la carte des espaces libres, et suppose que le reste de la page est occupé par des lignes vivantes.

Pour les pages qui ne sont pas sautées, il balaie chaque ligne, en enregistrant son existence et sa taille dans les compteurs correspondants, et ajoute l'espace libre de la page. À la fin, il estime le nombre de lignes vivantes en se basant sur le nombre de pages et de lignes visitées (de la même manière que VACUUM estime pg_class.reltuples).

Tableau F.23. Colonnes de pgstattuple_approx

ColonneTypeDescription
table_lenbigintLongueur physique de la relation en octets (exact)
scanned_percentfloat8Pourcentage parcouru de la table
approx_tuple_countbigintNombre de lignes vivantes (estimé)
approx_tuple_lenbigintLongueur totale des lignes vivantes en octets (estimé)
approx_tuple_percentfloat8Pourcentage des lignes vivantes
dead_tuple_countbigintNombre de lignes mortes (exact)
dead_tuple_lenbigintLongueur totale des lignes mortes en octets (exact)
dead_tuple_percentfloat8Pourcentage des lignes mortes
approx_free_spacebigintEspace libre total en octets (estimé)
approx_free_percentfloat8Pourcentage de l'espace libre

Dans la sortie ci-dessus, l'espace libre indiqué peut ne pas correspondre exactement à la sortie de pgstattuple car la carte des espaces libres donne un chiffre exact mais pas à l'octet près.

F.30.2. Auteurs

Tatsuo Ishii, Satoshi Nagayasu et Abhijit Menon-Sen