Conceptos básicos de EXPLAIN

EXPLAIN muestra la ruta de acceso elegida por el planificador antes de que incurras en el coste de ejecutar una consulta. EXPLAIN (ANALYZE, BUFFERS) ejecuta la consulta y añade tiempos y E/S de búfer para que puedas ver lo que realmente sucedió en PostgreSQL 18.4.

Receta

Tarjeta de referencia rápida - lista para copiar y pegar.

EXPLAIN (ANALYZE, BUFFERS, VERBOSE, SETTINGS, WAL)
SELECT o.id, o.total
FROM orders o
WHERE o.status = 'shipped'
  AND o.created_at >= now() - interval '7 days';

Cuándo usar esto: Cualquier consulta lenta o sorprendente en un conjunto de datos similar a producción. Captura el plan antes y después de cambios en índices o estadísticas.

Ejemplo de trabajo

CREATE TABLE orders (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  customer_id bigint NOT NULL,
  status text NOT NULL DEFAULT 'pending',
  created_at timestamptz NOT NULL DEFAULT now(),
  total numeric(12,2) NOT NULL
);
 
CREATE INDEX orders_status_created_idx ON orders (status, created_at);
 
INSERT INTO orders (customer_id, status, created_at, total)
SELECT
  (random() * 10000)::bigint,
  CASE WHEN random() < 0.05 THEN 'shipped' ELSE 'pending' END,
  now() - (random() * interval '90 days'),
  (random() * 500)::numeric(12,2)
FROM generate_series(1, 200000);
 
ANALYZE orders;
 
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT id, total
FROM orders
WHERE status = 'shipped'
  AND created_at >= now() - interval '7 days';

Un plan saludable a menudo muestra Index Scan en orders_status_created_idx con bajos rows removed by filter y modestos recuentos de shared hit.

Lo que esto demuestra:

• ANALYZE antes de comparar planes
• Lectura del tipo de escaneo y nombre del índice
• Interpretación de actual time y rows frente a las estimaciones del planificador
• Uso de BUFFERS para detectar fallos en la caché

Profundización

Cómo funciona

• El planificador construye un árbol de nodos (escaneo, unión, ordenación, agregación). Cada nodo tiene recuentos de filas estimados y reales.
• EXPLAIN por sí solo es barato y seguro en producción. ANALYZE ejecuta la consulta, así que úsalo en staging o con salvaguardas LIMIT en sentencias destructivas.
• BUFFERS informa shared hit (caché) y shared read (disco). Un alto read en una consulta frecuente significa que más RAM o mejores índices pueden ayudar.
• SETTINGS (PostgreSQL 12+) muestra GUCs no predeterminados que influyeron en el plan, útil cuando random_page_cost o work_mem difieren por rol.

Opciones de EXPLAIN de un vistazo

Notas SQL

-- Guardar un plan para un ticket (sin ejecución)
EXPLAIN (FORMAT JSON)
SELECT count(*) FROM orders WHERE status = 'pending';
 
-- Comparar solo estimaciones (seguro en producción)
EXPLAIN (VERBOSE)
SELECT * FROM orders WHERE customer_id = 42;

Errores comunes

• Ejecutar EXPLAIN ANALYZE en DELETE/UPDATE sin cuidado - Modificas datos de producción. Solución: Envuelve en una transacción y ROLLBACK, o prueba en una instantánea.
• Confiar en números de caché fría una vez - La primera ejecución después de un reinicio parece peor que el estado estable. Solución: Ejecuta dos veces; compara el segundo resultado de ANALYZE.
• Ignorar la deriva de la estimación de filas - rows=1000 vs actual rows=85000 indica estadísticas incorrectas o predicados correlacionados. Solución: ANALYZE y comprueba estadísticas extendidas.
• Leer solo el tiempo total - Un nodo externo barato puede ocultar un costoso bucle anidado en su interior. Solución: Encuentra el nodo con la mayor parte del actual time.
• Olvidar search_path - Los planes difieren cuando la cualificación del esquema cambia. Solución: Establece search_path explícitamente en la sesión que captures.

Alternativas

Preguntas frecuentes

Relacionado

• Seq Scan vs Index Scan - Cuándo gana cada escaneo
• Nested Loop, Hash Join, Merge Join - Nodos de unión en planes
• Estudios de caso de planes incorrectos - Patrones reales de estimaciones erróneas
• Conceptos básicos de estadísticas - Por qué las estimaciones salen mal

Versiones de pila: Esta página fue escrita para PostgreSQL 18.4 (estable 18, mantenimiento 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x y PostGIS 3.5+.