Menu

EXPLAIN ANALYZE en PostgreSQL: cómo leer un plan

EXPLAIN muestra el plan que PostgreSQL elige para una consulta, y EXPLAIN ANALYZE ejecuta la consulta y añade las filas y los tiempos reales de cada paso. Aprende a leer el árbol del plan y los nodos más comunes.

Esta página incluye editores ejecutables: edita, ejecuta y ve el resultado al instante.

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)
ParteSignificado
cost=STARTUP..TOTALtrabajo 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
widthtamaño medio estimado de la fila en bytes
actual timemilisegundos hasta la primera fila y hasta la última, por bucle
rows (el real)filas devueltas, por bucle
loopscuá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:

NodoQué hace
Seq Scanlee la tabla entera
Index Scanencuentra filas mediante un índice y después lee cada fila de la tabla
Index Only Scanresponde desde el índice sin visitar la tabla
Bitmap Index Scan + Bitmap Heap Scanreúne desde un índice la ubicación de las filas que coinciden y luego las lee en el orden de la tabla
Nested Looppor cada fila externa busca coincidencias en la entrada interna; va bien cuando el lado externo es pequeño
Hash Join + Hashconstruye una tabla hash con una entrada y la consulta con la otra
Merge Joinune dos entradas ya ordenadas por la clave del join
Sort, Incremental Sortordena filas para ORDER BY, DISTINCT o un merge join
HashAggregate, GroupAggregateGROUP BY con una tabla hash, o sobre una entrada ordenada
Limitse detiene tras N filas
Gatherreú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.

Ilustración de los lenguajes de programación de Coddy

Aprende a programar con Coddy

Comenzar