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)
| Partie | Signification |
|---|---|
cost=STARTUP..TOTAL | travail 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 |
width | taille moyenne estimée d'une ligne, en octets |
actual time | millisecondes jusqu'à la première ligne et jusqu'à la dernière, par boucle |
rows (réel) | lignes renvoyées, par boucle |
loops | nombre 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œud | Ce qu'il fait |
|---|---|
Seq Scan | lit toute la table |
Index Scan | trouve les lignes via un index, puis lit chaque ligne dans la table |
Index Only Scan | répond depuis l'index sans visiter la table |
Bitmap Index Scan + Bitmap Heap Scan | collecte dans un index l'emplacement des lignes qui correspondent, puis les lit dans l'ordre de la table |
Nested Loop | pour chaque ligne externe, cherche les correspondances dans l'entrée interne ; efficace quand le côté externe est petit |
Hash Join + Hash | construit une table de hachage à partir d'une entrée, puis la sonde avec l'autre |
Merge Join | joint deux entrées déjà triées sur la clé de jointure |
Sort, Incremental Sort | trie les lignes pour ORDER BY, DISTINCT ou une jointure par fusion |
HashAggregate, GroupAggregate | GROUP BY avec une table de hachage, ou sur une entrée triée |
Limit | s'arrête après N lignes |
Gather | rassemble 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.