Re: [Minor] Improvement on random functions doc

On Tue, Oct 20, 2026 at 11:06 PM David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>
> On Tuesday, October 20, 2026, Fujii Masao <masao(dot)fujii(at)gmail(dot)com> wrote:
>>
>> On Wed, Oct 21, 2026 at 3:54 AM Matemática A3K <matematica(dot)a3k(at)gmail(dot)com> wrote:
>> > In my terms, this would be something like "Accuracy was traded in
>> > order to better convey the idea to the audience". I find this to be
>> > valid although I don't share it nor I think the documentation is built
>> > upon it, but this is just my opinion, thanks for sharing yours.
>>
>> pgbench docs already describes random() as producing a "uniformly-distributed
>> random integer". So I'm OK with explicitly stating that the distribution is
>> uniform here as well.
>>
>> If we do that, I think it's better to use similar wording to keep the docs
>> consistent.
>
>
> I’m not strongly opposed to clarifying this but…
>
> pgbench also has random_exponential and random_zipfian and calls random_normal random_gaussian.
> Its target audience is quite different than the person executing random in some SQL command.

While your concern about the audience makes sense, this section is not
a tutorial, it's the reference for the implementation. As such, it
should be as accurate as possible in order to find its appropriate
use.

> The fact that normal_uniform doesn’t actually exist because an unqualified random is conventionally drawn without any bias to a particular value.

I think the convention for "random()" is providing numbers sampled
from uniform distribution in [0,1] because with this you can generate
values from other domains and distributions. That "convention" is not
clear where it has been made, so it should be stated.

> The clarification in pgbench seems more like pattern matching with its larger set of random variants.
>
> I’m less inclined to use pgbench’s phrasing for much the same reason - the returns wording seems to fit better in chapter 9. I’m also not a fan of using “uniformly” if we do clarify this. “…from a uniform distribution covering 0 <= x < 1” would pattern match the existing random_normal wording.

I agree that better wording could be used here. How about:
- "Returns a value sampled from a uniform distribution in the range
0.0 <= x < 1.0"
- "Returns a value sampled from a uniform distribution in the range
min <= x <= max"
- "Returns a value sampled from a normal distribution with the given
parameters;"
?