This is an automated email from the ASF dual-hosted git repository.
morningman 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 0edfe41b264 [fix](doc) document FOREACH input types and unequal-length
behavior (#3729)
0edfe41b264 is described below
commit 0edfe41b264aa5be5116b878601fee40882aad48
Author: boluor <[email protected]>
AuthorDate: Fri May 22 10:35:30 2026 -0700
[fix](doc) document FOREACH input types and unequal-length behavior (#3729)
## Summary
The FOREACH combinator page
(`sql-manual/sql-functions/combinators/foreach`) only had a description
and examples. It didn't document the accepted input types or the
behavior when array arguments have different lengths. Added a **Notes**
section covering three points, verified against the engine source:
- **Input/return types** — each argument must be an `ARRAY` whose
element type matches the corresponding argument of the nested aggregate
function; the result is an `ARRAY` of the nested function's return type,
computed position by position.
- **Unequal-length arrays** — when a single call passes multiple array
arguments, all arrays in the **same row** must have the same length,
otherwise the query fails with `Arrays passed to <function> aggregate
function have different sizes` (see
`be/src/exprs/aggregate/aggregate_function_foreach.h`). Array lengths
may differ **across rows** (the existing example already demonstrates
per-position aggregation across rows).
- **Unsupported functions** — `percentile`, `percentile_array`,
`percentile_approx`, and `percentile_approx_weighted` are not supported
with the `foreach` combinator.
Applied to `docs/`, `versioned_docs/version-{2.1,3.x,4.x}/`, and the
matching `i18n/zh-CN/` pages.
Closes #2944
## Test plan
- [x] Behavior confirmed against the BE source
(`aggregate_function_foreach.h` size-mismatch check; FE
`ForEachCombinator` unsupported-function list).
- [x] Dead-link check passes on the changed files.
- [ ] CI build.
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
---
docs/sql-manual/sql-functions/combinators/foreach.md | 6 ++++++
.../current/sql-manual/sql-functions/combinators/foreach.md | 6 ++++++
.../version-2.1/sql-manual/sql-functions/combinators/foreach.md | 6 ++++++
.../version-3.x/sql-manual/sql-functions/combinators/foreach.md | 6 ++++++
.../version-4.x/sql-manual/sql-functions/combinators/foreach.md | 6 ++++++
.../version-2.1/sql-manual/sql-functions/combinators/foreach.md | 6 ++++++
.../version-3.x/sql-manual/sql-functions/combinators/foreach.md | 6 ++++++
.../version-4.x/sql-manual/sql-functions/combinators/foreach.md | 6 ++++++
8 files changed, 48 insertions(+)
diff --git a/docs/sql-manual/sql-functions/combinators/foreach.md
b/docs/sql-manual/sql-functions/combinators/foreach.md
index c56b2ad3695..99d6684302c 100644
--- a/docs/sql-manual/sql-functions/combinators/foreach.md
+++ b/docs/sql-manual/sql-functions/combinators/foreach.md
@@ -55,5 +55,11 @@ mysql [test]>select map_agg_foreach(a,a) from db;
| [{1:1, 20:20, 100:100}, {2:2}, {3:3}] |
+---------------------------------------+
```
+## Notes
+
+- Each argument must be an ARRAY whose element type matches the corresponding
argument of the nested aggregate function. The result is an ARRAY of the nested
function's return type, computed position by position.
+- When a single call passes multiple array arguments, all arrays in the same
row must have the same length; otherwise the query fails with `Arrays passed to
<function> aggregate function have different sizes`. (Array lengths may differ
across rows.)
+- The `percentile`, `percentile_array`, `percentile_approx`, and
`percentile_approx_weighted` functions are not supported with the `foreach`
combinator.
+
### Keywords
FOREACH
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/combinators/foreach.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/combinators/foreach.md
index 39cf9054717..58fba6f96aa 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/combinators/foreach.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/combinators/foreach.md
@@ -54,5 +54,11 @@ mysql [test]>select map_agg_foreach(a,a) from db;
| [{1:1, 20:20, 100:100}, {2:2}, {3:3}] |
+---------------------------------------+
```
+## 注意事项
+
+- 每个参数都必须是 ARRAY，其元素类型需与被包裹聚合函数对应参数的类型一致；返回值是被包裹函数返回类型的 ARRAY，按下标逐位计算。
+- 当一次调用传入多个数组参数时，同一行内的各数组长度必须相同，否则查询会报错 `Arrays passed to <function> aggregate
function have different sizes`。（不同行之间的数组长度可以不同。）
+-
`percentile`、`percentile_array`、`percentile_approx`、`percentile_approx_weighted`
函数不支持与 `foreach` 组合器一起使用。
+
### keywords
FOREACH
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/combinators/foreach.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/combinators/foreach.md
index 39cf9054717..58fba6f96aa 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/combinators/foreach.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/combinators/foreach.md
@@ -54,5 +54,11 @@ mysql [test]>select map_agg_foreach(a,a) from db;
| [{1:1, 20:20, 100:100}, {2:2}, {3:3}] |
+---------------------------------------+
```
+## 注意事项
+
+- 每个参数都必须是 ARRAY，其元素类型需与被包裹聚合函数对应参数的类型一致；返回值是被包裹函数返回类型的 ARRAY，按下标逐位计算。
+- 当一次调用传入多个数组参数时，同一行内的各数组长度必须相同，否则查询会报错 `Arrays passed to <function> aggregate
function have different sizes`。（不同行之间的数组长度可以不同。）
+-
`percentile`、`percentile_array`、`percentile_approx`、`percentile_approx_weighted`
函数不支持与 `foreach` 组合器一起使用。
+
### keywords
FOREACH
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/combinators/foreach.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/combinators/foreach.md
index 39cf9054717..58fba6f96aa 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/combinators/foreach.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/combinators/foreach.md
@@ -54,5 +54,11 @@ mysql [test]>select map_agg_foreach(a,a) from db;
| [{1:1, 20:20, 100:100}, {2:2}, {3:3}] |
+---------------------------------------+
```
+## 注意事项
+
+- 每个参数都必须是 ARRAY，其元素类型需与被包裹聚合函数对应参数的类型一致；返回值是被包裹函数返回类型的 ARRAY，按下标逐位计算。
+- 当一次调用传入多个数组参数时，同一行内的各数组长度必须相同，否则查询会报错 `Arrays passed to <function> aggregate
function have different sizes`。（不同行之间的数组长度可以不同。）
+-
`percentile`、`percentile_array`、`percentile_approx`、`percentile_approx_weighted`
函数不支持与 `foreach` 组合器一起使用。
+
### keywords
FOREACH
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/combinators/foreach.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/combinators/foreach.md
index 39cf9054717..58fba6f96aa 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/combinators/foreach.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/combinators/foreach.md
@@ -54,5 +54,11 @@ mysql [test]>select map_agg_foreach(a,a) from db;
| [{1:1, 20:20, 100:100}, {2:2}, {3:3}] |
+---------------------------------------+
```
+## 注意事项
+
+- 每个参数都必须是 ARRAY，其元素类型需与被包裹聚合函数对应参数的类型一致；返回值是被包裹函数返回类型的 ARRAY，按下标逐位计算。
+- 当一次调用传入多个数组参数时，同一行内的各数组长度必须相同，否则查询会报错 `Arrays passed to <function> aggregate
function have different sizes`。（不同行之间的数组长度可以不同。）
+-
`percentile`、`percentile_array`、`percentile_approx`、`percentile_approx_weighted`
函数不支持与 `foreach` 组合器一起使用。
+
### keywords
FOREACH
\ No newline at end of file
diff --git
a/versioned_docs/version-2.1/sql-manual/sql-functions/combinators/foreach.md
b/versioned_docs/version-2.1/sql-manual/sql-functions/combinators/foreach.md
index 9cc764f95ae..5801adfee28 100644
--- a/versioned_docs/version-2.1/sql-manual/sql-functions/combinators/foreach.md
+++ b/versioned_docs/version-2.1/sql-manual/sql-functions/combinators/foreach.md
@@ -54,5 +54,11 @@ mysql [test]>select map_agg_foreach(a,a) from db;
| [{1:1, 20:20, 100:100}, {2:2}, {3:3}] |
+---------------------------------------+
```
+## Notes
+
+- Each argument must be an ARRAY whose element type matches the corresponding
argument of the nested aggregate function. The result is an ARRAY of the nested
function's return type, computed position by position.
+- When a single call passes multiple array arguments, all arrays in the same
row must have the same length; otherwise the query fails with `Arrays passed to
<function> aggregate function have different sizes`. (Array lengths may differ
across rows.)
+- The `percentile`, `percentile_array`, `percentile_approx`, and
`percentile_approx_weighted` functions are not supported with the `foreach`
combinator.
+
### keywords
FOREACH
\ No newline at end of file
diff --git
a/versioned_docs/version-3.x/sql-manual/sql-functions/combinators/foreach.md
b/versioned_docs/version-3.x/sql-manual/sql-functions/combinators/foreach.md
index 9cc764f95ae..5801adfee28 100644
--- a/versioned_docs/version-3.x/sql-manual/sql-functions/combinators/foreach.md
+++ b/versioned_docs/version-3.x/sql-manual/sql-functions/combinators/foreach.md
@@ -54,5 +54,11 @@ mysql [test]>select map_agg_foreach(a,a) from db;
| [{1:1, 20:20, 100:100}, {2:2}, {3:3}] |
+---------------------------------------+
```
+## Notes
+
+- Each argument must be an ARRAY whose element type matches the corresponding
argument of the nested aggregate function. The result is an ARRAY of the nested
function's return type, computed position by position.
+- When a single call passes multiple array arguments, all arrays in the same
row must have the same length; otherwise the query fails with `Arrays passed to
<function> aggregate function have different sizes`. (Array lengths may differ
across rows.)
+- The `percentile`, `percentile_array`, `percentile_approx`, and
`percentile_approx_weighted` functions are not supported with the `foreach`
combinator.
+
### keywords
FOREACH
\ No newline at end of file
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/combinators/foreach.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/combinators/foreach.md
index c56b2ad3695..99d6684302c 100644
--- a/versioned_docs/version-4.x/sql-manual/sql-functions/combinators/foreach.md
+++ b/versioned_docs/version-4.x/sql-manual/sql-functions/combinators/foreach.md
@@ -55,5 +55,11 @@ mysql [test]>select map_agg_foreach(a,a) from db;
| [{1:1, 20:20, 100:100}, {2:2}, {3:3}] |
+---------------------------------------+
```
+## Notes
+
+- Each argument must be an ARRAY whose element type matches the corresponding
argument of the nested aggregate function. The result is an ARRAY of the nested
function's return type, computed position by position.
+- When a single call passes multiple array arguments, all arrays in the same
row must have the same length; otherwise the query fails with `Arrays passed to
<function> aggregate function have different sizes`. (Array lengths may differ
across rows.)
+- The `percentile`, `percentile_array`, `percentile_approx`, and
`percentile_approx_weighted` functions are not supported with the `foreach`
combinator.
+
### Keywords
FOREACH
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
