EXPLAIN query muestra el plan que PostgreSQL elige para una consulta: un árbol de pasos (nodos) con costes y número de filas estimados. EXPLAIN ANALYZE query además ejecuta la consulta y añade el tiempo, las filas y los bucles reales de cada nodo. Lee el árbol desde el nodo más indentado hacia fuera: los nodos internos pasan sus filas al nodo de arriba.
No hay índice en email, así que el plan es un Seq Scan: PostgreSQL lee todas las filas y se queda con las que pasan el Filter. Rows Removed by Filter muestra el trabajo desperdiciado. Los tiempos cambian en cada ejecución; importa más la forma del plan que los números.
Leer una línea del plan
Cada nodo imprime una línea con esta forma:
Seq Scan on users (cost=STARTUP..TOTAL rows=N width=W) (actual time=FIRST..LAST rows=N loops=L)
| Parte | Significado |
|---|---|
cost=STARTUP..TOTAL | trabajo estimado antes de la primera fila y para todas las filas, en unidades del planificador (no milisegundos) |
rows (el primero) | número estimado de filas que devuelve el nodo |
width | tamaño medio estimado de la fila en bytes |
actual time | milisegundos hasta la primera fila y hasta la última, por bucle |
rows (el real) | filas devueltas, por bucle |
loops | cuántas veces se ejecutó el nodo; multiplica por él el tiempo y las filas |
Los costes de un nodo padre incluyen los de sus hijos. Planning Time y Execution Time, al final, son los totales de toda la sentencia.
Reconocer los nodos más comunes
EXPLAIN (COSTS OFF) oculta los números, así se ve mejor la forma del plan:
Lee desde dentro. Se recorren las dos tablas y los clientes filtrados van a un Hash. El Hash Join lo consulta con cada pedido, y el GroupAggregate de arriba cuenta el resultado. Los nodos que más vas a ver:
| Nodo | Qué hace |
|---|---|
Seq Scan | lee la tabla entera |
Index Scan | encuentra filas mediante un índice y después lee cada fila de la tabla |
Index Only Scan | responde desde el índice sin visitar la tabla |
Bitmap Index Scan + Bitmap Heap Scan | reúne desde un índice la ubicación de las filas que coinciden y luego las lee en el orden de la tabla |
Nested Loop | por cada fila externa busca coincidencias en la entrada interna; va bien cuando el lado externo es pequeño |
Hash Join + Hash | construye una tabla hash con una entrada y la consulta con la otra |
Merge Join | une dos entradas ya ordenadas por la clave del join |
Sort, Incremental Sort | ordena filas para ORDER BY, DISTINCT o un merge join |
HashAggregate, GroupAggregate | GROUP BY con una tabla hash, o sobre una entrada ordenada |
Limit | se detiene tras N filas |
Gather | reúne filas de los procesos paralelos |
Detectar estimaciones de filas erróneas
La comprobación más útil en EXPLAIN ANALYZE es comparar las rows estimadas con las rows reales en el mismo nodo. Cuando están muy lejos, el planificador eligió su plan con números equivocados, a menudo porque faltan estadísticas o están desactualizadas:
El scan devuelve 10 filas reales, pero la estimación es mucho mayor porque la tabla todavía no se ha analizado. Añade ANALYZE tasks; antes del EXPLAIN y la estimación se acerca a 10. Autovacuum analiza las tablas en segundo plano, pero ejecuta ANALYZE tú mismo después de una carga masiva (ver VACUUM y autovacuum).
Explicar un cambio de datos sin conservarlo
EXPLAIN ANALYZE ejecuta la sentencia, así que un UPDATE o un DELETE cambia filas. Envuélvelo en una transacción y haz rollback:
Las 1000 filas siguen ahí después del rollback.
Ver la E/S con BUFFERS y otras opciones
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 muestra la E/S: un nodo con muchas páginas read fue a disco. PostgreSQL 17 añadió SERIALIZE (el coste de convertir las filas de salida a texto) y MEMORY (la memoria del planificador). La guía oficial de EXPLAIN recorre más planes.
Probar un plan con ajustes del planificador
Para ver qué plan usaría PostgreSQL sin un método concreto, desactiva ese método en tu sesión. Hazlo solo en pruebas, nunca en código de producción:
Con 100 filas el planificador prefiere un Seq Scan; con enable_seqscan = off el plan muestra Index Scan using items_pkey. Compara los tiempos de los dos EXPLAIN ANALYZE para ver si el índice ayuda. RESET enable_seqscan; vuelve al valor por defecto.
Preguntas frecuentes
¿Qué diferencia hay entre EXPLAIN y EXPLAIN ANALYZE?
EXPLAIN solo planifica la consulta y muestra estimaciones. EXPLAIN ANALYZE además la ejecuta y añade el tiempo, las filas y el número de bucles reales de cada nodo, así que tarda lo mismo que la consulta.
¿Qué significa cost en un plan de PostgreSQL?
Cost es la estimación del planificador en unidades arbitrarias, escaladas para que leer una página de forma secuencial cueste 1 (seq_page_cost). Sirve para comparar planes de la misma consulta, no como un tiempo en milisegundos.
¿EXPLAIN ANALYZE modifica datos?
Sí, con INSERT, UPDATE, DELETE y MERGE hace el cambio. Ejecútalo entre BEGIN y ROLLBACK para medir sin conservar el resultado.
¿Por qué elige un Seq Scan si existe un índice?
Porque el planificador estima que es más barato: la tabla es pequeña, la consulta devuelve una gran parte de las filas o la condición no puede usar el índice. Las estadísticas desactualizadas también pueden engañarlo, y ANALYZE lo corrige.