ClickHouse/docs/en/sql-reference/functions/random-functions.md

slug	sidebar_position	sidebar_label
/en/sql-reference/functions/random-functions	145	Random Numbers

Functions for Generating Random Numbers

All functions in this section accept zero or one arguments. The only use of the argument (if provided) is to prevent prevent common subexpression elimination such that two different execution of the same random function in a query return different random values.

Related content

• Blog: Generating random data in ClickHouse

:::note The random numbers are generated by non-cryptographic algorithms. :::

rand, rand32

Returns a random UInt32 number, evenly distributed accross the range of all possible UInt32 numbers.

Uses a linear congruential generator.

rand64

Returns a random UInt64 number, evenly distributed accross the range of all possible UInt64 numbers.

Uses a linear congruential generator.

randCanonical

Returns a Float64 value, evenly distributed in [0, 1).

randConstant

Like rand but produces a constant column with a random value.

Example

SELECT rand(), rand(1), rand(number), randConstant(), randConstant(1), randConstant(number)
FROM numbers(3)

Result:

┌─────rand()─┬────rand(1)─┬─rand(number)─┬─randConstant()─┬─randConstant(1)─┬─randConstant(number)─┐
│ 3047369878 │ 4132449925 │   4044508545 │     2740811946 │      4229401477 │           1924032898 │
│ 2938880146 │ 1267722397 │   4154983056 │     2740811946 │      4229401477 │           1924032898 │
│  956619638 │ 4238287282 │   1104342490 │     2740811946 │      4229401477 │           1924032898 │
└────────────┴────────────┴──────────────┴────────────────┴─────────────────┴──────────────────────┘

Functions for Generating Random Numbers based on a Distribution

randUniform

Returns a Float64 drawn uniformly from the interval between min and max (continuous uniform distribution).

Syntax

randUniform(min, max)

Arguments

• min - Float64 - min value of the range,
• max - Float64 - max value of the range.

Returned value

• Random number.

Type: Float64.

Example

SELECT randUniform(5.5, 10) FROM numbers(5)

Result:

┌─randUniform(5.5, 10)─┐
│    8.094978491443102 │
│   7.3181248914450885 │
│    7.177741903868262 │
│    6.483347380953762 │
│    6.122286382885112 │
└──────────────────────┘

randNormal

Returns a Float64 drawn from a normal distribution.

Syntax

randNormal(mean, variance)

Arguments

• mean - Float64 - mean value of distribution,
• variance - Float64 - variance.

Returned value

• Random number.

Type: Float64.

Example

SELECT randNormal(10, 2) FROM numbers(5)

Result:

┌──randNormal(10, 2)─┐
│ 13.389228911709653 │
│  8.622949707401295 │
│ 10.801887062682981 │
│ 4.5220192605895315 │
│ 10.901239123982567 │
└────────────────────┘

randLogNormal

Returns a Float64 drawn from a log-normal distribution.

Syntax

randLogNormal(mean, variance)

Arguments

• mean - Float64 - mean value of distribution,
• variance - Float64 - variance.

Returned value

• Random number.

Type: Float64.

Example

SELECT randLogNormal(100, 5) FROM numbers(5)

Result:

┌─randLogNormal(100, 5)─┐
│  1.295699673937363e48 │
│  9.719869109186684e39 │
│  6.110868203189557e42 │
│  9.912675872925529e39 │
│ 2.3564708490552458e42 │
└───────────────────────┘

randBinomial

Returns a UInt64 drawn from a binomial distribution.

Syntax

randBinomial(experiments, probability)

Arguments

• experiments - UInt64 - number of experiments,
• probability - Float64 - probability of success in each experiment (values in 0...1 range only).

Returned value

• Random number.

Type: UInt64.

Example

SELECT randBinomial(100, .75) FROM numbers(5)

Result:

┌─randBinomial(100, 0.75)─┐
│                      74 │
│                      78 │
│                      76 │
│                      77 │
│                      80 │
└─────────────────────────┘

randNegativeBinomial

Returns a UInt64 drawn from a negative binomial distribution.

Syntax

randNegativeBinomial(experiments, probability)

Arguments

• experiments - UInt64 - number of experiments,
• probability - Float64 - probability of failure in each experiment (values in 0...1 range only).

Returned value

• Random number.

Type: UInt64.

Example

SELECT randNegativeBinomial(100, .75) FROM numbers(5)

Result:

┌─randNegativeBinomial(100, 0.75)─┐
│                              33 │
│                              32 │
│                              39 │
│                              40 │
│                              50 │
└─────────────────────────────────┘

randPoisson

Returns a UInt64 drawn from a Poisson distribution.

Syntax

randPoisson(n)

Arguments

• n - UInt64 - mean number of occurrences.

Returned value

• Random number.

Type: UInt64.

Example

SELECT randPoisson(10) FROM numbers(5)

Result:

┌─randPoisson(10)─┐
│               8 │
│               8 │
│               7 │
│              10 │
│               6 │
└─────────────────┘

randBernoulli

Returns a UInt64 drawn from a Bernoulli distribution.

Syntax

randBernoulli(probability)

Arguments

• probability - Float64 - probability of success (values in 0...1 range only).

Returned value

• Random number.

Type: UInt64.

Example

SELECT randBernoulli(.75) FROM numbers(5)

Result:

┌─randBernoulli(0.75)─┐
│                   1 │
│                   1 │
│                   0 │
│                   1 │
│                   1 │
└─────────────────────┘

randExponential

Returns a Float64 drawn from a exponential distribution.

Syntax

randExponential(lambda)

Arguments

• lambda - Float64 - lambda value.

Returned value

• Random number.

Type: Float64.

Example

SELECT randExponential(1/10) FROM numbers(5)

Result:

┌─randExponential(divide(1, 10))─┐
│              44.71628934340778 │
│              4.211013337903262 │
│             10.809402553207766 │
│              15.63959406553284 │
│             1.8148392319860158 │
└────────────────────────────────┘

randChiSquared

Returns a Float64 drawn from a Chi-square distribution - a distribution of a sum of the squares of k independent standard normal random variables.

Syntax

randChiSquared(degree_of_freedom)

Arguments

• degree_of_freedom - Float64 - degree of freedom.

Returned value

• Random number.

Type: Float64.

Example

SELECT randChiSquared(10) FROM numbers(5)

Result:

┌─randChiSquared(10)─┐
│ 10.015463656521543 │
│  9.621799919882768 │
│   2.71785015634699 │
│ 11.128188665931908 │
│  4.902063104425469 │
└────────────────────┘

randStudentT

Returns a Float64 drawn from a Student's t-distribution.

Syntax

randStudentT(degree_of_freedom)

Arguments

• degree_of_freedom - Float64 - degree of freedom.

Returned value

• Random number.

Type: Float64.

Example

SELECT randStudentT(10) FROM numbers(5)

Result:

┌─────randStudentT(10)─┐
│   1.2217309938538725 │
│   1.7941971681200541 │
│ -0.28192176076784664 │
│   0.2508897721303792 │
│  -2.7858432909761186 │
└──────────────────────┘

randFisherF

Returns a Float64 drawn from a F-distribution.

Syntax

randFisherF(d1, d2)

Arguments

• d1 - Float64 - d1 degree of freedom in X = (S1 / d1) / (S2 / d2),
• d2 - Float64 - d2 degree of freedom in X = (S1 / d1) / (S2 / d2),

Returned value

• Random number.

Type: Float64.

Example

SELECT randFisherF(10, 3) FROM numbers(5)

Result:

┌──randFisherF(10, 3)─┐
│   7.286287504216609 │
│ 0.26590779413050386 │
│ 0.22207610901168987 │
│  0.7953362728449572 │
│ 0.19278885985221572 │
└─────────────────────┘

Functions for Generating Random Strings

randomString

Returns a random String of specified length. Not all characters may be printable.

Syntax

randomString(length)

randomFixedString

Like randomString but returns a FixedString.

randomPrintableASCII

Returns a random String of specified length. All characters are printable.

Syntax

randomPrintableASCII(length)

randomStringUTF8

Returns a random String containing length many UTF8 codepoints. Not all characters may be printable

Syntax

randomStringUTF8(length)

fuzzBits

Syntax

Inverts the bits of String or FixedString s, each with probability prob.

Syntax

fuzzBits(s, prob)

Arguments

• s - String or FixedString
• prob - constant Float32/64

Returned value

Fuzzed string with same type as s.

Example

SELECT fuzzBits(materialize('abacaba'), 0.1)
FROM numbers(3)

Result:

┌─fuzzBits(materialize('abacaba'), 0.1)─┐
│ abaaaja                               │
│ a*cjab+                               │
│ aeca2A                                │
└───────────────────────────────────────┘