Menu

PostgreSQL EXPLAIN ANALYZE : lire un plan d'exécution

EXPLAIN affiche le plan que PostgreSQL choisit pour une requête, et EXPLAIN ANALYZE exécute la requête et ajoute le nombre réel de lignes et le temps de chaque étape. Apprenez à lire l'arbre du plan et les noms de nœuds courants.

Cette page contient des éditeurs exécutables. Modifiez, exécutez et voyez la sortie instantanément.

EXPLAIN query affiche le plan que PostgreSQL choisit pour une requête : un arbre d'étapes (des nœuds) avec des coûts et des nombres de lignes estimés. EXPLAIN ANALYZE query exécute aussi la requête et ajoute le temps, les lignes et les boucles réels de chaque nœud. Lisez l'arbre en partant du nœud le plus indenté vers l'extérieur : les nœuds internes transmettent leurs lignes au nœud situé au-dessus.

Il n'y a pas d'index sur email, donc le plan est un Seq Scan : PostgreSQL lit chaque ligne et garde celles qui passent le Filter. Rows Removed by Filter montre le travail perdu. Les temps changent à chaque exécution ; la forme du plan compte plus que les chiffres.

Lire une ligne du plan

Chaque nœud affiche une ligne de cette forme :

Seq Scan on users  (cost=STARTUP..TOTAL rows=N width=W) (actual time=FIRST..LAST rows=N loops=L)
PartieSignification
cost=STARTUP..TOTALtravail estimé avant la première ligne, puis pour toutes les lignes, en unités du planificateur (pas en millisecondes)
rows (le premier)nombre estimé de lignes renvoyées par le nœud
widthtaille moyenne estimée d'une ligne, en octets
actual timemillisecondes jusqu'à la première ligne et jusqu'à la dernière, par boucle
rows (réel)lignes renvoyées, par boucle
loopsnombre d'exécutions du nœud ; multipliez le temps et les lignes par ce nombre

Les coûts d'un nœud parent incluent ceux de ses enfants. Planning Time et Execution Time, en bas, sont des totaux pour toute l'instruction.

Reconnaître les nœuds de plan courants

EXPLAIN (COSTS OFF) masque les chiffres, ce qui rend la forme du plan plus facile à voir :

Lisez depuis l'intérieur. Les deux tables sont parcourues et les clients filtrés vont dans un Hash. Le Hash Join le sonde avec chaque commande, et le GroupAggregate au sommet compte le résultat. Les nœuds que vous croiserez le plus :

NœudCe qu'il fait
Seq Scanlit toute la table
Index Scantrouve les lignes via un index, puis lit chaque ligne dans la table
Index Only Scanrépond depuis l'index sans visiter la table
Bitmap Index Scan + Bitmap Heap Scancollecte dans un index l'emplacement des lignes qui correspondent, puis les lit dans l'ordre de la table
Nested Looppour chaque ligne externe, cherche les correspondances dans l'entrée interne ; efficace quand le côté externe est petit
Hash Join + Hashconstruit une table de hachage à partir d'une entrée, puis la sonde avec l'autre
Merge Joinjoint deux entrées déjà triées sur la clé de jointure
Sort, Incremental Sorttrie les lignes pour ORDER BY, DISTINCT ou une jointure par fusion
HashAggregate, GroupAggregateGROUP BY avec une table de hachage, ou sur une entrée triée
Limits'arrête après N lignes
Gatherrassemble les lignes des workers parallèles

Repérer les mauvaises estimations de lignes

La vérification la plus utile dans EXPLAIN ANALYZE consiste à comparer les rows estimées aux rows réelles d'un même nœud. Quand elles sont très éloignées, le planificateur a choisi son plan à partir de mauvais chiffres, souvent parce que les statistiques manquent ou sont périmées :

Le parcours renvoie 10 lignes réelles, mais l'estimation est bien plus haute, car la table n'a pas encore été analysée. Ajoutez ANALYZE tasks; avant l'EXPLAIN et l'estimation se rapproche de 10. L'autovacuum analyse les tables en arrière-plan, mais lancez ANALYZE vous-même après un chargement massif (voir VACUUM et autovacuum).

Expliquer une modification sans la garder

EXPLAIN ANALYZE exécute l'instruction, donc un UPDATE ou un DELETE modifie des lignes. Placez-le dans une transaction et annulez-la :

Les 1000 lignes sont toujours là après le rollback.

Afficher les E/S avec BUFFERS et d'autres options

EXPLAIN (ANALYZE, BUFFERS) SELECT ...;        -- pages read from cache (hit) and disk (read)
EXPLAIN (ANALYZE, BUFFERS, SETTINGS) SELECT ...; -- also list changed planner settings
EXPLAIN (FORMAT JSON) SELECT ...;              -- machine-readable, for plan visualizers
EXPLAIN (ANALYZE, TIMING OFF) SELECT ...;      -- row counts without per-node timing overhead

BUFFERS affiche les E/S : un nœud avec beaucoup de pages read est allé sur le disque. PostgreSQL 17 a ajouté SERIALIZE (le coût de conversion des lignes de sortie en texte) et MEMORY (la mémoire du planificateur). Le guide officiel d'EXPLAIN détaille d'autres plans.

Tester un plan avec les paramètres du planificateur

Pour voir le plan que PostgreSQL utiliserait sans une méthode donnée, désactivez cette méthode pour votre session. Faites-le uniquement pour des expériences, jamais dans du code de production :

Avec 100 lignes, le planificateur préfère un Seq Scan ; avec enable_seqscan = off, le plan affiche Index Scan using items_pkey. Comparez les deux temps d'EXPLAIN ANALYZE pour voir si l'index aide. RESET enable_seqscan; rétablit la valeur par défaut.

Questions fréquentes

Quelle différence entre EXPLAIN et EXPLAIN ANALYZE ?

EXPLAIN planifie seulement la requête et affiche des estimations. EXPLAIN ANALYZE l'exécute aussi et ajoute le temps réel, le nombre de lignes et le nombre de boucles de chaque nœud, donc il prend autant de temps que la requête elle-même.

Que signifie cost dans un plan PostgreSQL ?

Le coût est l'estimation du planificateur dans une unité arbitraire, calibrée pour que la lecture séquentielle d'une page coûte 1 (seq_page_cost). Il sert à comparer les plans d'une même requête, pas à mesurer un temps en millisecondes.

EXPLAIN ANALYZE modifie-t-il les données ?

Oui, pour INSERT, UPDATE, DELETE et MERGE, il effectue la modification. Lancez-le entre BEGIN et ROLLBACK pour mesurer sans garder le résultat.

Pourquoi un Seq Scan est-il choisi alors qu'un index existe ?

Parce que le planificateur l'estime moins coûteux : la table est petite, la requête renvoie une grande part des lignes, ou la condition ne peut pas utiliser l'index. Des statistiques périmées peuvent aussi le tromper, ce que ANALYZE corrige.

Illustration des langages de programmation de Coddy

Apprendre à coder avec Coddy

Commencer