Skip to content

Commit dd0ce4c

Browse files
BohuTANGclaude
BohuTANG
and
claude
committed
docs: update warehouse SQL documentation
- Add complete options for CREATE WAREHOUSE (auto_suspend, auto_resume, cluster scaling, etc.) - Add new commands: ALTER WAREHOUSE, REPLACE WAREHOUSE, QUERY_HISTORY - Add IF NOT EXISTS/IF EXISTS clauses to CREATE/DROP WAREHOUSE - Add LIKE pattern filtering to SHOW WAREHOUSES - Reorder sidebar by usage frequency (CREATE → USE → SHOW → ALTER → DROP → REPLACE → QUERY_HISTORY) - Update both en and cn documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
1 parent eb9cfb9 commit dd0ce4c

File tree

18 files changed

+603
-66
lines changed

18 files changed

+603
-66
lines changed

‎docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/_category_.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
{
2-
"label": "计算集群"
3-
}
2+
"label": "计算集群",
3+
"position": 19
4+
}

‎docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/alter-warehouse.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: ALTER WAREHOUSE
3+
sidebar_position: 4
4+
---
5+
6+
import FunctionDescription from '@site/src/components/FunctionDescription';
7+
8+
<FunctionDescription description="引入或更新于：v1.2.687"/>
9+
10+
暂停、恢复或修改计算集群配置。
11+
12+
## 语法
13+
14+
```sql
15+
-- 暂停或恢复
16+
ALTER WAREHOUSE <warehouse_name> { SUSPEND | RESUME }
17+
18+
-- 修改配置
19+
ALTER WAREHOUSE <warehouse_name>
20+
SET [ WITH ] warehouse_size = <size>
21+
[ WITH ] auto_suspend = <nullable_unsigned_number>
22+
[ WITH ] auto_resume = <bool>
23+
[ WITH ] max_cluster_count = <nullable_unsigned_number>
24+
[ WITH ] min_cluster_count = <nullable_unsigned_number>
25+
[ WITH ] comment = '<string_literal>'
26+
```
27+
28+
| 参数 | 说明 |
29+
|------|------|
30+
| `SUSPEND` | 立即暂停计算集群。 |
31+
| `RESUME` | 立即恢复计算集群。 |
32+
| `SET` | 修改一个或多个选项，未指定的选项保持不变。 |
33+
34+
## 选项
35+
36+
`SET` 子句支持与 [CREATE WAREHOUSE](create-warehouse.md) 相同的选项：
37+
38+
| 选项 | 类型 / 取值 | 说明 |
39+
|------|-------------|------|
40+
| `WAREHOUSE_SIZE` | `XSmall`、`Small`、`Medium`、`Large`、`XLarge`、`2XLarge`–`6XLarge` | 修改规格。 |
41+
| `AUTO_SUSPEND` | `NULL`、`0` 或 ≥60 秒 | 空闲自动暂停时间。`NULL` 表示禁用。 |
42+
| `AUTO_RESUME` | 布尔值 | 是否自动恢复。 |
43+
| `MAX_CLUSTER_COUNT` | `NULL` 或非负整数 | 最大集群数。 |
44+
| `MIN_CLUSTER_COUNT` | `NULL` 或非负整数 | 最小集群数。 |
45+
| `COMMENT` | 字符串 | 备注信息。 |
46+
47+
- 数值选项设为 `NULL` 会重置为 `0`。
48+
- `SET` 后不带任何选项会报错。
49+
50+
## 示例
51+
52+
暂停计算集群：
53+
54+
```sql
55+
ALTER WAREHOUSE my_wh SUSPEND;
56+
```
57+
58+
恢复计算集群：
59+
60+
```sql
61+
ALTER WAREHOUSE my_wh RESUME;
62+
```
63+
64+
修改配置：
65+
66+
```sql
67+
ALTER WAREHOUSE my_wh
68+
SET warehouse_size = Large
69+
auto_resume = TRUE
70+
comment = '生产环境';
71+
```
72+
73+
禁用自动暂停：
74+
75+
```sql
76+
ALTER WAREHOUSE my_wh SET auto_suspend = NULL;
77+
```

‎docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/create-warehouse.md‎

Lines changed: 44 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,65 @@
11
---
22
title: CREATE WAREHOUSE
3+
sidebar_position: 1
34
---
45

56
import FunctionDescription from '@site/src/components/FunctionDescription';
67

78
<FunctionDescription description="引入或更新于：v1.2.687"/>
89

9-
创建一个具有指定大小的计算集群。
10+
创建计算集群。
1011

1112
## 语法
1213

1314
```sql
14-
CREATE WAREHOUSE '<warehouse_name>'
15-
WITH WAREHOUSE_SIZE = '<warehouse_size>'
15+
CREATE WAREHOUSE [ IF NOT EXISTS ] <warehouse_name>
16+
[ WITH ] warehouse_size = <size>
17+
[ WITH ] auto_suspend = <nullable_unsigned_number>
18+
[ WITH ] initially_suspended = <bool>
19+
[ WITH ] auto_resume = <bool>
20+
[ WITH ] max_cluster_count = <nullable_unsigned_number>
21+
[ WITH ] min_cluster_count = <nullable_unsigned_number>
22+
[ WITH ] comment = '<string_literal>'
1623
```
1724

18-
说明：
25+
| 参数 | 说明 |
26+
|------|------|
27+
| `IF NOT EXISTS` | 可选。若计算集群已存在则不执行任何操作。 |
28+
| warehouse_name | 长度 3–63 个字符，仅支持 `A-Z`、`a-z`、`0-9` 和 `-`。以 `~` 开头的名称为系统保留。 |
1929

20-
- `<warehouse_name>` 只能包含英文字母、数字和 `-`。建议统一使用单引号包裹。
21-
- `<warehouse_size>` 不区分大小写，可选值为：`XSMALL`、`SMALL`、`MEDIUM`、`LARGE`、`XLARGE`、`XXLARGE`、`XXXLARGE`。建议统一使用单引号包裹。
30+
## 选项
31+
32+
| 选项 | 类型 / 取值 | 默认值 | 说明 |
33+
|------|-------------|--------|------|
34+
| `WAREHOUSE_SIZE` | `XSmall`、`Small`、`Medium`、`Large`、`XLarge`、`2XLarge`–`6XLarge`（不区分大小写） | `Small` | 计算集群规格。 |
35+
| `AUTO_SUSPEND` | `NULL`、`0` 或 ≥60 秒 | `600` 秒 | 空闲自动暂停时间。`0` 或 `NULL` 表示不自动暂停；小于 60 秒会报错。 |
36+
| `INITIALLY_SUSPENDED` | 布尔值 | `FALSE` | 设为 `TRUE` 时，创建后保持暂停状态，需手动恢复。 |
37+
| `AUTO_RESUME` | 布尔值 | `TRUE` | 是否在收到查询时自动恢复。 |
38+
| `MAX_CLUSTER_COUNT` | `NULL` 或非负整数 | `0` | 自动扩缩容的最大集群数。`0` 表示禁用。 |
39+
| `MIN_CLUSTER_COUNT` | `NULL` 或非负整数 | `0` | 自动扩缩容的最小集群数，应 ≤ `MAX_CLUSTER_COUNT`。 |
40+
| `COMMENT` | 字符串 | 空 | 备注信息，可通过 `SHOW WAREHOUSES` 查看。 |
41+
42+
- 选项可任意顺序，重复时以最后一个为准。
43+
- `AUTO_SUSPEND`、`MAX_CLUSTER_COUNT`、`MIN_CLUSTER_COUNT` 设为 `NULL` 会重置为 `0`。
2244

2345
## 示例
2446

25-
此示例创建一个 `XSMALL` 规格的计算集群：
47+
创建带自动扩缩容的 XLarge 计算集群：
48+
49+
```sql
50+
CREATE WAREHOUSE IF NOT EXISTS etl_wh
51+
WITH warehouse_size = XLarge
52+
auto_suspend = 600
53+
initially_suspended = TRUE
54+
auto_resume = FALSE
55+
max_cluster_count = 4
56+
min_cluster_count = 2
57+
comment = 'ETL 专用集群';
58+
```
59+
60+
创建 Small 规格的计算集群：
2661

2762
```sql
28-
CREATE WAREHOUSE 'testwarehouse' WITH WAREHOUSE_SIZE = 'XSMALL';
63+
CREATE WAREHOUSE my_warehouse
64+
WITH warehouse_size = Small;
2965
```

‎docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/drop-warehouse.md‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,35 @@
11
---
22
title: DROP WAREHOUSE
3+
sidebar_position: 5
34
---
5+
46
import FunctionDescription from '@site/src/components/FunctionDescription';
57

68
<FunctionDescription description="引入或更新于：v1.2.687"/>
79

8-
删除指定的计算集群并释放与其关联的资源。
10+
删除计算集群并释放相关资源。
911

1012
## 语法
1113

1214
```sql
13-
DROP WAREHOUSE '<warehouse_name>'
15+
DROP WAREHOUSE [ IF EXISTS ] <warehouse_name>
1416
```
1517

16-
建议统一使用单引号包裹 `<warehouse_name>`。
18+
| 参数 | 说明 |
19+
|------|------|
20+
| `IF EXISTS` | 可选。若计算集群不存在则不报错。 |
21+
| warehouse_name | 要删除的计算集群名称。以 `~` 开头的名称为系统保留，会被拒绝。 |
1722

1823
## 示例
1924

20-
此示例删除 `testwarehouse` 计算集群：
25+
删除计算集群：
26+
27+
```sql
28+
DROP WAREHOUSE my_warehouse;
29+
```
30+
31+
仅在存在时删除：
2132

2233
```sql
23-
DROP WAREHOUSE 'testwarehouse';
34+
DROP WAREHOUSE IF EXISTS my_warehouse;
2435
```

‎docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/index.md‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,30 @@
11
---
22
title: 计算集群（Warehouse）
3+
sidebar_position: 0
34
---
45

5-
计算集群相关的 SQL 命令。
6+
Databend Cloud 计算集群相关的 SQL 命令。
67

7-
## 计算集群管理
8+
## 基本规则
89

9-
| 命令 | 描述 |
10-
|---------|-------------|
11-
| [CREATE WAREHOUSE](create-warehouse.md) | 创建新的计算集群用于计算资源 |
12-
| [DROP WAREHOUSE](drop-warehouse.md) | 删除计算集群 |
13-
| [USE WAREHOUSE](use-warehouse.md) | 为当前会话设置计算集群 |
10+
- **命名规范**：长度 3–63 个字符，仅支持 `A-Z`、`a-z`、`0-9` 和 `-`。以 `~` 开头的名称为系统保留。
11+
- **标识符**：不含空格或特殊字符时可省略引号，否则需用单引号包裹。
12+
- **数值参数**：支持整数或 `NULL`。设为 `NULL` 会重置为默认值（如 `AUTO_SUSPEND = NULL` 等同于 `0`）。
13+
- **布尔参数**：仅接受 `TRUE` / `FALSE`。
14+
- **`WITH` 关键字**：可放在整个选项列表前，也可放在每个选项前。选项间用空格分隔。
1415

15-
## 计算集群信息
16+
## 计算集群管理
1617

1718
| 命令 | 描述 |
18-
|---------|-------------|
19-
| [SHOW WAREHOUSES](show-warehouses.md) | 列出所有计算集群 |
19+
|------|------|
20+
| [CREATE WAREHOUSE](create-warehouse.md) | 创建计算集群 |
21+
| [USE WAREHOUSE](use-warehouse.md) | 切换当前会话的计算集群 |
22+
| [SHOW WAREHOUSES](show-warehouses.md) | 查看计算集群列表 |
23+
| [ALTER WAREHOUSE](alter-warehouse.md) | 暂停、恢复或修改计算集群配置 |
24+
| [DROP WAREHOUSE](drop-warehouse.md) | 删除计算集群 |
25+
| [REPLACE WAREHOUSE](replace-warehouse.md) | 重建计算集群 |
26+
| [QUERY_HISTORY](query-history.md) | 查询执行历史记录 |
2027

2128
:::note
22-
计算集群代表用于执行查询的计算资源。
29+
计算集群是 Databend Cloud 中用于执行查询的计算资源。
2330
:::

‎docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/query-history.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: QUERY_HISTORY
3+
sidebar_position: 7
4+
---
5+
6+
import FunctionDescription from '@site/src/components/FunctionDescription';
7+
8+
<FunctionDescription description="引入或更新于：v1.2.687"/>
9+
10+
查询执行历史记录，用于分析和监控。
11+
12+
## 语法
13+
14+
```sql
15+
QUERY_HISTORY
16+
[ BY WAREHOUSE <warehouse_name> ]
17+
[ FROM '<timestamp>' ]
18+
[ TO '<timestamp>' ]
19+
[ LIMIT <unsigned_integer> ]
20+
```
21+
22+
| 参数 | 说明 |
23+
|------|------|
24+
| `BY WAREHOUSE` | 可选。按计算集群过滤，名称不能为空。 |
25+
| `FROM` | 可选。起始时间，格式 `YYYY-MM-DD HH:MM:SS`。默认为 `TO` 前 1 小时。 |
26+
| `TO` | 可选。结束时间，格式 `YYYY-MM-DD HH:MM:SS`。默认为当前时间。 |
27+
| `LIMIT` | 可选。返回记录数上限，默认 `10`，必须为正整数。 |
28+
29+
## 输出列
30+
31+
返回结果包含以下列：
32+
33+
| 列名 | 说明 |
34+
|------|------|
35+
| `query_id` | 查询唯一标识 |
36+
| `query_text` | SQL 语句 |
37+
| `scan_bytes` | 扫描数据量 |
38+
| ... | 其他查询指标 |
39+
40+
## 示例
41+
42+
查询指定集群的历史记录：
43+
44+
```sql
45+
QUERY_HISTORY
46+
BY WAREHOUSE etl_wh
47+
FROM '2023-08-20 00:00:00'
48+
TO '2023-08-20 06:00:00'
49+
LIMIT 200;
50+
```
51+
52+
查询最近 10 条记录：
53+
54+
```sql
55+
QUERY_HISTORY;
56+
```
57+
58+
指定返回数量：
59+
60+
```sql
61+
QUERY_HISTORY LIMIT 50;
62+
```

‎docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/replace-warehouse.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: REPLACE WAREHOUSE
3+
sidebar_position: 6
4+
---
5+
6+
import FunctionDescription from '@site/src/components/FunctionDescription';
7+
8+
<FunctionDescription description="引入或更新于：v1.2.687"/>
9+
10+
重建计算集群。语义与 [CREATE WAREHOUSE](create-warehouse.md) 相同，适用于覆盖已有配置的场景。
11+
12+
## 语法
13+
14+
```sql
15+
REPLACE WAREHOUSE <warehouse_name>
16+
[ WITH ] warehouse_size = <size>
17+
[ WITH ] auto_suspend = <nullable_unsigned_number>
18+
[ WITH ] initially_suspended = <bool>
19+
[ WITH ] auto_resume = <bool>
20+
[ WITH ] max_cluster_count = <nullable_unsigned_number>
21+
[ WITH ] min_cluster_count = <nullable_unsigned_number>
22+
[ WITH ] comment = '<string_literal>'
23+
```
24+
25+
| 参数 | 说明 |
26+
|------|------|
27+
| warehouse_name | 长度 3–63 个字符，仅支持 `A-Z`、`a-z`、`0-9` 和 `-`。以 `~` 开头的名称为系统保留。 |
28+
29+
## 选项
30+
31+
参见 [CREATE WAREHOUSE](create-warehouse.md#选项)。
32+
33+
## 示例
34+
35+
使用新配置重建计算集群：
36+
37+
```sql
38+
REPLACE WAREHOUSE etl_wh
39+
WITH warehouse_size = Large
40+
auto_suspend = 300
41+
auto_resume = TRUE
42+
comment = '更新后的 ETL 集群';
43+
```

0 commit comments

Comments
 (0)