Re: EXPLAIN: showing ReadStream / prefetch stats

On Mon, May 4, 2026 at 6:51 AM Tomas Vondra <tomas(at)vondra(dot)me> wrote:
>
> While looking for something in the EXPLAIN docs, I realized the docs
> added by 681daed93169 are considerably less detailed that for the other
> EXPLAIN options. It only said "information on I/O" provided by the scan
> node, while the other options go into much more details.
>
> The attached patch improves that a little bit - it lists the counters
> added to explain. I'll consider going into a little bit more detail,
> e.g. regarding what "capacity" or "waits" means.

I think that makes sense to add.

Two thoughts:

(1) I think going into a bit more detail makes sense to actually
explain how to interpret the values (or maybe even what action to
take?) - I think the BUFFERS documentation is probably a good style to
follow in terms of how it lists out the individual values and their
meaning.

(2) What do you think of also clarifying when this information is
tracked? I gave that feedback in an earlier patch in this thread, but
I still feel like the "scan nodes providing such information" is very
vague and not helpful for users trying to understand when this is
shown (e.g. the fact that this currently has no visibility on index
I/O, and won't tell you anything about writes being performed to clear
out dirty buffers/etc).

Maybe:

"Include information on I/O performed by scan nodes providing such
information, currently visible for read I/O issued by Bitmap Heap
Scans, Sequential Scans and TID Scans."

Of course that's a bit prone to get stale, but I think the clarity on
what it does/doesn't do would be worth the effort to maintain it.

Thanks,
Lukas

--
Lukas Fittl