[doc](function) Add stack table function documentation

docs/sql-manual/sql-functions/table-functions/stack.md

@@ -0,0 +1,120 @@
+---
+{
+    "title": "STACK",
+    "language": "en",
+    "description": "The stack function separates expressions into rows in row-major order and pads the last row with NULL values."
+}
+---
+
+## 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. Expressions in the same output column must have compatible types. 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 common type of the expressions assigned to that column; 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 `stack` is used with a single expression per output column, the table function returns one column. 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.

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/stack.md

@@ -0,0 +1,120 @@
+---
+{
+    "title": "STACK",
+    "language": "zh-CN",
+    "description": "STACK 函数按行优先顺序将表达式拆分成多行，并使用 NULL 补齐最后一行。"
+}
+---
+
+## 描述
+
+`stack` 将一组表达式拆分为固定数量的行。表达式按行优先顺序排列，与 Spark 和 Hive 的 `stack` 函数兼容。`stack` 需要与 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 配合使用，将生成的列添加到每个输入行中。
+
+## 语法
+
+```sql
+STACK(<num_rows>, <expr1> [, <expr2> ...])
+```
+
+## 参数
+
+| 参数 | 描述 |
+|------|------|
+| `<num_rows>` | 用于指定生成行数的正整数常量。支持 `3 - 1` 等常量表达式。 |
+| `<expr1> [, <expr2> ...]` | 要分配到生成行中的表达式。同一输出列中的表达式必须具有兼容的类型。表达式可以引用输入行中的列。 |
+
+## 返回值
+
+返回 `<num_rows>` 行。输出列数等于表达式数量除以 `<num_rows>` 后向上取整的结果。每个输出列的类型为分配到该列的表达式所共有的类型；如果某列只包含 `NULL` 表达式，则该列为 `NULL` 类型。值从左到右逐行分配。如果最后一行没有足够的表达式，缺少的值将使用 `NULL` 补齐。
+
+当每个输出列只有一个表达式时，`stack` 表函数返回一列。生成多个输出列时，需要在 `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` 值会在结果中作为补充值或原值保留。

sidebars.ts

@@ -1,4 +1,4 @@
 import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
 
 const sidebars: SidebarsConfig = {
     docs: [
@@ -2213,6 +2213,7 @@
                                 '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',
                             ],
                         },