[Minor] Improvement on random functions doc

From: Matemática A3K <matematica(dot)a3k(at)gmail(dot)com>
To: "pgsql-docs(at)lists(dot)postgresql(dot)org" <pgsql-docs(at)lists(dot)postgresql(dot)org>
Subject: [Minor] Improvement on random functions doc
Date: 2026-10-20 15:40:40
Message-ID: CA+FDnhJJU33yD2op38bQVZyORPH0LkmKb8m28moUfZde0vOQeQ@mail.gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-docs

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:
https://www.postgresql.org/message-id/flat/2161235.1756479428%40sss.pgh.pa.us#59959fb9783cbc6dcd89699e2c4d4b28
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

Attachment Content-Type Size
0001_doc_random_imp.patch text/x-patch 1.4 KB

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message David G. Johnston 2026-10-20 17:09:50 Re: [Minor] Improvement on random functions doc
Previous Message Matemática A3K 2026-10-19 12:49:07 Re: [Minor] Possible missing syntax