This is an automated email from the ASF dual-hosted git repository.
yiguolei pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 39a6535babf [doc](function) Update array_shuffle seed rules (#4176)
39a6535babf is described below
commit 39a6535babf19675d12ca4b38bfa3e50bd5a2f38
Author: Chenyang Sun <[email protected]>
AuthorDate: Fri Oct 9 17:19:59 2026 +0800
[doc](function) Update array_shuffle seed rules (#4176)
Update ARRAY_SHUFFLE docs, for apache/doris#68438:
- seed must be a constant; a column or another non-constant seed reports
an error
- all 64 bits of the seed are used, so any BIGINT works, a negative one
too
- each row is shuffled on its own, a constant array too, and each batch
starts a random sequence from the seed
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [ ] Chinese
- [ ] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
- [ ] Updated required version and language counterparts, or explained
why not
- [ ] If only one language changed, confirmed whether source/translation
counterparts need sync
Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
---
.../array-functions/array-shuffle.md | 21 ++++++++++++++----
.../array-functions/array-shuffle.md | 21 ++++++++++++++----
.../array-functions/array-shuffle.md | 25 ++++++++++++++++++----
.../array-functions/array-shuffle.md | 25 ++++++++++++++++++----
4 files changed, 76 insertions(+), 16 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
b/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
index 34ebff32f52..4dec97ca99e 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
@@ -18,7 +18,7 @@ Randomly shuffle the order of elements in an array.
## Parameters
- `arr`: `ARRAY<T>`.
-- `seed`: optional, random seed.
+- `seed`: optional, random seed. It must be a constant `BIGINT`.
## Return value
@@ -26,8 +26,12 @@ Randomly shuffle the order of elements in an array.
## Usage notes
-- If the input `arr` is `NULL`, returns `NULL`.
-- Providing a `seed` yields reproducible results; omitting it may yield
different results per execution.
+- If the input `arr` is `NULL`, returns `NULL`. If `seed` is `NULL`, returns
`NULL`.
+- Each row is shuffled on its own, even when `arr` is a constant, so rows with
the same array can get different orders.
+- `seed` must be a constant, such as `0` or `1 + 1`. Passing a column or
another non-constant expression reports an error.
+- Any `BIGINT` value can be a `seed`, including a negative one. All 64 bits
are used, so `-1` and `4294967295` give different results.
+- Rows are processed in batches. Each batch starts a random sequence from
`seed`, and its rows take numbers from the sequence one after another. So a
single call such as `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` gives the same result each
time, but on many rows, the order of a row can change with how the rows are
split into batches.
+- Without `seed`, each batch starts from a new random seed, so the result may
differ between executions.
- `ARRAY_SHUFFLE` has an alias `SHUFFLE`; they are equivalent.
## Examples
@@ -37,5 +41,14 @@ Randomly shuffle the order of elements in an array.
- `ARRAY_SHUFFLE(['a', null, 'b'])` -> e.g. `['b', 'a', null]`
- With a fixed seed (reproducible results):
- - `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` -> same order each time (e.g. `[1, 3, 2,
4]`)
+ - `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` -> `[2, 1, 3, 4]` each time
+
+- A constant array is shuffled on each row:
+ - `SELECT number, ARRAY_SHUFFLE([1, 2, 3, 4, 5], 0) FROM numbers("number" =
"3") ORDER BY number` -> `[3, 1, 2, 4, 5]`, `[3, 5, 4, 2, 1]` and `[4, 5, 1, 3,
2]` on the three rows
+
+- A negative seed works, and all 64 bits are used:
+ - `ARRAY_SHUFFLE([1, 2, 3, 4], -1)` -> `[4, 1, 3, 2]`, while
`ARRAY_SHUFFLE([1, 2, 3, 4], 4294967295)` -> `[2, 4, 3, 1]`
+
+- A non-constant seed reports an error:
+ - `SELECT ARRAY_SHUFFLE(arr, id) FROM t` -> error `The seed of array_shuffle
must be a constant`
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
index 327e2d61234..18471cb745d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
@@ -18,7 +18,7 @@
## 参数
- `arr`：`ARRAY<T>`。
-- `seed`：可选，表示随机数种子。
+- `seed`：可选，表示随机数种子，必须是 `BIGINT` 类型的常量。
## 返回值
@@ -26,8 +26,12 @@
## 使用说明
-- 输入的 `arr` 是 `NULL` 时，返回 `NULL`。
-- 指定 `seed` 可获得可复现结果；不指定则每次执行结果可能不同。
+- 输入的 `arr` 是 `NULL` 时，返回 `NULL`；`seed` 是 `NULL` 时，也返回 `NULL`。
+- 每一行都会单独打乱，`arr` 是常量时也一样，所以相同的数组在不同行可能得到不同的顺序。
+- `seed` 必须是常量，例如 `0` 或 `1 + 1`。传入列或其他非常量表达式会报错。
+- `seed` 可以是任意 `BIGINT` 值，包括负数。64 位全部参与计算，所以 `-1` 和 `4294967295` 的结果不同。
+- 数据按批处理。每一批都从 `seed` 开始生成一个随机数序列，批内的行依次使用这个序列。因此像 `ARRAY_SHUFFLE([1, 2, 3,
4], 0)` 这样的单次调用每次结果都相同；但在多行数据上，某一行的结果可能随数据的分批方式而变化。
+- 不指定 `seed` 时，每一批都使用新的随机种子，每次执行结果可能不同。
- `ARRAY_SHUFFLE`的函数别名是 `SHUFFLE`，两个函数功能一致。
## 示例
@@ -37,4 +41,13 @@
- `ARRAY_SHUFFLE(['a', null, 'b'])` -> 例如 `['b', 'a', null]`
- 指定种子（结果可复现）：
- - `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` -> 每次执行均得到相同顺序（如 `[1, 3, 2, 4]`）
\ No newline at end of file
+ - `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` -> 每次执行都得到 `[2, 1, 3, 4]`
+
+- 常量数组也会逐行打乱：
+ - `SELECT number, ARRAY_SHUFFLE([1, 2, 3, 4, 5], 0) FROM numbers("number" =
"3") ORDER BY number` -> 三行依次为 `[3, 1, 2, 4, 5]`、`[3, 5, 4, 2, 1]`、`[4, 5, 1,
3, 2]`
+
+- 负数种子也可以使用，并且 64 位全部参与计算：
+ - `ARRAY_SHUFFLE([1, 2, 3, 4], -1)` -> `[4, 1, 3, 2]`，而 `ARRAY_SHUFFLE([1,
2, 3, 4], 4294967295)` -> `[2, 4, 3, 1]`
+
+- 非常量的种子会报错：
+ - `SELECT ARRAY_SHUFFLE(arr, id) FROM t` -> 报错 `The seed of array_shuffle
must be a constant`
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
index 327e2d61234..00bfbdaf352 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
@@ -10,6 +10,10 @@
`ARRAY_SHUFFLE` 用来随机打乱数组内元素的顺序。
+:::note
+自 Apache Doris 4.2 起，`seed` 必须是常量，任意 `BIGINT` 值的 64 位都会参与计算，并且常量 `arr`
也会逐行打乱，因此同一个 `seed` 得到的顺序与 4.0、4.1 不同。在 4.0 和 4.1 中，传入非常量的 `seed`
不会报错，但只有每批第一行的 `seed` 生效；`seed` 为负数或大于 4294967295 时会报错；常量 `arr` 在每一行都得到相同的顺序。
+:::
+
## 语法
- `ARRAY_SHUFFLE(arr)`
@@ -18,7 +22,7 @@
## 参数
- `arr`：`ARRAY<T>`。
-- `seed`：可选，表示随机数种子。
+- `seed`：可选，表示随机数种子，必须是 `BIGINT` 类型的常量。
## 返回值
@@ -26,8 +30,12 @@
## 使用说明
-- 输入的 `arr` 是 `NULL` 时，返回 `NULL`。
-- 指定 `seed` 可获得可复现结果；不指定则每次执行结果可能不同。
+- 输入的 `arr` 是 `NULL` 时，返回 `NULL`；`seed` 是 `NULL` 时，也返回 `NULL`。
+- 每一行都会单独打乱，`arr` 是常量时也一样，所以相同的数组在不同行可能得到不同的顺序。
+- `seed` 必须是常量，例如 `0` 或 `1 + 1`。传入列或其他非常量表达式会报错。
+- `seed` 可以是任意 `BIGINT` 值，包括负数。64 位全部参与计算，所以 `-1` 和 `4294967295` 的结果不同。
+- 数据按批处理。每一批都从 `seed` 开始生成一个随机数序列，批内的行依次使用这个序列。因此像 `ARRAY_SHUFFLE([1, 2, 3,
4], 0)` 这样的单次调用每次结果都相同；但在多行数据上，某一行的结果可能随数据的分批方式而变化。
+- 不指定 `seed` 时，每一批都使用新的随机种子，每次执行结果可能不同。
- `ARRAY_SHUFFLE`的函数别名是 `SHUFFLE`，两个函数功能一致。
## 示例
@@ -37,4 +45,13 @@
- `ARRAY_SHUFFLE(['a', null, 'b'])` -> 例如 `['b', 'a', null]`
- 指定种子（结果可复现）：
- - `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` -> 每次执行均得到相同顺序（如 `[1, 3, 2, 4]`）
\ No newline at end of file
+ - `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` -> 每次执行都得到 `[2, 1, 3, 4]`
+
+- 常量数组也会逐行打乱：
+ - `SELECT number, ARRAY_SHUFFLE([1, 2, 3, 4, 5], 0) FROM numbers("number" =
"3") ORDER BY number` -> 三行依次为 `[3, 1, 2, 4, 5]`、`[3, 5, 4, 2, 1]`、`[4, 5, 1,
3, 2]`
+
+- 负数种子也可以使用，并且 64 位全部参与计算：
+ - `ARRAY_SHUFFLE([1, 2, 3, 4], -1)` -> `[4, 1, 3, 2]`，而 `ARRAY_SHUFFLE([1,
2, 3, 4], 4294967295)` -> `[2, 4, 3, 1]`
+
+- 非常量的种子会报错：
+ - `SELECT ARRAY_SHUFFLE(arr, id) FROM t` -> 报错 `The seed of array_shuffle
must be a constant`
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
index 34ebff32f52..f686e496932 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/array-functions/array-shuffle.md
@@ -10,6 +10,10 @@
Randomly shuffle the order of elements in an array.
+:::note
+Since Apache Doris 4.2, `seed` must be a constant, all 64 bits of any `BIGINT`
value are used, and a constant `arr` is shuffled on each row, so the same
`seed` gives a different order than in 4.0 and 4.1. In 4.0 and 4.1, a
non-constant `seed` does not report an error, but only the seed of the first
row in each batch is used; a `seed` that is negative or larger than 4294967295
reports an error; and a constant `arr` gets the same order on every row.
+:::
+
## Syntax
- `ARRAY_SHUFFLE(arr)`
@@ -18,7 +22,7 @@ Randomly shuffle the order of elements in an array.
## Parameters
- `arr`: `ARRAY<T>`.
-- `seed`: optional, random seed.
+- `seed`: optional, random seed. It must be a constant `BIGINT`.
## Return value
@@ -26,8 +30,12 @@ Randomly shuffle the order of elements in an array.
## Usage notes
-- If the input `arr` is `NULL`, returns `NULL`.
-- Providing a `seed` yields reproducible results; omitting it may yield
different results per execution.
+- If the input `arr` is `NULL`, returns `NULL`. If `seed` is `NULL`, returns
`NULL`.
+- Each row is shuffled on its own, even when `arr` is a constant, so rows with
the same array can get different orders.
+- `seed` must be a constant, such as `0` or `1 + 1`. Passing a column or
another non-constant expression reports an error.
+- Any `BIGINT` value can be a `seed`, including a negative one. All 64 bits
are used, so `-1` and `4294967295` give different results.
+- Rows are processed in batches. Each batch starts a random sequence from
`seed`, and its rows take numbers from the sequence one after another. So a
single call such as `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` gives the same result each
time, but on many rows, the order of a row can change with how the rows are
split into batches.
+- Without `seed`, each batch starts from a new random seed, so the result may
differ between executions.
- `ARRAY_SHUFFLE` has an alias `SHUFFLE`; they are equivalent.
## Examples
@@ -37,5 +45,14 @@ Randomly shuffle the order of elements in an array.
- `ARRAY_SHUFFLE(['a', null, 'b'])` -> e.g. `['b', 'a', null]`
- With a fixed seed (reproducible results):
- - `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` -> same order each time (e.g. `[1, 3, 2,
4]`)
+ - `ARRAY_SHUFFLE([1, 2, 3, 4], 0)` -> `[2, 1, 3, 4]` each time
+
+- A constant array is shuffled on each row:
+ - `SELECT number, ARRAY_SHUFFLE([1, 2, 3, 4, 5], 0) FROM numbers("number" =
"3") ORDER BY number` -> `[3, 1, 2, 4, 5]`, `[3, 5, 4, 2, 1]` and `[4, 5, 1, 3,
2]` on the three rows
+
+- A negative seed works, and all 64 bits are used:
+ - `ARRAY_SHUFFLE([1, 2, 3, 4], -1)` -> `[4, 1, 3, 2]`, while
`ARRAY_SHUFFLE([1, 2, 3, 4], 4294967295)` -> `[2, 4, 3, 1]`
+
+- A non-constant seed reports an error:
+ - `SELECT ARRAY_SHUFFLE(arr, id) FROM t` -> error `The seed of array_shuffle
must be a constant`
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
