Bug #103386 Documentation of SELECT statement doesn't ever specify what HAVING clause does
Submitted: 20 Apr 2021 16:57 Modified: 28 Apr 2021 10:13
Reporter: teo teo Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.7, 8.0 OS:Any
Assigned to: CPU Architecture:Any

[20 Apr 2021 16:57] teo teo
Description:
Suppose I want to know what the HAVING clause is for.
That's what documentation is for, right?

At https://dev.mysql.com/doc/refman/8.0/en/select.html

there are a lot of details about where you can and cannot use the HAVING clause, comparison between HAVING and WHERE, limitations, etc, but at no point does it ever just explain what the HAVING clause means or does.

It's sort of implied that it's a condition, like WHERE. You can deduce that by the fact that the docs tell you not to use HAVING when you should use WHERE. But it's never explicitly said.

It's like your are ASSUMING that the reader already knows what the HAVING clause means. 
You should never assume that. Documentation is for explaining what the statements and clauses do, not just for giving in-depth details to readers that are assumed to already know the basics. Otherwise where do you put the limit between what is expected to be already known and what you need to document??

That the meaning of HAVING is pretty intuitive and corresponds to the meaning of the word "having" in English is no excuse. The same is true for "WHERE" and yet, the documentation does explicitly say what the WHERE clause does:

"The WHERE clause, if given, indicates the condition or conditions that rows must satisfy to be selected. where_condition is an expression that evaluates to true for each row to be selected. The statement selects all rows if there is no WHERE clause."

There is no equivalent explanation for the HAVING clause, and there isn't even one that vaguely states something like "HAVING is similar to WHERE but...". That's completely implied.

How to repeat:
...
[21 Apr 2021 6:54] MySQL Verification Team
Hello Teo Teo,

Thank you for the report.

Thanks,
Umesh
[28 Apr 2021 10:13] Paul DuBois
Posted by developer:
 
Updated.