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 common subexpression elimination such that two different executions within a row of the same random function return different random values.
Related content
The random numbers are generated by non-cryptographic algorithms.
rand
Returns a random UInt32 number with uniform distribution.
Uses a linear congruential generator with an initial state obtained from the system, which means that while it appears random, it's not truly random and can be predictable if the initial state is known. For scenarios where true randomness is crucial, consider using alternative methods like system-level calls or integrating with external libraries.
Syntax
Alias: rand32
Arguments
None.
Returned value
Returns a number of type UInt32.
Example
rand64
Returns a random UInt64 integer (UInt64) number
Syntax
Arguments
None.
Arguments
Returns a number UInt64 number with uniform distribution.
Uses a linear congruential generator with an initial state obtained from the system, which means that while it appears random, it's not truly random and can be predictable if the initial state is known. For scenarios where true randomness is crucial, consider using alternative methods like system-level calls or integrating with external libraries.
Example
randCanonical
Returns a random Float64 number.
Syntax
Arguments
None.
Arguments
Returns a Float64 value between 0 (inclusive) and 1 (exclusive).
Example
randConstant
Generates a single constant column filled with a random value. Unlike rand
, this function ensures the same random value appears in every row of the generated column, making it useful for scenarios requiring a consistent random seed across rows in a single query.
Syntax
Arguments
- [x] (Optional): An optional expression that influences the generated random value. Even if provided, the resulting value will still be constant within the same query execution. Different queries using the same expression will likely generate different constant values.
Arguments
Returns a column of type UInt32 containing the same random value in each row.
Implementation details
The actual output will be different for each query execution, even with the same optional expression. The optional parameter may not significantly change the generated value compared to using randConstant
alone.
Example
randUniform
Returns a random Float64 drawn uniformly from interval [min
, max
].
Syntax
Arguments
min
-Float64
- left boundary of the range,max
-Float64
- right boundary of the range.
Returned value
A random number of type Float64.
Example
randNormal
Returns a random Float64 drawn from a normal distribution.
Syntax
Arguments
mean
-Float64
- mean value of distribution,stddev
-Float64
- standard deviation of the distribution.
Returned value
- Random number. Float64.
Example
Result:
randLogNormal
Returns a random Float64 drawn from a log-normal distribution.
Syntax
Arguments
mean
-Float64
- mean value of distribution,stddev
-Float64
- standard deviation of the distribution.
Returned value
- Random number. Float64.
Example
Result:
randBinomial
Returns a random UInt64 drawn from a binomial distribution.
Syntax
Arguments
experiments
-UInt64
- number of experiments,probability
-Float64
- probability of success in each experiment, a value between 0 and 1.
Returned value
- Random number. UInt64.
Example
Result:
randNegativeBinomial
Returns a random UInt64 drawn from a negative binomial distribution.
Syntax
Arguments
experiments
-UInt64
- number of experiments,probability
-Float64
- probability of failure in each experiment, a value between 0 and 1.
Returned value
- Random number. UInt64.
Example
Result:
randPoisson
Returns a random UInt64 drawn from a Poisson distribution.
Syntax
Arguments
n
-UInt64
- mean number of occurrences.
Returned value
- Random number. UInt64.
Example
Result:
randBernoulli
Returns a random UInt64 drawn from a Bernoulli distribution.
Syntax
Arguments
probability
-Float64
- probability of success, a value between 0 and 1.
Returned value
- Random number. UInt64.
Example
Result:
randExponential
Returns a random Float64 drawn from a exponential distribution.
Syntax
Arguments
lambda
-Float64
- lambda value.
Returned value
- Random number. Float64.
Example
Result:
randChiSquared
Returns a random Float64 drawn from a Chi-square distribution - a distribution of a sum of the squares of k independent standard normal random variables.
Syntax
Arguments
degree_of_freedom
-Float64
- degree of freedom.
Returned value
- Random number. Float64.
Example
Result:
randStudentT
Returns a random Float64 drawn from a Student's t-distribution.
Syntax
Arguments
degree_of_freedom
-Float64
- degree of freedom.
Returned value
- Random number. Float64.
Example
Result:
randFisherF
Returns a random Float64 drawn from a F-distribution.
Syntax
Arguments
d1
-Float64
- d1 degree of freedom inX = (S1 / d1) / (S2 / d2)
,d2
-Float64
- d2 degree of freedom inX = (S1 / d1) / (S2 / d2)
,
Returned value
- Random number. Float64.
Example
Result:
randomString
Generates a string of the specified length filled with random bytes (including zero bytes). Not all characters may be printable.
Syntax
Arguments
length
— String length in bytes. Positive integer.
Returned value
- String filled with random bytes. String.
Example
Query:
Result:
randomFixedString
Generates a binary string of the specified length filled with random bytes (including zero bytes). Not all characters may be printable.
Syntax
Arguments
length
— String length in bytes. UInt64.
Returned value(s)
- String filled with random bytes. FixedString.
Example
Query:
Result:
randomPrintableASCII
Generates a string with a random set of ASCII characters. All characters are printable.
If you pass length < 0
, the behavior of the function is undefined.
Syntax
Arguments
length
— String length in bytes. Positive integer.
Returned value
Example
randomStringUTF8
Generates a random string of a specified length. Result string contains valid UTF-8 code points. The value of code points may be outside of the range of assigned Unicode.
Syntax
Arguments
length
— Length of the string in code points. UInt64.
Returned value(s)
- UTF-8 random string. String.
Example
Query:
Result:
fuzzBits
Syntax
Flips the bits of String or FixedString s
, each with probability prob
.
Syntax
Arguments
s
-String
orFixedString
,prob
- constantFloat32/64
between 0.0 and 1.0.
Returned value
Fuzzed string with same type as s
.
Example
Result:
fuzzBits
Introduced in: v20.5
Flips the bits of the input string s
, with probability p
for each bit.
Syntax
Arguments
s
— String or FixedString to perform bit fuzzing onString
orFixedString
p
— Probability of flipping each bit as a number between0.0
and1.0
Float*
Returned value
Returns a Fuzzed string with same type as s
. String
or FixedString
Examples
Usage example
rand
Introduced in: v1.1
Returns a random UInt32
number with uniform distribution.
Uses a linear congruential generator with an initial state obtained from the system, which means that while it appears random, it's not truly random and can be predictable if the initial state is known. For scenarios where true randomness is crucial, consider using alternative methods like system-level calls or integrating with external libraries.
Syntax
Arguments
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random number of type UInt32
. UInt32
Examples
Usage example
rand64
Introduced in: v1.1
Returns a random distributed UInt64
number with uniform distribution.
Uses a linear congruential generator with an initial state obtained from the system, which means that while it appears random, it's not truly random and can be predictable if the initial state is known. For scenarios where true randomness is crucial, consider using alternative methods like system-level calls or integrating with external libraries.
Syntax
Arguments
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random UInt64 number with uniform distribution. UInt64
Examples
Usage example
randBernoulli
Introduced in: v22.10
Returns a random Float64 number drawn from a Bernoulli distribution.
Syntax
Arguments
probability
— The probability of success as a value between0
and1
.Float64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified Bernoulli distribution. UInt64
Examples
Usage example
randBinomial
Introduced in: v22.10
Returns a random Float64 number drawn from a binomial distribution.
Syntax
Arguments
experiments
— The number of experimentsUInt64
probability
— The probability of success in each experiment as a value between0
and1
Float64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified binomial distribution. UInt64
Examples
Usage example
randCanonical
Introduced in: v22.11
Returns a random distributed Float64
number with uniform distribution between 0
(inclusive) and 1
(exclusive).
Syntax
Arguments
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number. Float64
Examples
Usage example
randChiSquared
Introduced in: v22.10
Returns a random Float64 number drawn from a chi-square distribution.
Syntax
Arguments
degree_of_freedom
— Degrees of freedom.Float64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified chi-square distribution. Float64
Examples
Usage example
randConstant
Introduced in: v1.1
Generates a single random value that remains constant across all rows in the current query execution.
This function:
- Returns the same random value for every row within a single query
- Produces different values across separate query executions
It is useful for applying consistent random seeds or identifiers across all rows in a dataset
Syntax
Arguments
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a column of type UInt32
containing the same random value in each row. UInt32
Examples
Basic usage
Usage with parameter
randExponential
Introduced in: v22.10
Returns a random Float64 number drawn from an exponential distribution.
Syntax
Arguments
lambda
— Rate parameter or lambda value of the distributionFloat64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified exponential distribution. Float64
Examples
Usage example
randFisherF
Introduced in: v22.10
Returns a random Float64 number drawn from an F-distribution.
Syntax
Arguments
d1
— d1 degree of freedom inX = (S1 / d1) / (S2 / d2)
.Float64
d2
— d2 degree of freedom inX = (S1 / d1) / (S2 / d2)
.Float64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified F-distribution Float64
Examples
Usage example
randLogNormal
Introduced in: v22.10
Returns a random Float64 number drawn from a log-normal distribution.
Syntax
Arguments
mean
— The mean value of distribution.Float64
stddev
— The standard deviation of the distribution.Float64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified log-normal distribution. Float64
Examples
Usage example
randNegativeBinomial
Introduced in: v22.10
Returns a random Float64 number drawn from a negative binomial distribution.
Syntax
Arguments
experiments
— The number of experiments.UInt64
probability
—The probability of failure in each experiment as a value between
0and
1. [
Float64`](/sql-reference/data-types/float)x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified negative binomial distribution UInt64
Examples
Usage example
randNormal
Introduced in: v22.10
Returns a random Float64 number drawn from a normal distribution.
Syntax
Arguments
mean
— The mean value of distributionFloat64
stddev
— The standard deviation of the distributionFloat64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified normal distribution. Float64
Examples
Usage example
randPoisson
Introduced in: v22.10
Returns a random Float64 number drawn from a Poisson distribution distribution.
Syntax
Arguments
n
— The mean number of occurrences.UInt64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified Poisson distribution. UInt64
Examples
Usage example
randStudentT
Introduced in: v22.10
Returns a random Float64 number drawn from a Student's t-distribution.
Syntax
Arguments
degree_of_freedom
— Degrees of freedom.Float64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random Float64 number drawn from the specified Student's t-distribution. Float64
Examples
Usage example
randUniform
Introduced in: v22.10
Returns a random Float64 number drawn uniformly from the interval .
Syntax
Arguments
min
— Left boundary of the range (inclusive).Float64
max
— Right boundary of the range (inclusive).Float64
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a random number drawn uniformly from the interval formed by min
and max
. Float64
Examples
Usage example
randomFixedString
Introduced in: v20.5
Generates a random fixed-size string with the specified number of character. The returned characters are not necessarily ASCII characters, i.e. they may not be printable.
Syntax
Arguments
length
— Length of the string in bytes.UInt*
Returned value
Returns a string filled with random bytes. FixedString
Examples
Usage example
randomPrintableASCII
Introduced in: v20.1
Generates a random ASCII string with the specified number of characters.
If you pass length < 0
, the behavior of the function is undefined.
Syntax
Arguments
length
— String length in bytes.(U)Int*
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a string with a random set of ASCII printable characters. String
Examples
Usage example
randomString
Introduced in: v20.5
Generates a random string with the specified number of characters. The returned characters are not necessarily ASCII characters, i.e. they may not be printable.
Syntax
Arguments
length
— Length of the string in bytes.(U)Int*
x
— Optional and ignored. The only purpose of the argument is to prevent common subexpression elimination when the same function call is used multiple times in a query.Any
Returned value
Returns a string filled with random bytes. String
Examples
Usage example
randomStringUTF8
Introduced in: v20.5
Generates a random UTF-8 string with the specified number of codepoints. No codepoints from unassigned planes (planes 4 to 13) are returned. It is still possible that the client interacting with ClickHouse server is not able to display the produced UTF-8 string correctly.
Syntax
Arguments
length
— Length of the string in code points.(U)Int*
Returned value
Returns a string filled with random UTF-8 codepoints. String
Examples
Usage example