On 5/4/26 17:22, Lukas Fittl wrote:
> On Mon, May 4, 2026 at 6:51 AM Tomas Vondra <tomas@vondra.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.
>
Agreed.
> (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.
>
Yeah, I'll think about it. At some point I didn't like mentioning exact
scan types, because who knows what custom scans could do etc. But maybe
that's OK.
regards
--
Tomas Vondra
