[Minor] Improvement on random functions doc
Hackorum builds and tests every patch posted to the lists, not only commitfest submissions. This is Hackorum's own CI rather than the PostgreSQL project's, and it is still under testing - please report anything that looks wrong.
You can run a PostgreSQL built from this patch straight from Docker, with no checkout and no build:
docker run --rm -p 5432:5432 ghcr.io/hackorum-dev/postgres-patch:t254292psql -h localhost -U postgresBuilt from patchset v1 (message #1), October 26, 2026 at 06:58 PM.
Every patchset is also pushed to a branch of our PostgreSQL fork, so you can check out the same tree CI built. Without a PostgreSQL checkout:
git clone --branch t254292_1 https://github.com/hackorum-dev/postgres.gitIn a checkout you already have, add the fork once:
git remote add hackorum https://github.com/hackorum-dev/postgres.gitthen, for this patchset and every later one:
git fetch hackorum t254292_1 && git checkout t254292_1Patchset v1 (message #1) is on t254292_1
In https://www.postgresql.org/docs/18/functions-math.html#FUNCTIONS-MATH-RANDOM-TABLE
is stated:
random ( ) → double precision
Returns a random value in the range 0.0 <= x < 1.0
random() → 0.897124072839091
random ( min integer, max integer ) → integer
random ( min bigint, max bigint ) → bigint
random ( min numeric, max numeric ) → numeric
Returns a random value in the range min <= x <= max. For type numeric,
the result will have the same number of fractional decimal digits as
min or max, whichever has more.
random(1, 10) → 7
random(-0.499, 0.499) → 0.347
random_normal ( [ mean double precision [, stddev double precision ]]
) → double precision
Returns a random value from the normal distribution with the given
parameters; mean defaults to 0.0 and stddev defaults to 1.0
random_normal(0.0, 1.0) → 0.051285419
The probabilistic distribution used in random() and random(min, max)
is not stated (whereas in random_normal() is).
Google AI pointed me here as the source of the functions:
https://doxygen.postgresql.org/pg__prng_8c_source.html
If this is true (please someone more knowledgeable confirm), the
distribution is stated in the doc in the source as Uniform.
Given this, the "general" doc should reflect this as it is more
accurate and makes it more useful (last IMO).
The attached patch aligns the "general" doc with the "source" doc in this.
There's another random function for dates and related in version 19:
https://www.postgresql.org/docs/19/functions-datetime.html#FUNCTIONS-DATETIME-TABLE
from what I infer from reading here:
/messages/by-id/2161235.1756479428@sss.pgh.pa.us
it builds on the random math function and the correction should also
be applied here.
There's another function that relies on random numbers, uuid4 and
gen_random_uuid:
https://www.postgresql.org/docs/18/functions-uuid.html
but this precision can't be made since the random numbers are taken
from external sources.
I hope you find this correct and useful and it can be made part of a
larger patch of minor polishing on docs to be submitted eventually.
Comments are welcome.
Cheers,
Rodrigo
On Tue, Oct 20, 2026 at 8:40 AM Matemática A3K <matematica.a3k@gmail.com>
wrote:
The probabilistic distribution used in random() and random(min, max)
is not stated (whereas in random_normal() is).
The docs make the, IMO, reasonable assumption that "all values have an
equal chance of appearing" is what people understand by a simple "random"
selection procedure. Calling it uniform when the target audience may not
usually be exposed to the terminology is not necessarily helpful here.
David J.
On Tue, Oct 20, 2026 at 2:10 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
On Tue, Oct 20, 2026 at 8:40 AM Matemática A3K <matematica.a3k@gmail.com> wrote:
The probabilistic distribution used in random() and random(min, max)
is not stated (whereas in random_normal() is).The docs make the, IMO, reasonable assumption that "all values have an equal chance of appearing" is what people understand by a simple "random" selection procedure. Calling it uniform when the target audience may not usually be exposed to the terminology is not necessarily helpful here.
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.
On Wed, Oct 21, 2026 at 3:54 AM Matemática A3K <matematica.a3k@gmail.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.
Regards,
--
Fujii Masao
On Tuesday, October 20, 2026, Fujii Masao <masao.fujii@gmail.com> wrote:
On Wed, Oct 21, 2026 at 3:54 AM Matemática A3K <matematica.a3k@gmail.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. The fact that
normal_uniform doesn’t actually exist because an unqualified random is
conventionally drawn without any bias to a particular value.
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.
David J.
On Tue, Oct 20, 2026 at 11:06 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
On Tuesday, October 20, 2026, Fujii Masao <masao.fujii@gmail.com> wrote:
On Wed, Oct 21, 2026 at 3:54 AM Matemática A3K <matematica.a3k@gmail.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;"
?
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;"
?
- "Returns a value sampled from the range 0.0 <= x < 1.0 using a
uniform probability distribution"
- "Returns a value sampled from the range min <= x <= max using a
uniform probability distribution"
- "Returns a value sampled from the range -infinity < x < infinity
using a normal probability distribution with the given parameters,..."
?