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

I was unaware of the existence of a docs mailing list. I'll post this there.

On 2019-10-19 17:07, Jeff Janes wrote:
> On Fri, Oct 18, 2019 at 11:02 AM PG Bug reporting form
> <noreply(at)postgresql(dot)org <mailto: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
> <mailto: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