EXPLAIN ANALYZE para humanos: leer un plan de PostgreSQL sin sufrir

󰃭 2026-11-04 · 18 min de lectura

Contenido

Hay una pregunta que todos hemos hecho alguna vez, normalmente con cara de funeral: «el índice existe, ¿por qué PostgreSQL pasa de él?».

Mira estas dos consultas sobre la misma tabla de un millón de filas. Devuelven exactamente las mismas 726 filas:

-- Consulta A
Seq Scan on pedidos  (cost=0.00..24853.00 rows=5000 width=27) (actual time=0.104..459.164 rows=726 loops=1)
Execution Time: 459.294 ms

-- Consulta B
Bitmap Heap Scan on pedidos  (cost=9.94..2118.47 rows=712 width=27) (actual time=0.235..1.202 rows=726 loops=1)
Execution Time: 1.272 ms

459 milisegundos frente a 1,2. La diferencia entre una y otra es una sola línea de SQL, y está justo ahí, en el plan. Al final de la entrada vuelvo a ellas. Antes toca aprender a leer lo que PostgreSQL nos cuenta, que parece un volcado ilegible pero se lee con cuatro reglas.

Todo lo que ves aquí sale de un laboratorio que puedes reproducir en tu máquina. Las salidas están capturadas con PostgreSQL 16.15; más abajo cuento qué cambia en versiones más nuevas.

El laboratorio #

Tres tablas sintéticas, generadas con generate_series() y random(), para no descargar nada:

TablaFilasTamaño total
clientes10 0001,3 MB
pedidos1 000 00079 MB
lineas_pedido3 000 000261 MB

Cada pedido tiene exactamente 3 líneas y cada cliente unos 100 pedidos. El 90 % de los pedidos están en estado entregado y sólo el 0,5 % en devuelto; lo usaremos a propósito. Además, provincia, municipio y codigo_postal de los clientes están fuertemente correlacionados, y eso también tiene su historia.

El código está en el repositorio público de laboratorios, en la carpeta lab-explain/, autosuficiente como las de las otras series. Con Podman:

ignacio@zeus:~$ git clone https://codeberg.org/igalvan/blog-public-code.git
ignacio@zeus:~$ cd blog-public-code/lab-explain
ignacio@zeus:~/blog-public-code/lab-explain$ ./lab.sh up      # PostgreSQL en un contenedor
ignacio@zeus:~/blog-public-code/lab-explain$ ./lab.sh init    # crea y carga las tablas (~20 s)
ignacio@zeus:~/blog-public-code/lab-explain$ ./lab.sh run      # ejecuta las consultas

./lab.sh run guarda cada salida en salidas/. Si prefieres usar un PostgreSQL que ya tengas instalado, basta con definir PSQL_CMD (el README lo explica).

Una decisión de laboratorio: todas las consultas empiezan con SET max_parallel_workers_per_gather = 0; y SET jit = off;. El paralelismo añade nodos Gather y Workers que son muy interesantes, pero estorban cuando estás aprendiendo a leer. En producción lo normal es tenerlos activados.

EXPLAIN y EXPLAIN ANALYZE no son lo mismo #

  • EXPLAIN consulta estima: muestra el plan que PostgreSQL elegiría y lo que cree que va a costar, sin ejecutar nada.
  • EXPLAIN ANALYZE consulta ejecuta de verdad la consulta y añade lo que pasó realmente: tiempos y filas reales.
  • EXPLAIN (ANALYZE, BUFFERS) consulta añade cuántas páginas de memoria o disco tocó cada nodo. Es la forma que uso casi siempre.

Un aviso que conviene tatuarse: como ANALYZE ejecuta la consulta, con un UPDATE, DELETE o INSERT modifica los datos. Si quieres ver el plan sin consecuencias:

BEGIN;
EXPLAIN (ANALYZE, BUFFERS) UPDATE pedidos SET estado = 'enviado' WHERE id = 1;
ROLLBACK;

Regla 1: el plan es un árbol y se lee de dentro hacia fuera #

Cada línea con -> es un nodo. Los nodos más indentados se ejecutan primero y pasan sus filas al nodo de encima. Este es el plan de una unión sencilla, recortado:

Nested Loop  (cost=5.49..380.77 rows=100 width=22) (actual time=0.075..0.299 rows=103 loops=1)
  ->  Index Scan using clientes_pkey on clientes c  (cost=0.29..8.30 rows=1 width=16) (actual time=0.026..0.027 rows=1 loops=1)
        Index Cond: (id = 4242)
  ->  Bitmap Heap Scan on pedidos p  (cost=5.20..371.46 rows=100 width=14) (actual time=0.043..0.254 rows=103 loops=1)
        Recheck Cond: (cliente_id = 4242)
        ->  Bitmap Index Scan on idx_pedidos_cliente  (cost=0.00..5.17 rows=100 width=0) (actual time=0.024..0.024 rows=103 loops=1)
              Index Cond: (cliente_id = 4242)
Execution Time: 0.400 ms

Primero se busca el cliente por clave primaria, luego se buscan sus pedidos con el índice de cliente_id, y arriba el Nested Loop los combina.

Y cada nodo trae dos paréntesis con casi el mismo formato:

(cost=5.20..371.46 rows=100 width=14)              <- lo que PostgreSQL ESTIMA
(actual time=0.043..0.254 rows=103 loops=1)        <- lo que PASÓ DE VERDAD
  • cost=arranque..total: coste estimado en unidades arbitrarias. El primer número es lo que cuesta producir la primera fila; el segundo, la última. No son milisegundos: es una moneda interna que sirve para comparar planes.
  • rows: filas que se estiman (o que salieron de verdad, en el segundo paréntesis).
  • width: ancho medio de la fila, en bytes.
  • actual time=arranque..total: milisegundos reales, por cada vuelta.
  • loops: cuántas veces se ejecutó este nodo.

Esa última pareja es la trampa más habitual y nos lleva a la regla 2.

Regla 2: el tiempo real es por vuelta, multiplica por loops #

Esta unión devuelve los pedidos de todos los clientes de un municipio:

Nested Loop  (cost=5.13..15440.31 rows=5400 width=22) (actual time=0.070..29.251 rows=5425 loops=1)
  ->  Seq Scan on clientes c  (cost=0.00..259.00 rows=54 width=16) (actual time=0.027..1.476 rows=54 loops=1)
        Filter: (municipio = 'Municipio 7'::text)
        Rows Removed by Filter: 9946
  ->  Bitmap Heap Scan on pedidos p  (cost=5.13..280.13 rows=101 width=14) (actual time=0.026..0.496 rows=100 loops=54)
        Recheck Cond: (c.id = cliente_id)
        ->  Bitmap Index Scan on idx_pedidos_cliente  (cost=0.00..5.11 rows=101 width=0) (actual time=0.011..0.011 rows=100 loops=54)
              Index Cond: (cliente_id = c.id)
Execution Time: 29.613 ms

Mira el nodo Bitmap Heap Scan on pedidos: actual time=0.026..0.496, parece que medio milisegundo. Pero tiene loops=54: se ejecutó 54 veces, una por cada cliente del municipio. 0,496 ms × 54 ≈ 27 ms, casi todo el tiempo de la consulta (29,6 ms). Si no multiplicas, te vas a poner a optimizar el nodo equivocado.

Un detalle más: cuando loops es mayor que 1, rows es la media por vuelta (100 filas × 54 vueltas ≈ las 5 425 del nodo de arriba).

Para ver que los costes no son magia, tomemos el Seq Scan de más abajo (cost=0.00..19853.00). La tabla pedidos ocupa 7 353 páginas y tiene 1 000 000 de filas. Con los parámetros por defecto, leer una página secuencialmente cuesta 1, procesar una fila 0,01 y evaluar una condición 0,0025:

7353 × 1  +  1 000 000 × 0,01  +  1 000 000 × 0,0025  =  19 853

Cuadra exactamente. Un plan es aritmética, no un oráculo.

Regla 3: cómo accede a los datos #

Probemos con la consulta SELECT * FROM pedidos WHERE cliente_id = 4242, en varias situaciones.

Seq Scan. Sin índice sobre cliente_id, no hay otra opción que leer la tabla entera:

Seq Scan on pedidos  (cost=0.00..19853.00 rows=100 width=27) (actual time=5.110..63.057 rows=103 loops=1)
  Filter: (cliente_id = 4242)
  Rows Removed by Filter: 999897
  Buffers: shared read=7353
Execution Time: 63.135 ms

La línea clave es Rows Removed by Filter: 999897: leyó un millón de filas para quedarse con 103.

Bitmap Heap Scan. Con un índice sobre cliente_id:

Bitmap Heap Scan on pedidos  (cost=5.20..371.46 rows=100 width=27) (actual time=0.071..0.700 rows=103 loops=1)
  Recheck Cond: (cliente_id = 4242)
  Heap Blocks: exact=102
  ->  Bitmap Index Scan on idx_pedidos_cliente  (cost=0.00..5.17 rows=100 width=0) (actual time=0.048..0.048 rows=103 loops=1)
        Index Cond: (cliente_id = 4242)
Execution Time: 0.728 ms

De 63 ms a 0,7 ms. Primero se recorre el índice y se construye un «mapa» de qué páginas de la tabla contienen filas buscadas (Bitmap Index Scan); luego se leen esas 102 páginas una sola vez y en orden (Bitmap Heap Scan). Es la elección típica cuando salen unas decenas o cientos de filas dispersas por la tabla.

Index Scan. Para una sola fila por clave primaria, PostgreSQL va y vuelve por el índice sin mapa intermedio:

Index Scan using pedidos_pkey on pedidos  (cost=0.42..8.44 rows=1 width=27) (actual time=0.042..0.042 rows=1 loops=1)
  Index Cond: (id = 777777)
Execution Time: 0.052 ms

Index Only Scan. Si sólo pides columnas que están en el propio índice, ni siquiera toca la tabla:

Index Only Scan using idx_pedidos_cliente on pedidos  (cost=0.42..6.17 rows=100 width=4) (actual time=0.011..0.018 rows=103 loops=1)
  Index Cond: (cliente_id = 4242)
  Heap Fetches: 0
Execution Time: 0.031 ms

Ojo con Heap Fetches: 0. Un Index Only Scan necesita que el mapa de visibilidad de la tabla esté al día, algo que mantiene VACUUM. Si Heap Fetches es alto, el «only» es mentira: está yendo a la tabla igualmente. En el laboratorio hago un VACUUM pedidos; justo antes para que salga limpio.

El mito del Seq Scan malo. Cuando la condición se lleva casi media tabla:

Seq Scan on pedidos  (cost=0.00..22353.00 rows=598275 width=27) (actual time=0.011..83.618 rows=599873 loops=1)
  Filter: ((cliente_id >= 1) AND (cliente_id <= 6000))
Execution Time: 108.245 ms

Aquí PostgreSQL tiene el índice a mano y decide no usarlo, y hace bien: para devolver el 60 % de la tabla, leerla de principio a fin es más barato que saltar del índice a la tabla seiscientas mil veces. Un Seq Scan no es un fallo: es la herramienta correcta cuando se devuelve mucha parte de la tabla (o la tabla es diminuta).

(Con un 30 % de la tabla, por cierto, PostgreSQL seguía eligiendo Bitmap Heap Scan. El punto de cruce depende de los datos; lo que importa es que lo calcula él y que puedes comprobarlo en el plan.)

Regla 3, segunda parte: cómo une tablas #

Los tres algoritmos de unión que vas a ver siempre son estos, y PostgreSQL elige según cuántas filas cree que entran.

Nested Loop (bucle anidado): para cada fila de la tabla externa busca en la interna. Ideal con pocas filas externas y un índice en la interna. Es lo que vimos en la regla 2.

Hash Join: construye una tabla hash con la tabla más pequeña y recorre la grande una sola vez consultándola. Es el rey cuando se unen muchas filas. Aquí, todos los clientes contra todos los pedidos:

HashAggregate  (cost=27838.11..27838.21 rows=8 width=52) (actual time=533.080..533.087 rows=8 loops=1)
  ->  Hash Join  (cost=359.00..20338.11 rows=1000000 width=18) (actual time=2.681..341.616 rows=1000000 loops=1)
        Hash Cond: (p.cliente_id = c.id)
        ->  Seq Scan on pedidos p  (cost=0.00..17353.00 rows=1000000 width=10) (actual time=0.006..128.027 rows=1000000 loops=1)
        ->  Hash  (cost=234.00..234.00 rows=10000 width=16) (actual time=2.593..2.595 rows=10000 loops=1)
              Buckets: 16384  Batches: 1  Memory Usage: 597kB
              ->  Seq Scan on clientes c  (cost=0.00..234.00 rows=10000 width=16) (actual time=0.003..0.890 rows=10000 loops=1)
Execution Time: 533.194 ms

Se construye el hash con los 10 000 clientes (597 kB) y se recorren los pedidos una vez. Fíjate en Batches: 1: significa que el hash cabió en memoria (work_mem). Si ves Batches mayor que 1, el hash se ha desbordado a disco y la unión se vuelve bastante más lenta.

Merge Join: une dos entradas ya ordenadas por la clave de unión, avanzando en paralelo por ambas. Es una buena opción cuando las dos entradas vienen ordenadas «gratis», por ejemplo desde índices.

Una forma muy instructiva de aprender es forzar a PostgreSQL a elegir otro algoritmo y comparar. En el laboratorio lo hago con SET enable_hashjoin = off; y compañía (sólo para experimentar, nunca como solución en producción). La misma consulta, tres algoritmos:

AlgoritmoCoste estimadoTiempo real
Hash Join (elección de PostgreSQL)27 838533 ms
Nested Loop (con Memoize)52 868664 ms
Merge Join68 320887 ms

El orden de los costes estimados coincide con el de los tiempos reales. Cuando eso pasa, el planificador está bien informado. Cuando no, mira la regla 4.

El Nested Loop merece una mención: PostgreSQL 14 y posteriores colocan un nodo Memoize delante del índice interno, que recuerda resultados ya buscados:

->  Memoize  (cost=0.30..0.31 rows=1 width=16) (actual time=0.000..0.000 rows=1 loops=1000000)
      Cache Key: p.cliente_id
      Hits: 990000  Misses: 10000  Evictions: 0  Overflows: 0  Memory Usage: 1133kB

Un millón de vueltas, 990 000 aciertos de caché y sólo 10 000 búsquedas reales en el índice. Por eso un Nested Loop sobre un millón de filas no salió catastrófico. Mira el loops=1000000 y recuerda la regla 2.

El Merge Join, por su parte, necesita las dos entradas ordenadas. Aquí las obtiene de dos Index Scan, y el de pedidos salta de una página a otra de la tabla siguiendo el índice, lo que se nota en los casi un millón de accesos a buffers (shared hit=990160).

Regla 4: compara siempre estimado y real #

Esta es la regla que más tiempo me ha ahorrado. En cada nodo tienes el rows= que PostgreSQL esperaba y el rows= que salió. Si difieren en uno o dos órdenes de magnitud, el problema no es el índice ni el algoritmo: es que el planificador decide a ciegas con información equivocada.

Un ejemplo con tres filtros sobre clientes (provincia, municipio y código postal):

Seq Scan on clientes  (cost=0.00..309.00 rows=1 width=74) (actual time=0.015..0.749 rows=23 loops=1)
  Filter: ((provincia = 'Provincia 1'::text) AND (municipio = 'Municipio 7'::text) AND (codigo_postal = '00070'::text))
  Rows Removed by Filter: 9977

Estimó 1 fila, salieron 23. Por qué: PostgreSQL asume que las columnas son independientes y multiplica sus selectividades. Pero aquí cada código postal pertenece a un único municipio y cada municipio a una única provincia, así que los tres filtros dicen lo mismo y la selectividad real es mucho mayor que el producto.

Dentro de una unión con pedidos y lineas_pedido, el error se arrastra y se amplifica:

Aggregate  ...
  ->  Nested Loop  (cost=5.64..746.27 rows=286 width=10) (actual time=0.137..55.855 rows=6735 loops=1)
        ->  Nested Loop  (cost=5.21..684.97 rows=100 width=4) (actual time=0.048..5.643 rows=2245 loops=1)
              ->  Seq Scan on clientes c  (cost=0.00..309.00 rows=1 width=4) (actual time=0.014..1.071 rows=23 loops=1)

Estimado 286 filas en la unión, reales 6 735: 23 veces menos. En este caso el plan sigue siendo razonable, pero con una estimación así de mala el planificador puede elegir un Nested Loop donde un Hash Join sería mucho mejor. Aquí hemos tenido suerte.

El arreglo no es un índice, sino darle al planificador información sobre la correlación con estadísticas extendidas:

CREATE STATISTICS clientes_geo (dependencies, ndistinct)
    ON provincia, municipio, codigo_postal FROM clientes;
ANALYZE clientes;

dependencies es la que corrige los filtros de igualdad como este; ndistinct ayuda con los GROUP BY sobre varias columnas. El resultado:

Seq Scan on clientes  (cost=0.00..309.00 rows=23 width=74) (actual time=0.024..1.043 rows=23 loops=1)
...
Nested Loop  (cost=5.64..9322.65 rows=6573 width=10) (actual time=0.060..14.631 rows=6735 loops=1)

Estimado 23, real 23. En la unión, 6 573 estimadas frente a 6 735 reales.

Una advertencia de honestidad: en este laboratorio la forma del plan no cambió, así que la consulta no mejora «gracias» a la estadística. Si compruebas los números verás que pasa de 58 ms a 17 ms, pero eso es sobre todo caché: en la primera salida el último nodo lee de fuera de shared_buffers (read=4047) y en la segunda no. Estimar bien no garantiza un plan distinto; lo que garantiza es que, cuando el plan tenga que cambiar, tome la decisión con datos correctos.

BUFFERS: ¿lenta por leer o lenta por trabajar? #

BUFFERS cuenta las páginas (de 8 kB) que toca cada nodo:

  • shared hit: la página ya estaba en la caché de PostgreSQL (shared_buffers).
  • shared read: no estaba y hubo que pedirla fuera. Ojo, «fuera» puede ser la caché del sistema operativo y no necesariamente el disco.

El mismo Seq Scan sobre pedidos, recién arrancado el servidor y luego con la tabla ya caliente:

-- Frío (recién reiniciado)
Seq Scan on pedidos ...
  Buffers: shared read=7353

-- Caliente
Seq Scan on pedidos ...
  Buffers: shared hit=7353

Siempre las mismas 7 353 páginas, que son las que ocupa la tabla. Lo que cambia es de dónde salen. Esto te ayuda a distinguir dos tipos de lentitud: la que viene de leer mucho (muchos read) y la que viene de trabajar mucho (muchos hit y mucho tiempo de CPU). Y te avisa de un clásico: la consulta que «va rápido la segunda vez» no está arreglada, está en caché.

El N+1, visto en un plan #

Si vienes de ORMs, el N+1 es el patrón de ejecutar una consulta por cada fila de otra. Dentro de PostgreSQL tiene su versión: la subconsulta correlacionada.

SELECT p.id,
       (SELECT sum(l.cantidad * l.precio)
        FROM lineas_pedido l
        WHERE l.pedido_id = p.id) AS importe
FROM pedidos p
WHERE p.cliente_id BETWEEN 4242 AND 4261;

El plan:

Bitmap Heap Scan on pedidos p  (cost=28.27..20915.11 rows=1936 width=36) (actual time=0.629..43.262 rows=2000 loops=1)
  SubPlan 1
    ->  Aggregate  (cost=8.51..8.52 rows=1 width=32) (actual time=0.018..0.018 rows=1 loops=2000)
          ->  Index Scan using idx_lineas_pedido on lineas_pedido l  (cost=0.43..8.48 rows=3 width=10) (actual time=0.016..0.017 rows=3 loops=2000)
Execution Time: 43.501 ms

loops=2000: el SubPlan se ejecuta una vez por pedido. Cada vuelta cuesta 0,018 ms, que parece nada, pero 0,018 × 2000 = 36 ms de los 43,5 totales. Es la regla 2 en acción. La versión con JOIN y GROUP BY hace el mismo trabajo en 11,6 ms.

Dentro de la base de datos la diferencia es moderada porque no hay red entre medias. El N+1 «de verdad» es el que hace la aplicación: una consulta por pedido, cada una con su viaje de ida y vuelta al servidor. El laboratorio lo mide con n_mas_1.sh, que lanza 2 000 consultas sueltas y luego una sola con JOIN, ambas desde una única sesión de psql y por socket Unix local (la red más rápida que existe):

ignacio@zeus:~/blog-public-code/lab-explain$ ./n_mas_1.sh
Pedidos a calcular: 2000

== N+1: 2000 consultas sueltas
real	0m0.226s

== Una sola consulta con JOIN
real	0m0.056s

En cinco ejecuciones, el N+1 tardó entre 226 y 256 ms y el JOIN entre 51 y 93 ms: entre 2,5 y 4,5 veces más lento, sin red de por medio. Con un servidor remoto, cada viaje cuesta además la latencia de red, y la diferencia crece a base de bien.

Si leíste la serie de GraphQL, ya me has visto dar la lata con el N+1 y con DataLoader. Aquí lo único que cambia es dónde mirar: en el plan, un loops enorme.

Tres autopsias: el índice existe y PostgreSQL pasa de él #

Volvamos a la pregunta del principio.

1. Función aplicada a la columna indexada #

Hay un índice sobre pedidos.fecha. Esta consulta busca los pedidos de un día:

SELECT * FROM pedidos WHERE to_char(fecha, 'YYYY-MM-DD') = '2024-03-15';
Seq Scan on pedidos  (cost=0.00..24853.00 rows=5000 width=27) (actual time=0.104..459.164 rows=726 loops=1)
  Filter: (to_char((fecha)::timestamp with time zone, 'YYYY-MM-DD'::text) = '2024-03-15'::text)
  Rows Removed by Filter: 999274
Execution Time: 459.294 ms

El índice está ordenado por fecha, no por to_char(fecha, ...). Para PostgreSQL esa función es una caja negra: no puede deducir en qué parte del índice caería el resultado, así que no tiene más remedio que calcularla fila a fila sobre el millón de filas.

Fíjate también en rows=5000 frente a 726 reales: ante una expresión opaca PostgreSQL no tiene estadísticas y usa una estimación por defecto (un 0,5 % de la tabla).

La solución es escribir la condición sobre la columna «desnuda»:

SELECT * FROM pedidos WHERE fecha = DATE '2024-03-15';
Bitmap Heap Scan on pedidos  (cost=9.94..2118.47 rows=712 width=27) (actual time=0.235..1.202 rows=726 loops=1)
  Recheck Cond: (fecha = '2024-03-15'::date)
  ->  Bitmap Index Scan on idx_pedidos_fecha  (cost=0.00..9.77 rows=712 width=0) (actual time=0.141..0.141 rows=726 loops=1)
Execution Time: 1.272 ms

459 ms → 1,3 ms, y además la estimación (712) ya se parece a la realidad (726). Es la misma regla para date_trunc, lower(), extract() o un cast sobre la columna: si la envuelves en una función, el índice normal no la entiende. O reescribes la condición, o creas un índice sobre la expresión.

2. Tipos que no encajan #

pedidos.cliente_id es un integer con índice. ¿Y si lo comparamos con un número con decimales, como hacen algunos drivers o ORMs al enviar parámetros?

SELECT * FROM pedidos WHERE cliente_id = 4242.0;
Seq Scan on pedidos  (cost=0.00..22353.00 rows=5000 width=27) (actual time=12.194..114.285 rows=103 loops=1)
  Filter: ((cliente_id)::numeric = 4242.0)
  Rows Removed by Filter: 999897
Execution Time: 114.316 ms

La pista está en el Filter: (cliente_id)::numeric. Como 4242.0 es un numeric, PostgreSQL convierte la columna a numeric para poder comparar, y un índice sobre integer no sirve para una comparación sobre numeric. Misma consulta con el literal correcto:

Bitmap Heap Scan on pedidos  (cost=5.20..371.46 rows=100 width=27) (actual time=0.032..0.138 rows=103 loops=1)
  ->  Bitmap Index Scan on idx_pedidos_cliente  (cost=0.00..5.17 rows=100 width=0) (actual time=0.015..0.015 rows=103 loops=1)
Execution Time: 0.161 ms

114 ms → 0,16 ms. Cuando un índice «no se usa» y no sabes por qué, lee el Filter con atención: un ::tipo pegado a tu columna delata este problema.

3. Poca selectividad #

Con un índice sobre estado, la misma columna con tres valores distintos produce tres comportamientos distintos:

CondiciónFilasPlan elegidoTiempo
estado = 'entregado'899 663 (90 %)Seq Scan128 ms
estado = 'pendiente'25 177 (2,5 %)Bitmap Heap Scan17 ms
estado = 'devuelto'4 895 (0,5 %)Index Scan2,9 ms

No hay nada roto. El mismo índice sirve muy bien para el 0,5 % y es inútil para el 90 %, y PostgreSQL decide en cada consulta comparando costes con las estadísticas de la columna. Si alguna vez te preguntas por qué el índice de una columna con pocos valores distintos «no funciona», probablemente sí funciona, pero para los valores raros.

Herramientas para no leer planes a mano #

Cuando el plan es largo, lo cómodo es visualizarlo:

  • explain.depesz.com: pegas el plan y marca en colores los nodos que más tiempo consumen.
  • explain.dalibo.com: visualización en forma de árbol y diagrama. Está construido sobre PEV2, que es software libre.

Un consejo de higiene antes de pegar nada en un servicio público: el plan contiene nombres de tablas, de columnas e incluso valores literales de tus consultas. Si trabajas con datos internos, anonimiza el plan o usa una herramienta que puedas alojar tú.

Qué cambia en PostgreSQL 18 #

Todas las salidas de esta entrada son de PostgreSQL 16.15. Las versiones recientes mejoran EXPLAIN: en PostgreSQL 18, EXPLAIN ANALYZE incluye BUFFERS por defecto, y los nodos de índice muestran una línea Index Searches con el número de recorridos que hizo el índice (más detalle en el artículo de pgMustard). La forma de leer el plan es la misma; sólo verás alguna línea más.

Checklist de cinco preguntas #

Ante cualquier plan, en este orden:

  1. ¿Dónde está el tiempo? Busca el nodo con mayor actual time multiplicado por loops. Ahí es donde optimizar.
  2. ¿Coinciden rows estimado y real? Si difieren por órdenes de magnitud, revisa estadísticas (ANALYZE, CREATE STATISTICS) antes de tocar índices.
  3. ¿Cómo accede a la tabla? Un Seq Scan con un Rows Removed by Filter enorme y pocas filas devueltas pide un índice. Con muchas filas devueltas, está bien.
  4. ¿Hay algo raro pegado a mi columna en el Filter/Index Cond? Una función, un ::cast… eso explica un índice ignorado.
  5. ¿Es lectura o trabajo? Mira BUFFERS: muchos read indican que hay que traer datos de fuera; muchos hit con mucho tiempo, que la CPU está trabajando de más.

Para quedarte con algo #

  • EXPLAIN estima, EXPLAIN ANALYZE ejecuta. Usa BEGIN/ROLLBACK con DML.
  • El plan se lee de dentro hacia fuera y el tiempo real es por vuelta.
  • Compara siempre estimado con real: ahí se esconde la mitad de los problemas.
  • Un Seq Scan no es malo por sí mismo.
  • Si un índice no se usa, mira el Filter: tipos, funciones y selectividad.

Todo el código está en lab-explain/ con las salidas de referencia en salidas/. Si lo ejecutas y te salen planes distintos, fíjate en la forma, no en los milisegundos, y cuéntamelo: es la mejor manera de aprender cuál fue la decisión del planificador.


Ingrese la dirección de su instancia


Más posts como este