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

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

761 lines
16 KiB
Markdown
Raw Normal View History

2020-04-03 13:23:32 +00:00
---
2022-08-28 14:53:34 +00:00
slug: /en/sql-reference/functions/random-functions
2023-04-19 17:05:55 +00:00
sidebar_position: 145
sidebar_label: Random Numbers
2020-04-03 13:23:32 +00:00
---
2023-04-19 17:05:55 +00:00
# Functions for Generating Random Numbers
2023-11-16 20:07:49 +00:00
All functions in this section accept zero or one arguments. The only use of the argument (if provided) is to prevent [common subexpression
elimination](../../sql-reference/functions/index.md#common-subexpression-elimination) such that two different executions within a row of the same random
function return different random values.
2017-04-03 19:49:50 +00:00
2023-04-19 18:03:01 +00:00
Related content
2023-04-19 18:03:01 +00:00
- Blog: [Generating random data in ClickHouse](https://clickhouse.com/blog/generating-random-test-distribution-data-for-clickhouse)
:::note
The random numbers are generated by non-cryptographic algorithms.
:::
2017-04-03 19:49:50 +00:00
## rand
2024-03-11 08:34:01 +00:00
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
```sql
rand()
```
2024-03-11 08:34:01 +00:00
Alias: `rand32`
### Arguments
None.
2024-03-11 08:34:01 +00:00
### Returned value
Returns a number of type UInt32.
### Example
```sql
2024-03-03 21:38:59 +00:00
SELECT rand();
```
```response
2024-03-11 08:34:01 +00:00
1569354847 -- Note: The actual output will be a random number, not the specific number shown in the example
```
2022-06-02 10:55:18 +00:00
## rand64
2024-03-11 08:34:01 +00:00
Returns a random UInt64 integer (UInt64) number
2020-06-19 10:12:59 +00:00
### Syntax
```sql
rand64()
```
2024-03-11 08:34:01 +00:00
### Arguments
None.
2024-03-11 08:34:01 +00:00
### Returned value
2024-03-11 08:34:01 +00:00
Returns a number UInt64 number with uniform distribution.
2024-03-11 08:34:01 +00:00
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.
2024-03-03 21:38:59 +00:00
### Example
```sql
SELECT rand64();
```
```response
2024-03-11 08:34:01 +00:00
15030268859237645412 -- Note: The actual output will be a random number, not the specific number shown in the example.
```
2022-11-17 10:17:27 +00:00
## randCanonical
2024-03-11 08:34:01 +00:00
Returns a random Float64 number.
### Syntax
```sql
randCanonical()
```
2024-03-11 08:34:01 +00:00
### Arguments
None.
2024-03-11 08:34:01 +00:00
### Returned value
Returns a Float64 value between 0 (inclusive) and 1 (exclusive).
### Example
```sql
SELECT randCanonical();
```
```response
2024-03-11 08:34:01 +00:00
0.3452178901234567 - Note: The actual output will be a random Float64 number between 0 and 1, not the specific number shown in the example.
```
2022-06-02 10:55:18 +00:00
## randConstant
2024-03-11 08:34:01 +00:00
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
```sql
randConstant([x]);
```
2024-03-11 08:34:01 +00:00
### 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.
2024-03-11 08:34:01 +00:00
### Returned value
Returns a column of type UInt32 containing the same random value in each row.
2024-03-03 21:38:59 +00:00
### 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.
### Examples
```sql
SELECT randConstant() AS random_value;
```
```response
| random_value |
|--------------|
| 1234567890 |
```
```sql
SELECT randConstant(10) AS random_value;
```
```response
| random_value |
|--------------|
| 9876543210 |
```
## randUniform
Returns a random Float64 drawn uniformly from interval [`min`, `max`].
### Syntax
```sql
randUniform(min, max)
```
2024-03-11 08:34:01 +00:00
### Arguments
2023-06-01 18:27:34 +00:00
- `min` - `Float64` - left boundary of the range,
2023-06-02 14:00:57 +00:00
- `max` - `Float64` - right boundary of the range.
2024-03-11 08:34:01 +00:00
### Returned value
2023-04-19 20:04:59 +00:00
A random number of type [Float64](/docs/en/sql-reference/data-types/float.md).
### Example
```sql
SELECT randUniform(5.5, 10) FROM numbers(5)
```
```response
┌─randUniform(5.5, 10)─┐
│ 8.094978491443102 │
│ 7.3181248914450885 │
│ 7.177741903868262 │
│ 6.483347380953762 │
│ 6.122286382885112 │
└──────────────────────┘
```
## randNormal
2023-06-01 18:27:34 +00:00
Returns a random Float64 drawn from a [normal distribution](https://en.wikipedia.org/wiki/Normal_distribution).
**Syntax**
```sql
2023-04-19 18:03:01 +00:00
randNormal(mean, variance)
```
**Arguments**
2023-04-19 18:03:01 +00:00
- `mean` - `Float64` - mean value of distribution,
2023-06-01 18:27:34 +00:00
- `variance` - `Float64` - [variance](https://en.wikipedia.org/wiki/Variance) of the distribution.
**Returned value**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [Float64](/docs/en/sql-reference/data-types/float.md).
**Example**
```sql
SELECT randNormal(10, 2) FROM numbers(5)
```
Result:
```result
┌──randNormal(10, 2)─┐
│ 13.389228911709653 │
│ 8.622949707401295 │
│ 10.801887062682981 │
│ 4.5220192605895315 │
│ 10.901239123982567 │
└────────────────────┘
```
## randLogNormal
2023-06-01 18:27:34 +00:00
Returns a random Float64 drawn from a [log-normal distribution](https://en.wikipedia.org/wiki/Log-normal_distribution).
**Syntax**
```sql
2023-04-19 18:03:01 +00:00
randLogNormal(mean, variance)
```
**Arguments**
2023-04-19 18:03:01 +00:00
- `mean` - `Float64` - mean value of distribution,
2023-06-01 18:27:34 +00:00
- `variance` - `Float64` - [variance](https://en.wikipedia.org/wiki/Variance) of the distribution.
**Returned value**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [Float64](/docs/en/sql-reference/data-types/float.md).
**Example**
```sql
SELECT randLogNormal(100, 5) FROM numbers(5)
```
Result:
```result
┌─randLogNormal(100, 5)─┐
│ 1.295699673937363e48 │
│ 9.719869109186684e39 │
│ 6.110868203189557e42 │
│ 9.912675872925529e39 │
│ 2.3564708490552458e42 │
└───────────────────────┘
```
## randBinomial
2023-06-01 18:27:34 +00:00
Returns a random UInt64 drawn from a [binomial distribution](https://en.wikipedia.org/wiki/Binomial_distribution).
**Syntax**
```sql
randBinomial(experiments, probability)
```
**Arguments**
2023-04-19 18:03:01 +00:00
- `experiments` - `UInt64` - number of experiments,
2023-06-01 18:27:34 +00:00
- `probability` - `Float64` - probability of success in each experiment, a value between 0 and 1.
**Returned value**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
**Example**
```sql
SELECT randBinomial(100, .75) FROM numbers(5)
```
Result:
```result
┌─randBinomial(100, 0.75)─┐
│ 74 │
│ 78 │
│ 76 │
│ 77 │
│ 80 │
└─────────────────────────┘
```
## randNegativeBinomial
2023-06-01 18:27:34 +00:00
Returns a random UInt64 drawn from a [negative binomial distribution](https://en.wikipedia.org/wiki/Negative_binomial_distribution).
**Syntax**
```sql
randNegativeBinomial(experiments, probability)
```
**Arguments**
2023-04-19 18:03:01 +00:00
- `experiments` - `UInt64` - number of experiments,
2023-06-01 18:27:34 +00:00
- `probability` - `Float64` - probability of failure in each experiment, a value between 0 and 1.
**Returned value**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
**Example**
```sql
SELECT randNegativeBinomial(100, .75) FROM numbers(5)
```
Result:
```result
┌─randNegativeBinomial(100, 0.75)─┐
│ 33 │
│ 32 │
│ 39 │
│ 40 │
│ 50 │
└─────────────────────────────────┘
```
## randPoisson
2023-06-01 18:27:34 +00:00
Returns a random UInt64 drawn from a [Poisson distribution](https://en.wikipedia.org/wiki/Poisson_distribution).
**Syntax**
```sql
randPoisson(n)
```
**Arguments**
2023-04-19 18:03:01 +00:00
- `n` - `UInt64` - mean number of occurrences.
**Returned value**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
**Example**
```sql
SELECT randPoisson(10) FROM numbers(5)
```
Result:
```result
┌─randPoisson(10)─┐
│ 8 │
│ 8 │
│ 7 │
│ 10 │
│ 6 │
└─────────────────┘
```
## randBernoulli
2023-06-01 18:27:34 +00:00
Returns a random UInt64 drawn from a [Bernoulli distribution](https://en.wikipedia.org/wiki/Bernoulli_distribution).
**Syntax**
```sql
randBernoulli(probability)
```
**Arguments**
2023-06-01 18:27:34 +00:00
- `probability` - `Float64` - probability of success, a value between 0 and 1.
**Returned value**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [UInt64](/docs/en/sql-reference/data-types/int-uint.md).
**Example**
```sql
SELECT randBernoulli(.75) FROM numbers(5)
```
Result:
```result
┌─randBernoulli(0.75)─┐
│ 1 │
│ 1 │
│ 0 │
│ 1 │
│ 1 │
└─────────────────────┘
```
## randExponential
2023-06-01 18:27:34 +00:00
Returns a random Float64 drawn from a [exponential distribution](https://en.wikipedia.org/wiki/Exponential_distribution).
**Syntax**
```sql
randExponential(lambda)
```
**Arguments**
2023-04-19 18:03:01 +00:00
- `lambda` - `Float64` - lambda value.
**Returned value**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [Float64](/docs/en/sql-reference/data-types/float.md).
**Example**
```sql
SELECT randExponential(1/10) FROM numbers(5)
```
Result:
```result
┌─randExponential(divide(1, 10))─┐
│ 44.71628934340778 │
│ 4.211013337903262 │
│ 10.809402553207766 │
│ 15.63959406553284 │
│ 1.8148392319860158 │
└────────────────────────────────┘
```
## randChiSquared
2023-06-01 18:27:34 +00:00
Returns a random Float64 drawn from a [Chi-square distribution](https://en.wikipedia.org/wiki/Chi-squared_distribution) - a distribution of a sum of the squares of k independent standard normal random variables.
**Syntax**
```sql
randChiSquared(degree_of_freedom)
```
**Arguments**
2023-04-19 18:03:01 +00:00
- `degree_of_freedom` - `Float64` - degree of freedom.
**Returned value**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [Float64](/docs/en/sql-reference/data-types/float.md).
**Example**
```sql
SELECT randChiSquared(10) FROM numbers(5)
```
Result:
```result
┌─randChiSquared(10)─┐
│ 10.015463656521543 │
│ 9.621799919882768 │
│ 2.71785015634699 │
│ 11.128188665931908 │
│ 4.902063104425469 │
└────────────────────┘
```
## randStudentT
2023-06-01 18:27:34 +00:00
Returns a random Float64 drawn from a [Student's t-distribution](https://en.wikipedia.org/wiki/Student%27s_t-distribution).
**Syntax**
```sql
randStudentT(degree_of_freedom)
```
**Arguments**
2023-04-19 18:03:01 +00:00
- `degree_of_freedom` - `Float64` - degree of freedom.
**Returned value**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [Float64](/docs/en/sql-reference/data-types/float.md).
**Example**
```sql
SELECT randStudentT(10) FROM numbers(5)
```
Result:
```result
┌─────randStudentT(10)─┐
│ 1.2217309938538725 │
│ 1.7941971681200541 │
│ -0.28192176076784664 │
│ 0.2508897721303792 │
│ -2.7858432909761186 │
└──────────────────────┘
```
## randFisherF
2023-06-01 18:27:34 +00:00
Returns a random Float64 drawn from a [F-distribution](https://en.wikipedia.org/wiki/F-distribution).
**Syntax**
```sql
randFisherF(d1, d2)
```
**Arguments**
2023-04-19 18:03:01 +00:00
- `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**
2023-04-19 20:04:59 +00:00
- Random number.
Type: [Float64](/docs/en/sql-reference/data-types/float.md).
**Example**
```sql
SELECT randFisherF(10, 3) FROM numbers(5)
```
Result:
```result
┌──randFisherF(10, 3)─┐
│ 7.286287504216609 │
│ 0.26590779413050386 │
│ 0.22207610901168987 │
│ 0.7953362728449572 │
│ 0.19278885985221572 │
└─────────────────────┘
```
2023-09-18 17:34:40 +00:00
## randomString {#randomString}
2023-06-01 18:27:34 +00:00
Generates a string of the specified length filled with random bytes (including zero bytes). Not all characters may be printable.
2023-04-19 18:03:01 +00:00
**Syntax**
2020-05-29 02:06:21 +00:00
```sql
2023-04-19 18:03:01 +00:00
randomString(length)
```
2020-05-29 02:06:21 +00:00
2023-06-01 18:27:34 +00:00
**Arguments**
- `length` — String length in bytes. Positive integer.
**Returned value**
- String filled with random bytes.
Type: [String](../../sql-reference/data-types/string.md).
**Example**
Query:
```sql
2023-06-01 18:27:34 +00:00
SELECT randomString(30) AS str, length(str) AS len FROM numbers(2) FORMAT Vertical;
```
Result:
```text
2023-06-01 18:27:34 +00:00
Row 1:
──────
str: 3 G : pT ?w тi k aV f6
len: 30
Row 2:
──────
str: 9 ,] ^ ) ]?? 8
len: 30
```
2022-06-02 10:55:18 +00:00
## randomFixedString
2020-05-29 02:06:21 +00:00
2023-06-01 18:27:34 +00:00
Generates a binary string of the specified length filled with random bytes (including zero bytes). Not all characters may be printable.
**Syntax**
```sql
2023-06-01 18:27:34 +00:00
randomFixedString(length);
```
**Arguments**
- `length` — String length in bytes. [UInt64](../../sql-reference/data-types/int-uint.md).
**Returned value(s)**
- String filled with random bytes.
Type: [FixedString](../../sql-reference/data-types/fixedstring.md).
**Example**
Query:
```sql
SELECT randomFixedString(13) as rnd, toTypeName(rnd)
```
Result:
```text
┌─rnd──────┬─toTypeName(randomFixedString(13))─┐
│ j▒h㋖HɨZ'▒ │ FixedString(13) │
└──────────┴───────────────────────────────────┘
```
2023-04-19 18:03:01 +00:00
2022-06-02 10:55:18 +00:00
## randomPrintableASCII
2020-05-29 02:06:21 +00:00
2023-06-01 18:27:34 +00:00
Generates a string with a random set of [ASCII](https://en.wikipedia.org/wiki/ASCII#Printable_characters) characters. All characters are printable.
If you pass `length < 0`, the behavior of the function is undefined.
2023-04-19 18:03:01 +00:00
**Syntax**
```sql
2023-04-19 18:03:01 +00:00
randomPrintableASCII(length)
```
2023-06-01 18:27:34 +00:00
**Arguments**
- `length` — String length in bytes. Positive integer.
**Returned value**
- String with a random set of [ASCII](https://en.wikipedia.org/wiki/ASCII#Printable_characters) printable characters.
Type: [String](../../sql-reference/data-types/string.md)
**Example**
```sql
2023-06-01 18:27:34 +00:00
SELECT number, randomPrintableASCII(30) as str, length(str) FROM system.numbers LIMIT 3
```
```text
2023-06-01 18:27:34 +00:00
┌─number─┬─str────────────────────────────┬─length(randomPrintableASCII(30))─┐
│ 0 │ SuiCOSTvC0csfABSw=UcSzp2.`rv8x │ 30 │
│ 1 │ 1Ag NlJ &RCN:*>HVPG;PE-nO"SUFD │ 30 │
│ 2 │ /"+<"wUTh:=LjJ Vm!c&hI*m#XTfzz │ 30 │
└────────┴────────────────────────────────┴──────────────────────────────────┘
```
2022-06-02 10:55:18 +00:00
## randomStringUTF8
2020-05-29 02:06:21 +00:00
2023-06-01 18:27:34 +00:00
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.
2023-04-19 18:03:01 +00:00
**Syntax**
```sql
2023-06-01 18:27:34 +00:00
randomStringUTF8(length);
```
**Arguments**
- `length` — Length of the string in code points. [UInt64](../../sql-reference/data-types/int-uint.md).
**Returned value(s)**
- UTF-8 random string.
Type: [String](../../sql-reference/data-types/string.md).
**Example**
Query:
2023-04-19 18:03:01 +00:00
```sql
2023-06-01 18:27:34 +00:00
SELECT randomStringUTF8(13)
```
Result:
```text
┌─randomStringUTF8(13)─┐
│ 𘤗𙉝д兠庇󡅴󱱎󦐪􂕌𔊹𓰛 │
└──────────────────────┘
2023-04-19 18:03:01 +00:00
```
2023-09-18 17:34:40 +00:00
## fuzzBits {#fuzzBits}
2020-05-29 02:06:21 +00:00
**Syntax**
2023-06-01 18:27:34 +00:00
Flips the bits of String or FixedString `s`, each with probability `prob`.
2023-04-19 18:03:01 +00:00
**Syntax**
```sql
2023-04-19 18:03:01 +00:00
fuzzBits(s, prob)
2020-05-29 02:06:21 +00:00
```
**Arguments**
2023-06-01 18:27:34 +00:00
- `s` - `String` or `FixedString`,
- `prob` - constant `Float32/64` between 0.0 and 1.0.
2020-05-29 02:06:21 +00:00
**Returned value**
2023-04-19 18:03:01 +00:00
Fuzzed string with same type as `s`.
2020-05-29 02:06:21 +00:00
**Example**
```sql
2020-05-29 02:06:21 +00:00
SELECT fuzzBits(materialize('abacaba'), 0.1)
FROM numbers(3)
```
2022-05-20 00:16:27 +00:00
Result:
```result
2022-05-20 00:16:27 +00:00
┌─fuzzBits(materialize('abacaba'), 0.1)─┐
│ abaaaja │
│ a*cjab+ │
│ aeca2A │
2020-05-29 02:06:21 +00:00
└───────────────────────────────────────┘
2022-05-20 00:16:27 +00:00
```