Skip to content

Commit 59e55d2

Browse files
HappenLeeHappenLee
committed
[doc](function) Add Chinese stack documentation
1 parent 9bd8c9a commit 59e55d2

2 files changed

Lines changed: 134 additions & 3 deletions

File tree

  • docs/sql-manual/sql-functions/table-functions
  • i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions

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

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,14 @@ STACK(<num_rows>, <expr1> [, <expr2> ...])
1818

1919
## Parameters
2020

21-
- `<num_rows>`: A positive constant integer that specifies the number of rows to generate. Constant expressions, such as `3 - 1`, are supported.
22-
- `<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.
21+
| Parameter | Description |
22+
|-----------|-------------|
23+
| `<num_rows>` | A positive constant integer that specifies the number of rows to generate. Constant expressions, such as `3 - 1`, are supported. |
24+
| `<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. |
2325

2426
## Return Value
2527

26-
Returns `<num_rows>` rows. The number of output columns is the ceiling of the number of expressions divided by `<num_rows>`. 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`.
28+
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`.
2729

2830
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.
2931

@@ -104,6 +106,15 @@ LATERAL VIEW stack(2, a, s1, b, s2) s AS c1, c2
104106
ORDER BY id, c1, c2;
105107
```
106108

109+
```text
110+
+------+------+------+
111+
| id | c1 | c2 |
112+
+------+------+------+
113+
| 1 | 10 | x |
114+
| 1 | 20 | y |
115+
+------+------+------+
116+
```
117+
107118
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.
108119

109120
`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‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
{
3+
"title": "STACK",
4+
"language": "zh-CN",
5+
"description": "STACK 函数按行优先顺序将表达式拆分成多行，并使用 NULL 补齐最后一行。"
6+
}
7+
---
8+
9+
## 描述
10+
11+
`stack` 将一组表达式拆分为固定数量的行。表达式按行优先顺序排列，与 Spark 和 Hive 的 `stack` 函数兼容。`stack` 需要与 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 配合使用，将生成的列添加到每个输入行中。
12+
13+
## 语法
14+
15+
```sql
16+
STACK(<num_rows>, <expr1> [, <expr2> ...])
17+
```
18+
19+
## 参数
20+
21+
| 参数 | 描述 |
22+
|------|------|
23+
| `<num_rows>` | 用于指定生成行数的正整数常量。支持 `3 - 1` 等常量表达式。 |
24+
| `<expr1> [, <expr2> ...]` | 要分配到生成行中的表达式。同一输出列中的表达式必须具有兼容的类型。表达式可以引用输入行中的列。 |
25+
26+
## 返回值
27+
28+
返回 `<num_rows>` 行。输出列数等于表达式数量除以 `<num_rows>` 后向上取整的结果。每个输出列的类型为分配到该列的表达式所共有的类型；如果某列只包含 `NULL` 表达式，则该列为 `NULL` 类型。值从左到右逐行分配。如果最后一行没有足够的表达式，缺少的值将使用 `NULL` 补齐。
29+
30+
当每个输出列只有一个表达式时，`stack` 表函数返回一列。生成多个输出列时，需要在 `LATERAL VIEW` 子句中指定别名来命名这些列。
31+
32+
## 使用说明
33+
34+
1. `<num_rows>` 必须是正整数常量。列引用、非整数、零或负数均无效。
35+
2. 对于每个输出列，分配到该列的非 `NULL` 表达式必须具有相同类型。只包含 `NULL` 表达式的列为 `NULL` 类型。
36+
3. 值按行优先顺序排列：第一个输出行获得每个输出列的第一个值，第二个输出行获得每个输出列的第二个值，以此类推。
37+
4. `stack` 是表生成函数，通常与 `LATERAL VIEW` 配合使用。
38+
39+
## 示例
40+
41+
### 基本用法
42+
43+
```sql
44+
SELECT c1, c2
45+
FROM (SELECT 1) t
46+
LATERAL VIEW stack(2, 1, 2, 3) s AS c1, c2
47+
ORDER BY c1, c2;
48+
```
49+
50+
```text
51+
+------+------+
52+
| c1 | c2 |
53+
+------+------+
54+
| 1 | 2 |
55+
| 3 | NULL |
56+
+------+------+
57+
```
58+
59+
### 行优先排列
60+
61+
```sql
62+
SELECT c1, c2
63+
FROM (SELECT 1) t
64+
LATERAL VIEW stack(3, 1, 'a', 2, 'b', 3, 'c') s AS c1, c2
65+
ORDER BY c1, c2;
66+
```
67+
68+
```text
69+
+------+------+
70+
| c1 | c2 |
71+
+------+------+
72+
| 1 | a |
73+
| 2 | b |
74+
| 3 | c |
75+
+------+------+
76+
```
77+
78+
如果表达式数量不足以填满最后一行，缺少的值为 `NULL`：
79+
80+
```sql
81+
SELECT c1
82+
FROM (SELECT 1) t
83+
LATERAL VIEW stack(4, 1, 2, 3) s AS c1
84+
ORDER BY c1;
85+
```
86+
87+
```text
88+
+------+
89+
| c1 |
90+
+------+
91+
| NULL |
92+
| 1 |
93+
| 2 |
94+
| 3 |
95+
+------+
96+
```
97+
98+
### 列表达式和类型检查
99+
100+
```sql
101+
SELECT id, c1, c2
102+
FROM (
103+
SELECT 1 AS id, 10 AS a, 'x' AS s1, 20 AS b, 'y' AS s2
104+
) AS test_stack
105+
LATERAL VIEW stack(2, a, s1, b, s2) s AS c1, c2
106+
ORDER BY id, c1, c2;
107+
```
108+
109+
```text
110+
+------+------+------+
111+
| id | c1 | c2 |
112+
+------+------+------+
113+
| 1 | 10 | x |
114+
| 1 | 20 | y |
115+
+------+------+------+
116+
```
117+
118+
表达式会针对每个输入行求值。在本例中，`a` 和 `b` 组成一个输出列，`s1` 和 `s2` 组成另一个输出列。如果分配到同一输出列的表达式类型不兼容，查询将返回分析错误。
119+
120+
`NULL` 表达式可以与其他类型的值一起使用；`NULL` 值会在结果中作为补充值或原值保留。

0 commit comments

Comments
 (0)