From: Tomas Vondra <tomas@vondra.me>
To: Andres Freund <andres@anarazel.de>
Cc: Melanie Plageman <melanieplageman@gmail.com>
Cc: Lukas Fittl <lukas@fittl.com>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
Subject: Re: EXPLAIN: showing ReadStream / prefetch stats
Date: Mon, 4 May 2026 15:51:20 +0200
Message-ID: <afa26355-0170-4dfc-a381-024c052d26bf@vondra.me> (raw)
In-Reply-To: <s7s37qespplnffoy3f4ewyuuqrisnmb3kfurwdrm5plsqxkiak@rxnl5sahitsr>
References: <2aaa701f-76f9-4e83-bb2c-ec4520b5a89b@vondra.me>
<CAAKRu_by3fu=VsRmHjRMi9sF6Uy8mSruApyvzRm+O_=E1-ViAA@mail.gmail.com>
<8d6187c9-62ac-43a3-88d1-7503c4206657@vondra.me>
<CAP53PkxCmAF9qioQpGM8+H4sb_0ThUrvKR3wLEQ+8QNdVN_tQQ@mail.gmail.com>
<6ce690b9-0ec4-4d9e-ae9b-95a5ca3f79b2@vondra.me>
<72391376-967e-41b8-806b-41f9efea9a97@vondra.me>
<CAAKRu_Z9D5WYyEwnGGEgb5UOT8X1X+pCS4Trthq-Raz3h3N7vw@mail.gmail.com>
<552ecf6c-e8a2-4183-afc4-eff592674475@vondra.me>
<CAAKRu_ZKCGgm=hVmuSLdsQ4n8dGDdQX-A2MzLCUezj-O+xFRHw@mail.gmail.com>
<7ef4455a-5325-4dd8-906d-7bb7f3e787d7@vondra.me>
<s7s37qespplnffoy3f4ewyuuqrisnmb3kfurwdrm5plsqxkiak@rxnl5sahitsr>
Hi,
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'll add this as an open item for PG19, so that I don't forget about it.
regards
--
Tomas Vondra
Attachments:
[text/x-patch] 0001-Improve-docs-for-EXPLAIN-IO.patch (1.6K, ../afa26355-0170-4dfc-a381-024c052d26bf@vondra.me/2-0001-Improve-docs-for-EXPLAIN-IO.patch)
download | inline diff:
From e032752680193a26e21c3927968f72bed20db99e Mon Sep 17 00:00:00 2001
From: test <test>
Date: Sun, 3 May 2026 16:05:54 +0200
Subject: [PATCH] Improve docs for EXPLAIN (IO)
Commit 681daed931 introduced a new EXPLAIN options "IO", but the docs
did not explain what information is added to the output. Expand the
description a little bit, similarly to the other EXPLAIN options.
While at it, fix a typo in the first sentence.
Reported-by: FIXME link to the typo report
Author: Tomas Vondra <tomas@vondra.me>
---
doc/src/sgml/ref/explain.sgml | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgmlindex e95e19081e1..d0644bca038 100644--- a/doc/src/sgml/ref/explain.sgml+++ b/doc/src/sgml/ref/explain.sgml@@ -303,7 +303,13 @@ ROLLBACK;
<term><literal>IO</literal></term>
<listitem>
<para>
- Include information on I/O performed by scan nodes proving such information.+ Include information on I/O performed by scan nodes providing such+ information.+ Specifically, include information about the prefetch queue (the average+ and maximum distance, and the capacity), and information about issued+ I/O requests (number of requests and an average request size, number of+ I/O waits, and an average number of concurrent I/O requests).+ In text format, only non-zero values are printed.
This parameter may only be used when <literal>ANALYZE</literal> is also
enabled. It defaults to <literal>FALSE</literal>.
</para>
--
2.54.0
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: tomas@vondra.me, andres@anarazel.de, melanieplageman@gmail.com, lukas@fittl.com, pgsql-hackers@lists.postgresql.org
Subject: Re: EXPLAIN: showing ReadStream / prefetch stats
In-Reply-To: <afa26355-0170-4dfc-a381-024c052d26bf@vondra.me>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox