BUG #16065: The operation nodes in query plans outputted by EXPLAIN have no authoritative definitions.
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.
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.
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.htmlIt'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
I was unaware of the existence of a docs mailing list. I'll post this there.
Show quoted text
On 2019-10-19 17:07, Jeff Janes wrote:
On Fri, Oct 18, 2019 at 11:02 AM PG Bug reporting form
<noreply@postgresql.org <mailto: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
<mailto: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.htmlIt'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