V18 change on EXPLAIN ANALYZE

On Fri, Sep 26, 2025 at 1:34 PM Marcos Pegoraro <marcos@f10.com.br> wrote:

Robert Hass committed ddb17e387aa28d61521227377b00f997756b8a27, which changed how EXPLAIN indicates fractional rows. That's cool but I have to see that change on sources because it's not explained on DOCs.

One can understand that cost=4.36, that actual time=0.009, but what means rows=10.43 ? Costs and Time having decimals are fine but what is a row and a half ?

So, I don't know exactly how to explain this change but I think it would be good to have a new paragraph on [1] and explain that now when nloops > 1, we now display two digits after the decimal point, rather than none.

[1] - https://www.postgresql.org/docs/current/using-explain.html#USING-EXPLAIN-ANALYZE

The page you link says

In some query plans, it is possible for a subplan node to be
executed more than once. For example, the inner index scan will be
executed once per outer row in the above nested-loop plan. In such
cases, the loops value reports the total number of executions of the
node, and the actual time and rows values shown are averages
per-execution. This is done to make the numbers comparable with the
way that the cost estimates are shown. Multiply by the loops value to
get the total time actually spent in the node. In the above example,
we spent a total of 0.030 milliseconds executing the index scans on
tenk2.

in the second paragraph after the example in this section. Do you
think that's not sufficiently clear?

Thanks,
Maciek

Maciek Sakrejda <m.sakrejda@gmail.com> writes:

The page you link says

In some query plans, it is possible for a subplan node to be
executed more than once. For example, the inner index scan will be
executed once per outer row in the above nested-loop plan. In such
cases, the loops value reports the total number of executions of the
node, and the actual time and rows values shown are averages
per-execution. This is done to make the numbers comparable with the
way that the cost estimates are shown. Multiply by the loops value to
get the total time actually spent in the node. In the above example,
we spent a total of 0.030 milliseconds executing the index scans on
tenk2.

in the second paragraph after the example in this section. Do you
think that's not sufficiently clear?

It's not wrong, but it feels a little incomplete now. Maybe change
the last two sentences to

Multiply by the loops value to get the total time actually spent in
the node and the total number of rows processed by the node across all
executions. In the above example, we spent a total of 0.030
milliseconds executing the index scans on tenk2, and they handled a
total of 10 rows.

A bigger gap in perform.sgml is that it doesn't address parallel
query cases at all AFAICS. I think that was one of the main drivers
of this change, so it feels a little sad that it's not covered here.

regards, tom lane

On Fri, Sep 26, 2025 at 2:12 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Maciek Sakrejda <m.sakrejda@gmail.com> writes:

The page you link says

In some query plans, it is possible for a subplan node to be
executed more than once. For example, the inner index scan will be
executed once per outer row in the above nested-loop plan. In such
cases, the loops value reports the total number of executions of the
node, and the actual time and rows values shown are averages
per-execution. This is done to make the numbers comparable with the
way that the cost estimates are shown. Multiply by the loops value to
get the total time actually spent in the node. In the above example,
we spent a total of 0.030 milliseconds executing the index scans on
tenk2.

in the second paragraph after the example in this section. Do you
think that's not sufficiently clear?

It's not wrong, but it feels a little incomplete now. Maybe change
the last two sentences to

Multiply by the loops value to get the total time actually spent in
the node and the total number of rows processed by the node across all
executions. In the above example, we spent a total of 0.030
milliseconds executing the index scans on tenk2, and they handled a
total of 10 rows.

A bigger gap in perform.sgml is that it doesn't address parallel
query cases at all AFAICS. I think that was one of the main drivers
of this change, so it feels a little sad that it's not covered here.

Fair point. I included your proposed change and took a stab at briefly
covering parallelism in the attached (admittedly, my understanding of
how that works is a little shaky, so apologies if I'm way off on some
of this).

However, to get a parallel query in the regression database (I chose
EXPLAIN ANALYZE SELECT * FROM tenk2), I had to change some settings:

SET min_parallel_table_scan_size = 0;
SET parallel_tuple_cost = 0;
SET parallel_setup_cost = 0;

Should I mention that in the example? Or should I generate a bigger
table so using these is not necessary? If we say nothing and use the
example, I think it may be confusing if someone wants to use the
example as a starting point for their own exploration of how this
works. Or is there a better query that works out of the box and does
not need changes to the settings?

It also seems like the EXPLAIN ANALYZE section is getting a little
unwieldy. Should we subdivide it, or is this still okay?

Thanks,
Maciek

Hi hackers,

On 27.09.2025 03:31, Maciek Sakrejda wrote:

However, to get a parallel query in the regression database (I chose
EXPLAIN ANALYZE SELECT * FROM tenk2), I had to change some settings:

SET min_parallel_table_scan_size = 0;
SET parallel_tuple_cost = 0;
SET parallel_setup_cost = 0;

Should I mention that in the example? Or should I generate a bigger
table so using these is not necessary? If we say nothing and use the
example, I think it may be confusing if someone wants to use the
example as a starting point for their own exploration of how this
works. Or is there a better query that works out of the box and does
not need changes to the settings?

It also seems like the EXPLAIN ANALYZE section is getting a little
unwieldy. Should we subdivide it, or is this still okay?

Thanks for noticing the documentation gap regarding parallel plans.

1. I think the mention of VERBOSE might be unnecessary, since this is
already covered in parallel.sgml, section 'Parallel Plan Tips'. That
section explicitly says that EXPLAIN (ANALYZE, VERBOSE) shows per-worker
statistics.

2. Instead of introducing another query, why not reuse the one already
shown earlier in the same section, just with the GUCs adjusted to make
it parallel? For example:

SET min_parallel_table_scan_size = 0;
SET parallel_tuple_cost = 0;
SET parallel_setup_cost = 0;

EXPLAIN ANALYZE
SELECT *
FROM tenk1 t1, tenk2 t2
WHERE t1.unique1 < 10 AND t1.unique2 = t2.unique2;
QUERY PLAN
------------------------------------------------------------------------------------------------------------------------------------------
 Gather  (cost=4.65..70.96 rows=10 width=488) (actual time=1.670..6.246
rows=10.00 loops=1)
   Workers Planned: 2
   Workers Launched: 2
   Buffers: shared hit=78 read=6
   ->  Nested Loop  (cost=4.65..70.96 rows=4 width=488) (actual
time=0.218..0.277 rows=3.33 loops=3)
         Buffers: shared hit=78 read=6
         ->  Parallel Bitmap Heap Scan on tenk1 t1 (cost=4.36..39.31
rows=4 width=244) (actual time=0.195..0.202 rows=3.33 loops=3)
               Recheck Cond: (unique1 < 10)
               Heap Blocks: exact=10
               Buffers: shared hit=54
               ->  Bitmap Index Scan on tenk1_unique1 (cost=0.00..4.36
rows=10 width=0) (actual time=0.449..0.450 rows=10.00 loops=1)
                     Index Cond: (unique1 < 10)
                     Index Searches: 1
                     Buffers: shared hit=2
         ->  Index Scan using tenk2_unique2 on tenk2 t2
(cost=0.29..7.90 rows=1 width=244) (actual time=0.020..0.020 rows=1.00
loops=10)
               Index Cond: (unique2 = t1.unique2)
               Index Searches: 10
               Buffers: shared hit=24 read=6
 Planning:
   Buffers: shared hit=141 read=3
 Planning Time: 0.519 ms
 Execution Time: 6.302 ms
(22 rows)

--
Best regards,
Ilia Evdokimov,
Tantor Labs LLC,
https://tantorlabs.com/

Thanks for the feedback!

On Thu, Oct 30, 2025 at 7:35 AM Ilia Evdokimov
<ilya.evdokimov@tantorlabs.com> wrote:

1. I think the mention of VERBOSE might be unnecessary, since this is already covered in parallel.sgml, section 'Parallel Plan Tips'. That section explicitly says that EXPLAIN (ANALYZE, VERBOSE) shows per-worker statistics.

Okay. I think the EXPLAIN docs are a better place for that info, but
if that's the consensus, I can update the patch.

2. Instead of introducing another query, why not reuse the one already shown earlier in the same section, just with the GUCs adjusted to make it parallel?

Sure, I can do that. I thought a more concise example would make it
clearer to see the parallelism-related bits.

And to answer my own question, I noticed another example has `SET
enable_seqscan TO off;`, so I'll add the GUCs.

Thanks,
Maciek

I lost track of this, sorry. Here is an updated patch responding to
review feedback.

On 2/1/26 01:55, Maciek Sakrejda wrote:

I lost track of this, sorry. Here is an updated patch responding to
review feedback.

In sgml documentation, using |<| unescaped may cause the documentation
build to fail or behave unexpectedly [0]https://cirrus-ci.com/task/4731121381933056. It would be safer to replace
it with |&lt;| . And symbol |->| into |-&gt;|

I noticed that a long horizontal separator line in the query plan is
missing a |&zwsp;|

[0]: https://cirrus-ci.com/task/4731121381933056

--
Best regards,
Ilia Evdokimov,
Tantor Labs LLC,
https://tantorlabs.com/

Thanks for the feedback! I'm attaching a v2 fixing these issues.

Sorry, that should have been the attached v3.

On 3/4/26 22:13, Maciek Sakrejda wrote:

Sorry, that should have been the attached v3.

LGTM

One small nit: the patch currently adds trailing whitespace on the line
with "QUERY PLAN".

--
Best regards,
Ilia Evdokimov,
Tantor Labs LLC,
https://tantorlabs.com/

Ah, good catch. Fixed in attached v4.

Maciek Sakrejda <maciek@pganalyze.com> writes:

Ah, good catch. Fixed in attached v4.

Pushed with some tiny editorializations.

regards, tom lane

On Mon, Mar 23, 2026 at 11:49 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Maciek Sakrejda <maciek@pganalyze.com> writes:

Ah, good catch. Fixed in attached v4.

Pushed with some tiny editorializations.

Thanks!