Fwd: [PATCH] doc: outline all planner nodes

---------- Forwarded message ---------
From: Brian Brennglass <brian(at)supabase(dot)io>
Date: Thu, 30 Jul 2026 at 15:34
Subject: Re: [PATCH] doc: outline all planner nodes
To: Marcos Pegoraro <marcos(at)f10(dot)com(dot)br>

> cool this patch, I think it's a valuable contribution.

Thank you :)

> I don't know what version you are running, but rows is now a numeric, not
integer anymore.
> So rows should have decimals, like rows=199999.00 loops=1)

I was running PG 17. I just tested it for PG18, and it produced floats, but
only for the "actual cost" in EXPLAIN ANALYZE. I'll update the examples
that reference ANALYZE.

Just as an aside, I am kind of curious why PG uses decimals to track rows.
Is it now possible to return half a row?

> Maybe you add previous commands to create that table and later run that
select, so the user can replicate how to have that occurrence.
>Like you do on "Named Tuplestore Scan"

When I first started writing the patch, I had included table definitions,
but I found 2 issues with it:

1. It was noisy

All the extra SQL made the page very long, and I found it hard to follow. I
made an exception for "Named Tuplestore Scan" because the scan is so
obscure that I thought providing a larger example was the only way to make
it understandable.

I put it at the end of its section so the large block wouldn't disrupt the
flow as much. If you think the extra SQL is worth it, I'd be okay
revisiting. At that point, though, it may make sense to break up the doc
into multiple sub-chapters: Scans, Joins, DML... Otherwise, I think readers
would be intimidated by its length.

2. It wouldn't be reliable

The same query can produce different plans depending on server configs,
version, distribution of data within columns, ...

Unless we specify the PG version and configs used for the examples, not all
nodes are going to be consistently reproducible.

I'm not completely opposed to adding setup SQL, but it would also mean
revalidating them between PG releases.

At the moment, I'm thinking the maintenance overhead wouldn't be worth
it, especially
since I expect many readers will use the page to interpret plans they're
already seeing rather than to learn how to reproduce every plan node from
scratch.

> - Maybe you could run with EXPLAIN (costs off), because the goal is to
show the plan, not the cost.

I did this for the materialize example[1] because it was just too congested
to read otherwise, but was hesitant to apply it to the other nodes, too. I
thought writing out EXPLAIN (COSTS FALSE) would look a bit strange, as, in
my experience, it's not commonly referenced. I do agree that the costs
aren't useful for the page. I think it's best that I overlook my initial
hesitation. I'll update EXPLAIN to EXPLAIN (COSTS FALSE)

Best,
Brian B.

1. https://lovely-salmiakki-fdb4a0.netlify.app/#MATERIALIZE-OVERVIEW

On Mon, 27 Jul 2026 at 18:54, Marcos Pegoraro <marcos(at)f10(dot)com(dot)br> wrote:

> Em ter., 21 de jul. de 2026 às 15:34, Brian Brennglass <brian(at)supabase(dot)io>
> escreveu:
>
>> Just rebasing the previous patch. Also generated a preview site:
>>
>
> cool this patch, I think it's a valuable contribution.
>
> - I don't know what version you are running, but rows is now a numeric,
> not integer anymore.
> So rows should have decimals, like rows=199999.00 loops=1)
> - Maybe you add previous commands to create that table and later run that
> select, so the user can replicate how to have that occurrence.
> Like you do on "Named Tuplestore Scan"
> - Maybe you could run with EXPLAIN (costs off), because the goal is to
> show the plan, not the cost.
>
> regards
> Marcos
>