> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 用于生成随机数的函数文档

# 生成随机数的函数

本节中的所有函数都接受零个或一个参数。该参数 (如果提供) 的唯一作用是防止[公共子表达式消除
](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)，从而确保同一随机
函数在同一行中的两次不同调用会返回不同的随机值。

相关内容

* 指南：[在 ClickHouse 中生成随机数据](/zh/guides/clickhouse/data-modelling/generating-test-data)
* 博客：[在 ClickHouse 中生成随机数据](https://clickhouse.com/blog/generating-random-test-distribution-data-for-clickhouse)

<Note>
  这些随机数由非加密算法生成。
</Note>

<Note>
  下方文档由 `system.functions` 系统表自动生成。
</Note>

{/*AUTOGENERATED_START*/}

<div id="fuzzBits">
  ## fuzzBits
</div>

引入版本：v20.5.0

将输入字符串 `s` 中的每一位以概率 `p` 翻转。

**语法**

```sql theme={null}
fuzzBits(s, p)
```

**参数**

* `s` — 要执行位模糊处理的 [`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
* `p` — 翻转每一位的概率，取值范围为 `0.0` 到 `1.0` [`Float*`](/zh/reference/data-types/float)

**返回值**

返回一个经过模糊处理且与 `s` 类型相同的字符串。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT fuzzBits(materialize('abacaba'), 0.1)
FROM numbers(3)
```

```response title=Response theme={null}
┌─fuzzBits(materialize('abacaba'), 0.1)─┐
│ abaaaja                               │
│ a*cjab+                               │
│ aeca2A                                │
└───────────────────────────────────────┘
```

<div id="rand">
  ## rand
</div>

引入版本：v1.1.0

返回一个服从均匀分布的随机 `UInt32` 数值。

它使用线性同余生成器，初始状态取自系统。这意味着它虽然看起来是随机的，但并非真正随机；如果初始状态已知，结果就可以被预测。
如果场景对真正的随机性要求很高，请考虑使用系统级调用等其他方法，或集成外部库。

**语法**

```sql theme={null}
rand([x])
```

**别名**: `rand32`

**参数**

* `x` — 可选，会被忽略。该参数的唯一作用是在同一查询中多次使用相同的函数调用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个 `UInt32` 类型的随机数。[`UInt32`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT rand();
```

```response title=Response theme={null}
1569354847
```

<div id="rand64">
  ## rand64
</div>

引入版本：v1.1.0

返回一个服从均匀分布的随机 `UInt64` 数值。

它使用线性同余生成器，初始状态取自系统。这意味着它虽然看起来是随机的，但并非真正的随机数；如果已知初始状态，生成结果就可能被预测。
如果场景对真正的随机性要求很高，建议改用系统级调用或集成外部库等其他方法。

**语法**

```sql theme={null}
rand64([x])
```

**参数**

* `x` — 可选，会被忽略。该参数的唯一作用是：当同一查询中多次使用相同的函数调用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个服从均匀分布的随机 UInt64 数值。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT rand64();
```

```response title=Response theme={null}
15030268859237645412
```

<div id="randBernoulli">
  ## randBernoulli
</div>

引入版本：v22.10.0

返回一个从 [伯努利分布](https://en.wikipedia.org/wiki/Bernoulli_distribution) 中抽取的随机 Float64 数。

**语法**

```sql theme={null}
randBernoulli(probability[, x])
```

**参数**

* `probability` — 成功概率，取值介于 `0` 和 `1` 之间。[`Float64`](/zh/reference/data-types/float)
* `x` — 可选，会被忽略。该参数的唯一用途是在同一查询中多次使用相同的函数调用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定伯努利分布中抽样得到的随机 Float64 值。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT randBernoulli(.75) FROM numbers(5)
```

```response title=Response theme={null}
┌─randBernoulli(0.75)─┐
│                   1 │
│                   1 │
│                   0 │
│                   1 │
│                   1 │
└─────────────────────┘
```

<div id="randBinomial">
  ## randBinomial
</div>

引入版本：v22.10.0

返回一个从[二项分布](https://en.wikipedia.org/wiki/Binomial_distribution)中抽样得到的随机 Float64 数值。

**语法**

```sql theme={null}
randBinomial(experiments, probability[, x])
```

**参数**

* `experiments` — 实验次数 [`UInt64`](/zh/reference/data-types/int-uint)
* `probability` — 每次实验成功的概率，取值介于 `0` 和 `1` 之间 [`Float64`](/zh/reference/data-types/float)
* `x` — 可选，会被忽略。此参数的唯一作用，是在同一个查询中多次使用相同的函数调用时，防止[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定二项分布中抽样得到的随机 Float64 数值。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randBinomial(100, .75) FROM numbers(5)
```

```response title=Response theme={null}
┌─randBinomial(100, 0.75)─┐
│                      74 │
│                      78 │
│                      76 │
│                      77 │
│                      80 │
└─────────────────────────┘
```

<div id="randCanonical">
  ## randCanonical
</div>

引入版本：v22.11.0

返回一个随机的 `Float64` 数值，在 `0` (含) 到 `1` (不含) 之间服从均匀分布。

**语法**

```sql theme={null}
randCanonical([x])
```

**参数**

* `x` — 可选，会被忽略。该参数的唯一作用是：当同一查询中多次使用相同的函数调用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个随机的 Float64 值。[`Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randCanonical();
```

```response title=Response theme={null}
0.345217890123456
```

<div id="randChiSquared">
  ## randChiSquared
</div>

引入版本：v22.10.0

返回一个从[卡方分布](https://en.wikipedia.org/wiki/Chi-squared_distribution)中抽取的随机 Float64 数值。

**语法**

```sql theme={null}
randChiSquared(degree_of_freedom[, x])
```

**参数**

* `degree_of_freedom` — 自由度。[`Float64`](/zh/reference/data-types/float)
* `x` — 可选，会被忽略。此参数的唯一作用是当同一函数调用在一个查询中被多次使用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定卡方分布中抽样得到的随机 Float64 数。[`Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randChiSquared(10) FROM numbers(5)
```

```response title=Response theme={null}
┌─randChiSquared(10)─┐
│ 10.015463656521543 │
│  9.621799919882768 │
│   2.71785015634699 │
│ 11.128188665931908 │
│  4.902063104425469 │
└────────────────────┘
```

<div id="randConstant">
  ## randConstant
</div>

首次引入于：v1.1.0

生成一个随机值，并在当前查询执行的所有行中保持不变。

此函数：

* 在单次查询中，对每一行都返回相同的随机值
* 在不同的查询执行之间会生成不同的值

它适用于在数据集的所有行中使用一致的随机种子或标识符

**语法**

```sql theme={null}
randConstant([x])
```

**参数**

* `x` — 可选，且会被忽略。该参数的唯一用途，是防止在查询中多次使用同一个函数调用时发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个类型为 `UInt32` 的列，其中每一行都包含相同的随机值。[`UInt32`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT randConstant() AS random_value;
```

```response title=Response theme={null}
| random_value |
|--------------|
| 1234567890   |
```

**带参数用法**

```sql title=Query theme={null}
SELECT randConstant(10) AS random_value;
```

```response title=Response theme={null}
| random_value |
|--------------|
| 9876543210   |
```

<div id="randExponential">
  ## randExponential
</div>

引入版本：v22.10.0

返回一个服从[指数分布](https://en.wikipedia.org/wiki/Exponential_distribution)的随机 Float64 数。

**语法**

```sql theme={null}
randExponential(lambda[, x])
```

**参数**

* `lambda` — 该分布的速率参数或 lambda 值 [`Float64`](/zh/reference/data-types/float)
* `x` — 可选且会被忽略。此参数的唯一作用是：当同一函数调用在一个查询中使用多次时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定指数分布中抽样得到的随机 Float64 数值。[`Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randExponential(1/10) FROM numbers(5)
```

```response title=Response theme={null}
┌─randExponential(divide(1, 10))─┐
│              44.71628934340778 │
│              4.211013337903262 │
│             10.809402553207766 │
│              15.63959406553284 │
│             1.8148392319860158 │
└────────────────────────────────┘
```

<div id="randFisherF">
  ## randFisherF
</div>

引入版本：v22.10.0

返回一个服从 [F 分布](https://en.wikipedia.org/wiki/F-distribution) 的随机 Float64 数值。

**语法**

```sql theme={null}
randFisherF(d1, d2[, x])
```

**参数**

* `d1` — `X = (S1 / d1) / (S2 / d2)` 中 d1 的自由度。 [`Float64`](/zh/reference/data-types/float)
* `d2` — `X = (S1 / d1) / (S2 / d2)` 中 d2 的自由度。 [`Float64`](/zh/reference/data-types/float)
* `x` — 可选，会被忽略。该参数的唯一作用是在同一函数调用在一个查询中多次使用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。 [`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定 F 分布中抽样得到的随机 Float64 数值 [`Float64`](/zh/reference/data-types/float)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT randFisherF(10, 3) FROM numbers(5)
```

```response title=Response theme={null}
┌─randFisherF(10, 20)─┐
│  0.7204609609506184 │
│  0.9926258472572916 │
│  1.4010752726735863 │
│ 0.34928401507025556 │
│  1.8216216009473598 │
└─────────────────────┘
```

<div id="randLogNormal">
  ## randLogNormal
</div>

自 v22.10.0 引入

返回一个从[对数正态分布](https://en.wikipedia.org/wiki/Log-normal_distribution)中抽样得到的随机 Float64 数。

**语法**

```sql theme={null}
randLogNormal(mean, stddev[, x])
```

**参数**

* `mean` — 分布的均值。[`Float64`](/zh/reference/data-types/float)
* `stddev` — 分布的标准差。[`Float64`](/zh/reference/data-types/float)
* `x` — 可选，会被忽略。此参数的唯一作用是在同一查询中多次使用相同的函数调用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定对数正态分布中随机抽样得到的 Float64 数值。[`Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randLogNormal(100, 5) FROM numbers(5)
```

```response title=Response theme={null}
┌─randLogNormal(100, 5)─┐
│  1.295699673937363e48 │
│  9.719869109186684e39 │
│  6.110868203189557e42 │
│  9.912675872925529e39 │
│ 2.3564708490552458e42 │
└───────────────────────┘
```

<div id="randNegativeBinomial">
  ## randNegativeBinomial
</div>

引入版本：v22.10.0

返回一个服从[负二项分布](https://en.wikipedia.org/wiki/Negative_binomial_distribution)的随机 Float64 数。

**语法**

```sql theme={null}
randNegativeBinomial(experiments, probability[, x])
```

**参数**

* `experiments` — 实验次数。[`UInt64`](/zh/reference/data-types/int-uint)
* `probability` — `每次实验失败的概率，取值介于 `0`和`1` 之间。[`Float64\`]\(/reference/data-types/float)
* `x` — 可选，会被忽略。该参数的唯一作用是在查询中多次使用相同的函数调用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定负二项分布中抽样得到的随机 Float64 数值 [`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT randNegativeBinomial(100, .75) FROM numbers(5)
```

```response title=Response theme={null}
┌─randNegativeBinomial(100, 0.75)─┐
│                              33 │
│                              32 │
│                              39 │
│                              40 │
│                              50 │
└─────────────────────────────────┘
```

<div id="randNormal">
  ## randNormal
</div>

引入版本：v22.10.0

返回一个服从[正态分布](https://en.wikipedia.org/wiki/Normal_distribution)的随机 Float64 数值。

**语法**

```sql theme={null}
randNormal(mean, stddev[, x])
```

**参数**

* `mean` — 分布的均值 [`Float64`](/zh/reference/data-types/float)
* `stddev` — 分布的标准差 [`Float64`](/zh/reference/data-types/float)
* `x` — 可选，会被忽略。该参数的唯一作用是在查询中多次使用相同的函数调用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定正态分布中抽样得到的 Float64 随机数。[`Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randNormal(10, 2) FROM numbers(5)
```

```response title=Response theme={null}
┌──randNormal(10, 2)─┐
│ 13.389228911709653 │
│  8.622949707401295 │
│ 10.801887062682981 │
│ 4.5220192605895315 │
│ 10.901239123982567 │
└────────────────────┘
```

<div id="randPoisson">
  ## randPoisson
</div>

引入版本：v22.10.0

返回一个服从[泊松分布](https://en.wikipedia.org/wiki/Poisson_distribution)的随机 Float64 数。

**语法**

```sql theme={null}
randPoisson(n[, x])
```

**参数**

* `n` — 平均出现次数。[`UInt64`](/zh/reference/data-types/int-uint)
* `x` — 可选，会被忽略。该参数的唯一目的是在同一查询中多次使用相同的函数调用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定泊松分布中抽样得到的随机 Float64 浮点数。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT randPoisson(10) FROM numbers(5)
```

```response title=Response theme={null}
┌─randPoisson(10)─┐
│               8 │
│               8 │
│               7 │
│              10 │
│               6 │
└─────────────────┘
```

<div id="randStudentT">
  ## randStudentT
</div>

引入版本：v22.10.0

返回一个服从 [Student's t-distribution](https://en.wikipedia.org/wiki/Student%27s_t-distribution) 的随机 Float64 数值。

**语法**

```sql theme={null}
randStudentT(degree_of_freedom[, x])
```

**参数**

* `degree_of_freedom` — 自由度。[`Float64`](/zh/reference/data-types/float)
* `x` — 可选，会被忽略。该参数的唯一作用，是防止在同一查询中多次使用相同的函数调用时发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从指定的 Student's t 分布中抽样得到的随机 Float64 数。[`Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randStudentT(10) FROM numbers(5)
```

```response title=Response theme={null}
┌─────randStudentT(10)─┐
│   1.2217309938538725 │
│   1.7941971681200541 │
│ -0.28192176076784664 │
│   0.2508897721303792 │
│  -2.7858432909761186 │
└──────────────────────┘
```

<div id="randUniform">
  ## randUniform
</div>

引入版本：v22.10.0

返回一个从区间 $[\min, \max]$ 中按均匀分布随机抽取的 Float64 数值。

**语法**

```sql theme={null}
randUniform(min, max[, x])
```

**参数**

* `min` — 范围的左边界 (含边界值) 。[`Float64`](/zh/reference/data-types/float)
* `max` — 范围的右边界 (含边界值) 。[`Float64`](/zh/reference/data-types/float)
* `x` — 可选，会被忽略。此参数的唯一作用，是在同一查询中多次使用相同函数调用时，防止发生[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个从由 `min` 和 `max` 构成的区间内按均匀分布抽取的随机数。[`Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randUniform(5.5, 10) FROM numbers(5)
```

```response title=Response theme={null}
┌─randUniform(5.5, 10)─┐
│    8.094978491443102 │
│   7.3181248914450885 │
│    7.177741903868262 │
│    6.483347380953762 │
│    6.122286382885112 │
└──────────────────────┘
```

<div id="randomFixedString">
  ## randomFixedString
</div>

引入版本：v20.5.0

生成一个具有指定字符数的随机定长字符串。
返回的字符不一定是 ASCII 字符，也就是说，它们可能是不可打印的。

**语法**

```sql theme={null}
randomFixedString(length)
```

**参数**

* `length` — 字符串的长度 (以字节为单位) 。[`UInt*`](/zh/reference/data-types/int-uint)

**返回值**

返回一个填充了随机字节的字符串。[`FixedString`](/zh/reference/data-types/fixedstring)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randomFixedString(13) AS rnd, toTypeName(rnd)
```

```response title=Response theme={null}
┌─rnd──────┬─toTypeName(randomFixedString(13))─┐
│ j▒h㋖HɨZ'▒ │ FixedString(13)                 │
└──────────┴───────────────────────────────────┘
```

<div id="randomPrintableASCII">
  ## randomPrintableASCII
</div>

自 v20.1.0 引入

生成具有指定字符数的随机 [ASCII](https://en.wikipedia.org/wiki/ASCII#Printable_characters) 字符串。

如果传入 `length < 0`，则该函数的行为未定义。

**语法**

```sql theme={null}
randomPrintableASCII(length[, x])
```

**参数**

* `length` — 字符串长度 (以字节为单位) 。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `x` — 可选，会被忽略。此参数的唯一作用，是在同一查询中多次使用相同的函数调用时，防止[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个由随机 ASCII 可打印字符组成的字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT number, randomPrintableASCII(30) AS str, length(str) FROM system.numbers LIMIT 3
```

```response title=Response theme={null}
┌─number─┬─str────────────────────────────┬─length(randomPrintableASCII(30))─┐
│      0 │ SuiCOSTvC0csfABSw=UcSzp2.`rv8x │                               30 │
│      1 │ 1Ag NlJ &RCN:*>HVPG;PE-nO"SUFD │                               30 │
│      2 │ /"+<"with:=LjJ Vm!c&hI*m#XTfzz │                               30 │
└────────┴────────────────────────────────┴──────────────────────────────────┘
```

<div id="randomString">
  ## randomString
</div>

引入版本：v20.5.0

生成指定字符数的随机字符串。
返回的字符不一定是 ASCII 字符，也就是说，它们可能不可打印。

**语法**

```sql theme={null}
randomString(length[, x])
```

**参数**

* `length` — 字符串的长度 (以字节为单位) 。[`(U)Int*`](/zh/reference/data-types/int-uint)
* `x` — 可选，会被忽略。此参数的唯一作用是在同一查询中多次使用相同的函数调用时，防止[公共子表达式消除](/zh/reference/functions/regular-functions/overview#common-subexpression-elimination)。[`Any`](/zh/reference/data-types)

**返回值**

返回一个由随机字节填充的字符串。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT randomString(5) AS str FROM numbers(2)
```

```response title=Response theme={null}
���
�v6B�
```

<div id="randomStringUTF8">
  ## randomStringUTF8
</div>

引入版本：v20.5.0

生成具有指定码点数量的随机 [UTF-8](https://en.wikipedia.org/wiki/UTF-8) 字符串。
不会返回来自未分配 [plane](https://en.wikipedia.org/wiki/Plane_\(Unicode\)) (第 4 到第 13 平面) 的码点。
但与 ClickHouse server 交互的客户端仍可能无法正确显示生成的 UTF-8 字符串。

**语法**

```sql theme={null}
randomStringUTF8(length)
```

**参数**

* `length` — 字符串的长度，以码点为单位。[`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回一个由随机 UTF-8 码点组成的字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT randomStringUTF8(13)
```

```response title=Response theme={null}
┌─randomStringUTF8(13)─┐
│ 𘤗𙉝д兠庇󡅴󱱎󦐪􂕌𔊹𓰛       │
└──────────────────────┘
```