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 8bf0e710dd0 [doc](function) Add stack table function documentation
(#4059)
8bf0e710dd0 is described below
commit 8bf0e710dd060d109ef6d0c595b4d125aa637abd
Author: HappenLee <[email protected]>
AuthorDate: Sat Oct 17 05:39:30 2026 +0800
[doc](function) Add stack table function documentation (#4059)
## Summary
Document STACK row-major layout, NULL padding, constant row counts,
exact per-column type requirements, and LATERAL VIEW usage.
## Versions
- [x] dev
- [ ] 4.x
- [ ] 3.x
- [ ] 2.1 or older
Dev only. STACK is implemented on master and is absent from branch-4.0,
branch-4.1, and branch-4.2.
## Languages
- [x] Chinese
- [x] English
## Validation
Reviewed against Doris master `88f22fd875e0be4dea2c58c53744f4074378a870`
and the corresponding current 4.0, 4.1, and 4.2 source branches. Rebased
onto website master `f582020241f825849ffa3b57fc3220cb674d28a7`.
- SQL function structure and internal-link checks passed for the final
changed pages.
- `git diff --check` passed.
- English and Chinese changes are synchronized. Remaining version-sync
notices are explained above.
- Doris and the website were not built; examples were checked against
source and existing regression expectations where available.
---------
Co-authored-by: morningman <[email protected]>
---
.../sql-functions/table-functions/stack.md | 142 +++++++++++++++++++++
.../sql-functions/table-functions/stack.md | 142 +++++++++++++++++++++
sidebars.ts | 1 +
3 files changed, 285 insertions(+)
diff --git a/docs/sql-manual/sql-functions/table-functions/stack.md
b/docs/sql-manual/sql-functions/table-functions/stack.md
new file mode 100644
index 00000000000..ce634b6622c
--- /dev/null
+++ b/docs/sql-manual/sql-functions/table-functions/stack.md
@@ -0,0 +1,142 @@
+---
+{
+ "title": "STACK",
+ "language": "en",
+ "description": "The stack function separates expressions into rows in
row-major order and pads the last row with NULL values."
+}
+---
+
+<version since="dev">
+
+</version>
+
+## Description
+
+`stack` separates a list of expressions into a fixed number of rows. The
expressions are arranged in row-major order, which is compatible with the Spark
and Hive `stack` functions. Use `stack` with [`LATERAL
VIEW`](../../../query-data/lateral-view.md) to add the generated columns to
each input row.
+
+## Syntax
+
+```sql
+STACK(<num_rows>, <expr1> [, <expr2> ...])
+```
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `<num_rows>` | A positive constant integer that specifies the number of rows
to generate. Constant expressions, such as `3 - 1`, are supported. |
+| `<expr1> [, <expr2> ...]` | Expressions to distribute across the generated
rows. Non-NULL expressions in the same output column must have exactly the same
type; use explicit casts when needed. Expressions can reference columns from
the input row. |
+
+## Return Value
+
+Returns `<num_rows>` rows. The number of output columns is the ceiling of the
number of expressions divided by `<num_rows>`. Each output column has the type
shared by its non-NULL expressions; a column containing only `NULL` expressions
has the `NULL` type. Values are assigned row by row from left to right. If the
final row does not contain enough expressions, the missing values are filled
with `NULL`.
+
+When multiple output columns are produced, specify aliases in the `LATERAL
VIEW` clause to name them.
+
+## Usage Notes
+
+1. `<num_rows>` must be a positive constant integer. A column reference,
non-integer value, zero, or negative value is invalid.
+2. For each output column, non-`NULL` expressions assigned to that column must
have the same type. A column containing only `NULL` expressions has the `NULL`
type.
+3. Values are laid out in row-major order: the first output row receives the
first value of every output column, then the second row receives the second
value of every output column.
+4. `stack` is a table-generating function and is normally used with `LATERAL
VIEW`.
+
+## Examples
+
+### Basic usage
+
+```sql
+SELECT c1, c2
+FROM (SELECT 1) t
+LATERAL VIEW stack(2, 1, 2, 3) s AS c1, c2
+ORDER BY c1, c2;
+```
+
+```text
++------+------+
+| c1 | c2 |
++------+------+
+| 1 | 2 |
+| 3 | NULL |
++------+------+
+```
+
+### Row-major layout
+
+```sql
+SELECT c1, c2
+FROM (SELECT 1) t
+LATERAL VIEW stack(3, 1, 'a', 2, 'b', 3, 'c') s AS c1, c2
+ORDER BY c1, c2;
+```
+
+```text
++------+------+
+| c1 | c2 |
++------+------+
+| 1 | a |
+| 2 | b |
+| 3 | c |
++------+------+
+```
+
+When there are fewer expressions than required to fill the last row, the
missing values are `NULL`:
+
+```sql
+SELECT c1
+FROM (SELECT 1) t
+LATERAL VIEW stack(4, 1, 2, 3) s AS c1
+ORDER BY c1;
+```
+
+```text
++------+
+| c1 |
++------+
+| NULL |
+| 1 |
+| 2 |
+| 3 |
++------+
+```
+
+### Column expressions and type checking
+
+```sql
+SELECT id, c1, c2
+FROM (
+ SELECT 1 AS id, 10 AS a, 'x' AS s1, 20 AS b, 'y' AS s2
+) AS test_stack
+LATERAL VIEW stack(2, a, s1, b, s2) s AS c1, c2
+ORDER BY id, c1, c2;
+```
+
+```text
++------+------+------+
+| id | c1 | c2 |
++------+------+------+
+| 1 | 10 | x |
+| 1 | 20 | y |
++------+------+------+
+```
+
+Expressions are evaluated for each input row. In this example, `a` and `b`
form one output column and `s1` and `s2` form the other. If expressions
assigned to one output column have incompatible types, the query returns an
analysis error.
+
+`NULL` expressions can be used with values of another type; the `NULL` values
are padded or preserved in the result.
+
+Explicit NULL expressions are preserved:
+
+```sql
+SELECT c1
+FROM (SELECT 1) t
+LATERAL VIEW stack(2, 1, NULL) s AS c1
+ORDER BY c1;
+```
+
+```text
++------+
+| c1 |
++------+
+| NULL |
+| 1 |
++------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/stack.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/stack.md
new file mode 100644
index 00000000000..47b896870ff
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/stack.md
@@ -0,0 +1,142 @@
+---
+{
+ "title": "STACK",
+ "language": "zh-CN",
+ "description": "STACK 函数按行优先顺序将表达式拆分成多行，并使用 NULL 补齐最后一行。"
+}
+---
+
+<version since="dev">
+
+</version>
+
+## 描述
+
+`stack` 将一组表达式拆分为固定数量的行。表达式按行优先顺序排列，与 Spark 和 Hive 的 `stack` 函数兼容。`stack` 需要与
[`LATERAL VIEW`](../../../query-data/lateral-view.md) 配合使用，将生成的列添加到每个输入行中。
+
+## 语法
+
+```sql
+STACK(<num_rows>, <expr1> [, <expr2> ...])
+```
+
+## 参数
+
+| 参数 | 描述 |
+|------|------|
+| `<num_rows>` | 用于指定生成行数的正整数常量。支持 `3 - 1` 等常量表达式。 |
+| `<expr1> [, <expr2> ...]` | 要分配到生成行中的表达式。同一输出列中的非 NULL
表达式必须具有完全相同的类型；必要时请显式转换。表达式可以引用输入行中的列。 |
+
+## 返回值
+
+返回 `<num_rows>` 行。输出列数等于表达式数量除以 `<num_rows>` 后向上取整的结果。每个输出列的类型为分配到该列的非 NULL
表达式的相同类型；如果某列只包含 `NULL` 表达式，则该列为 `NULL` 类型。值从左到右逐行分配。如果最后一行没有足够的表达式，缺少的值将使用
`NULL` 补齐。
+
+生成多个输出列时，需要在 `LATERAL VIEW` 子句中指定别名来命名这些列。
+
+## 使用说明
+
+1. `<num_rows>` 必须是正整数常量。列引用、非整数、零或负数均无效。
+2. 对于每个输出列，分配到该列的非 `NULL` 表达式必须具有相同类型。只包含 `NULL` 表达式的列为 `NULL` 类型。
+3. 值按行优先顺序排列：第一个输出行获得每个输出列的第一个值，第二个输出行获得每个输出列的第二个值，以此类推。
+4. `stack` 是表生成函数，通常与 `LATERAL VIEW` 配合使用。
+
+## 示例
+
+### 基本用法
+
+```sql
+SELECT c1, c2
+FROM (SELECT 1) t
+LATERAL VIEW stack(2, 1, 2, 3) s AS c1, c2
+ORDER BY c1, c2;
+```
+
+```text
++------+------+
+| c1 | c2 |
++------+------+
+| 1 | 2 |
+| 3 | NULL |
++------+------+
+```
+
+### 行优先排列
+
+```sql
+SELECT c1, c2
+FROM (SELECT 1) t
+LATERAL VIEW stack(3, 1, 'a', 2, 'b', 3, 'c') s AS c1, c2
+ORDER BY c1, c2;
+```
+
+```text
++------+------+
+| c1 | c2 |
++------+------+
+| 1 | a |
+| 2 | b |
+| 3 | c |
++------+------+
+```
+
+如果表达式数量不足以填满最后一行，缺少的值为 `NULL`：
+
+```sql
+SELECT c1
+FROM (SELECT 1) t
+LATERAL VIEW stack(4, 1, 2, 3) s AS c1
+ORDER BY c1;
+```
+
+```text
++------+
+| c1 |
++------+
+| NULL |
+| 1 |
+| 2 |
+| 3 |
++------+
+```
+
+### 列表达式和类型检查
+
+```sql
+SELECT id, c1, c2
+FROM (
+ SELECT 1 AS id, 10 AS a, 'x' AS s1, 20 AS b, 'y' AS s2
+) AS test_stack
+LATERAL VIEW stack(2, a, s1, b, s2) s AS c1, c2
+ORDER BY id, c1, c2;
+```
+
+```text
++------+------+------+
+| id | c1 | c2 |
++------+------+------+
+| 1 | 10 | x |
+| 1 | 20 | y |
++------+------+------+
+```
+
+表达式会针对每个输入行求值。在本例中，`a` 和 `b` 组成一个输出列，`s1` 和 `s2`
组成另一个输出列。如果分配到同一输出列的表达式类型不兼容，查询将返回分析错误。
+
+`NULL` 表达式可以与其他类型的值一起使用；`NULL` 值会在结果中作为补充值或原值保留。
+
+显式 NULL 表达式会保留：
+
+```sql
+SELECT c1
+FROM (SELECT 1) t
+LATERAL VIEW stack(2, 1, NULL) s AS c1
+ORDER BY c1;
+```
+
+```text
++------+
+| c1 |
++------+
+| NULL |
+| 1 |
++------+
+```
diff --git a/sidebars.ts b/sidebars.ts
index 9d574c3c57d..0e064322605 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -2323,6 +2323,7 @@ const sidebars: SidebarsConfig = {
'sql-manual/sql-functions/table-functions/json-each-text-outer',
'sql-manual/sql-functions/table-functions/posexplode',
'sql-manual/sql-functions/table-functions/posexplode-outer',
+
'sql-manual/sql-functions/table-functions/stack',
'sql-manual/sql-functions/table-functions/unnest',
],
},
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
