Documentation PostgreSQL 15.15 » Annexes » Modules supplémentaires fournis » pgstattuple

Précédent | Niveau supérieur | Suivant
F.32. pg_stat_statements | Sommaire | F.34. pg_surgery

## F.33. 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.33.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`

  Colonne | Type | Description
  --- | --- | ---
  `table_len` | `bigint` | Longueur physique de la relation en octets
  `tuple_count` | `bigint` | Nombre de lignes vivantes
  `tuple_len` | `bigint` | Longueur totale des lignes vivantes en octets
  `tuple_percent` | `float8` | Pourcentage des lignes vivantes
  `dead_tuple_count` | `bigint` | Nombre de lignes mortes
  `dead_tuple_len` | `bigint` | Longueur totale des lignes mortes en octets
  `dead_tuple_percent` | `float8` | Pourcentage des lignes mortes
  `free_space` | `bigint` | Espace libre total en octets
  `free_percent` | `float8` | Pourcentage 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 :

  Colonne | Type | Description
  --- | --- | ---
  `version` | `integer` | Numéro de version du B-tree
  `tree_level` | `integer` | Niveau de l'arbre pour la page racine
  `index_size` | `bigint` | Taille totale de l'index en octets
  `root_block_no` | `bigint` | Emplacement du bloc racine (0 si aucun)
  `internal_pages` | `bigint` | Nombre de pages « internes » (niveau supérieur)
  `leaf_pages` | `bigint` | Nombre de pages feuilles
  `empty_pages` | `bigint` | Nombre de pages vides
  `deleted_pages` | `bigint` | Nombre de pages supprimées
  `avg_leaf_density` | `float8` | Densité moyenne des pages feuilles
  `leaf_fragmentation` | `float8` | Fragmentation 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 :

  Colonne | Type | Description
  --- | --- | ---
  `version` | `integer` | Numéro de version GIN
  `pending_pages` | `integer` | Nombre de pages dans la liste en attente
  `pending_tuples` | `bigint` | Nombre 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 :

  Colonne | Type | Description
  --- | --- | ---
  `version` | `integer` | Numéro de version de HASH
  `bucket_pages` | `bigint` | Nombre de pages bucket
  `overflow_pages` | `bigint` | Nombre de pages overflow
  `bitmap_pages` | `bigint` | Nombre de pages bitmap
  `unused_pages` | `bigint` | Nombre de pages inutilisées
  `live_items` | `bigint` | Nombre de lignes vivantes
  `dead_tuples` | `bigint` | Nombre de lignes mortes
  `free_percent` | `float` | Pourcentage 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`

  Colonne | Type | Description
  --- | --- | ---
  `table_len` | `bigint` | Longueur physique de la relation en octets (exact)
  `scanned_percent` | `float8` | Pourcentage parcouru de la table
  `approx_tuple_count` | `bigint` | Nombre de lignes vivantes (estimé)
  `approx_tuple_len` | `bigint` | Longueur totale des lignes vivantes en octets (estimé)
  `approx_tuple_percent` | `float8` | Pourcentage des lignes vivantes
  `dead_tuple_count` | `bigint` | Nombre de lignes mortes (exact)
  `dead_tuple_len` | `bigint` | Longueur totale des lignes mortes en octets (exact)
  `dead_tuple_percent` | `float8` | Pourcentage des lignes mortes
  `approx_free_space` | `bigint` | Espace libre total en octets (estimé)
  `approx_free_percent` | `float8` | Pourcentage 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.33.2. Auteurs

Tatsuo Ishii, Satoshi Nagayasu et Abhijit Menon-Sen