Re: BUG #16065: The operation nodes in query plans outputted by EXPLAIN have no authoritative definitions.

On Fri, Oct 18, 2019 at 11:02 AM PG Bug reporting form <
noreply(at)postgresql(dot)org> wrote:

> The following bug has been logged on the website:
>
> Bug reference: 16065
> Logged by: Eric Toombs
> Email address: ewtoombs(at)uwaterloo(dot)ca
> PostgreSQL version: 12.0
> Operating system: any
> Description:
>
> The official documentation of EXPLAIN is here:
> https://www.postgresql.org/docs/current/sql-explain.html
>
> It's a start, but it doesn't actually define any of the operation nodes in
> the query plan tree it outputs, e.g. Seq Scan, Index Scan, Index Only Scan,
> HashAggregate, Nested Loop, Nested Loop Semi Join, Nested Loop Anti Join,
> etc.. Online, there are descriptions (i.e. guesses) of what each operation
> node is actually doing, but these descriptions are not authoritative.
>

I agree that the documentation of EXPLAIN is sparse in general, but I don't
buy this particular complaint. If someone doesn't know what a Nested Loop
is, are they going to understand any reasonable length description of it
which we can offer? If someone doesn't know the very basic vocabulary of
computer operations, what words could we use to explain things to them?

There may be value in providing translations of those terms into other
languages, but that is a different topic.

> With authoritative definitions of each operation node, there would be no
> more guesswork, and DBAs could have a much more reliable mental model of
> what a query plan actually does.
>

It seems like an infinite regress where we have to provide an authoritative
definition of every word we use while providing the authoritative
definitions of the other words we use. Maybe some clever person can break
that loop, but without seeing a concrete proposal I am skeptical it can be
done.

In any event, it certainly isn't a bug. Probably the docs mailing list
would be a better venue to discuss it.

Cheers,

Jeff