Re: BUG #16065: The operation nodes in query plans outputted byEXPLAIN have no authoritative definitions. - Mailing list pgsql-bugs

From Jeff Janes
Subject Re: BUG #16065: The operation nodes in query plans outputted byEXPLAIN have no authoritative definitions.
Date
Msg-id CAMkU=1yT_wv6zBt-C9GHQrtMjngk5WmAPTzfPFuAvAKk9zvN5g@mail.gmail.com
Whole thread Raw
In response to BUG #16065: The operation nodes in query plans outputted by EXPLAIN have no authoritative definitions.  (PG Bug reporting form <noreply@postgresql.org>)
Responses Re: BUG #16065: The operation nodes in query plans outputted byEXPLAIN have no authoritative definitions.
List pgsql-bugs
On Fri, Oct 18, 2019 at 11:02 AM PG Bug reporting form <noreply@postgresql.org> wrote:
The following bug has been logged on the website:

Bug reference:      16065
Logged by:          Eric Toombs
Email address:      ewtoombs@uwaterloo.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

pgsql-bugs by date:

Previous
From: PG Bug reporting form
Date:
Subject: BUG #16069: Error installing yum.rpm
Next
From: Tom Lane
Date:
Subject: Re: BUG #16067: Failed system call was semget