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 0000000000000..e608dfae09c50 --- /dev/null +++ b/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(, [, ...]) +``` + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `` | A positive constant integer that specifies the number of rows to generate. Constant expressions, such as `3 - 1`, are supported. | +| ` [, ...]` | 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 `` rows. The number of output columns is the ceiling of the number of expressions divided by ``. 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. `` 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. 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 0000000000000..aac8b021019f5 --- /dev/null +++ b/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(, [, ...]) +``` + +## 参数 + +| 参数 | 描述 | +|------|------| +| `` | 用于指定生成行数的正整数常量。支持 `3 - 1` 等常量表达式。 | +| ` [, ...]` | 要分配到生成行中的表达式。同一输出列中的表达式必须具有兼容的类型。表达式可以引用输入行中的列。 | + +## 返回值 + +返回 `` 行。输出列数等于表达式数量除以 `` 后向上取整的结果。每个输出列的类型为分配到该列的表达式所共有的类型;如果某列只包含 `NULL` 表达式,则该列为 `NULL` 类型。值从左到右逐行分配。如果最后一行没有足够的表达式,缺少的值将使用 `NULL` 补齐。 + +当每个输出列只有一个表达式时,`stack` 表函数返回一列。生成多个输出列时,需要在 `LATERAL VIEW` 子句中指定别名来命名这些列。 + +## 使用说明 + +1. `` 必须是正整数常量。列引用、非整数、零或负数均无效。 +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` 值会在结果中作为补充值或原值保留。 diff --git a/sidebars.ts b/sidebars.ts index 80034d7c6091e..bace6884df0bd 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -2213,6 +2213,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', ], },