EXPLAIN

Nom

EXPLAIN -- affiche le plan d'exécution d'une instruction

Synopsis

EXPLAIN [ ANALYZE ] [ VERBOSE ] instruction

Description

Cette commande affiche le plan d'exécution que le planificateur PostgreSQL génère pour l'instruction fournie. Le plan d'exécution affiche comment le(s) table(s) référencée(s) par l'instruction seront parcourue(s) --- parcours séquentiel, parcours d'index, etc. --- et si plusieurs tables sont référencées, quels algorithmes de jointure seront utilisés pour amener la ligne requise à partir de chaque table en entrée.

La partie la plus critique de l'affichage est le coût d'exécution estimé de l'instruction, qui est l'impression que le planificateur a sur la durée que prendra l'exécution de l'instruction (mesuré en unité de récupération de pages disque). En fait, deux nombres sont affichés : le temps en exécution avant que la première ligne ne soit renvoyée et le temps total pour renvoyer toutes les lignes. Pour la plupart des requêtes, le temps total est ce qui importe mais dans des contextes telles qu'une sous-requête dans EXISTS, le planificateur choisira le plus petit temps de lancement plutôt que le plus petit temps total (car, de toute façon, l'exécuteur s'arrêtera après avoir récupéré une ligne). De même, si vous limitez le nombre de lignes à renvoyer avec une clause LIMIT, le planificateur fera une interpolation appropriée entre les coûts aux points finaux pour estimer le plan le moins cher.

L'option ANALYZE fait que l'instruction sera réellement exécutée, pas uniquement planifiée. Le temps total passé sur chaque nœud du plan (en millisecondes) et le nombre total de lignes renvoyées sont ajoutés à l'affichage. Ceci est utile pour voir si les estimations du planificateur sont proches de la réalité.

Important : Gardez en tête que l'instruction est réellement exécutée quand ANALYZE est utilisé. Bien que EXPLAIN annulera tout affichage qu'un SELECT renverrait, les autres effets immédiats de l'instruction auront lieu. Si vous souhaitez utiliser EXPLAIN ANALYZE sur une instruction INSERT, UPDATE, DELETE ou EXECUTE sans que la commande n'affecte vos données, utilisez cette approche :

BEGIN;
EXPLAIN ANALYZE ...;
ROLLBACK;

Paramètres

ANALYZE

Exécute la commande et affiche les temps d'exécution réels.

VERBOSE

Affiche la représentation interne complète du plan plutôt qu'un simple résumé. Utiliser cette option est seulement utile pour déboguer PostgreSQL. La sortie VERBOSE peut être joliment affichée, suivant le paramètre de configuration explain_pretty_print.

instruction

Toute instruction SELECT, INSERT, UPDATE, DELETE, EXECUTE ou DECLARE dont vous souhaitez voir le plan d'exécution.

Notes

La documentation sur l'utilisation de l'optimiseur des informations de coût est assez spartiate dans PostgreSQL. Référez-vous à Section 13.1 pour plus d'informations.

Pour permettre au planificateur de requêtes de PostgreSQL de prendre des décisions raisonnables lors de l'optimisation de requêtes, l'instruction ANALYZE devrait être exécutée pour enregistrer les statistiques sur la distribution des données à l'intérieur de la table. Si vous n'avez pas fait ceci (ou si la distribution statistique des données dans la table a changé significativement depuis la dernière exécution d'ANALYZE), les coûts estimés ne seront pas conformes aux réelles propriétés de la requête et, par conséquence, un plan de requête inférieur pourrait être choisi.

Avant PostgreSQL 7.3, le plan était émis sous la forme d'un message NOTICE. Maintenant, il apparaît comme le résultat d'une requête (formaté comme une table composée d'une seule colonne de type texte).

Exemples

Pour afficher le plan d'une simple requête sur une table avec une seule colonne de type integer et 10000 lignes :

EXPLAIN SELECT * FROM foo;

                       QUERY PLAN
---------------------------------------------------------
 Seq Scan on foo  (cost=0.00..155.00 rows=10000 width=4)
(1 row)

S'il existe un index et que nous utilisons une requête avec un condition WHERE indexable, EXPLAIN pourrait afficher un plan différent :

EXPLAIN SELECT * FROM foo WHERE i = 4;

                         QUERY PLAN
--------------------------------------------------------------
 Index Scan using fi on foo  (cost=0.00..5.98 rows=1 width=4)
   Index Cond: (i = 4)
(2 rows)

Et voici un exemple d'un plan de requête pour une requête utilisant une fonction d'agrégat :

EXPLAIN SELECT sum(i) FROM foo WHERE i < 10;

                             QUERY PLAN
---------------------------------------------------------------------
 Aggregate  (cost=23.93..23.93 rows=1 width=4)
   ->  Index Scan using fi on foo  (cost=0.00..23.92 rows=6 width=4)
         Index Cond: (i < 10)
(3 rows)

Voici un exemple d'utilisation de EXPLAIN EXECUTE pour afficher le plan d'exécution d'une requête préparée :

PREPARE query(int, int) AS SELECT sum(bar) FROM test
    WHERE id > $1 AND id < $2
    GROUP BY foo;

EXPLAIN ANALYZE EXECUTE query(100, 200);

                                                       QUERY PLAN
-------------------------------------------------------------------------------------------------------------------------
 HashAggregate  (cost=39.53..39.53 rows=1 width=8) (actual time=0.661..0.672 rows=7 loops=1)
   ->  Index Scan using test_pkey on test  (cost=0.00..32.97 rows=1311 width=8) (actual time=0.050..0.395 rows=99 loops=1)
         Index Cond: ((id > $1) AND (id < $2))
 Total runtime: 0.851 ms
(4 rows)

Bien sûr, les nombres spécifiques dépendent ici du contenu réel des tables impliquées. Notez aussi que les nombres, et même la stratégie de la requête sélectionnée, pourrait varier entre les versions de PostgreSQL à cause des améliorations du planificateur. De plus, la commande ANALYZE utilise une distribution aléatoire pour estimer les statistiques des données ; du coup, il est possible que les estimations de coût changent après un lancement d'ANALYZE, même si la distribution réelle des données n'a pas changé dans la table.

Compatibilité

Il n'existe pas d'instruction EXPLAIN définie dans le standard SQL.