databendlabs · bohutang · Dec 31, 2025 · Dec 31, 2025
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/_category_.json b/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/_category_.json
@@ -1,3 +1,4 @@
 {
-  "label": "计算集群"
-}
+  "label": "计算集群",
+  "position": 19
+}
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/alter-warehouse.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/alter-warehouse.md
@@ -0,0 +1,77 @@
+---
+title: ALTER WAREHOUSE
+sidebar_position: 4
+---
+
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="引入或更新于：v1.2.687"/>
+
+暂停、恢复或修改计算集群配置。
+
+## 语法
+
+```sql
+-- 暂停或恢复
+ALTER WAREHOUSE <warehouse_name> { SUSPEND | RESUME }
+
+-- 修改配置
+ALTER WAREHOUSE <warehouse_name>
+    SET [ WITH ] warehouse_size = <size>
+    [ WITH ] auto_suspend = <nullable_unsigned_number>
+    [ WITH ] auto_resume = <bool>
+    [ WITH ] max_cluster_count = <nullable_unsigned_number>
+    [ WITH ] min_cluster_count = <nullable_unsigned_number>
+    [ WITH ] comment = '<string_literal>'
+```
+
+| 参数 | 说明 |
+|------|------|
+| `SUSPEND` | 立即暂停计算集群。 |
+| `RESUME` | 立即恢复计算集群。 |
+| `SET` | 修改一个或多个选项，未指定的选项保持不变。 |
+
+## 选项
+
+`SET` 子句支持与 [CREATE WAREHOUSE](create-warehouse.md) 相同的选项：
+
+| 选项 | 类型 / 取值 | 说明 |
+|------|-------------|------|
+| `WAREHOUSE_SIZE` | `XSmall`、`Small`、`Medium`、`Large`、`XLarge`、`2XLarge`–`6XLarge` | 修改规格。 |
+| `AUTO_SUSPEND` | `NULL`、`0` 或 ≥300 秒 | 空闲自动暂停时间。`NULL` 表示禁用。 |
+| `AUTO_RESUME` | 布尔值 | 是否自动恢复。 |
+| `MAX_CLUSTER_COUNT` | `NULL` 或非负整数 | 最大集群数。 |
+| `MIN_CLUSTER_COUNT` | `NULL` 或非负整数 | 最小集群数。 |
+| `COMMENT` | 字符串 | 备注信息。 |
+
+- 数值选项设为 `NULL` 会重置为 `0`。
+- `SET` 后不带任何选项会报错。
+
+## 示例
+
+暂停计算集群：
+
+```sql
+ALTER WAREHOUSE my_wh SUSPEND;
+```
+
+恢复计算集群：
+
+```sql
+ALTER WAREHOUSE my_wh RESUME;
+```
+
+修改配置：
+
+```sql
+ALTER WAREHOUSE my_wh
+    SET warehouse_size = Large
+    auto_resume = TRUE
+    comment = '生产环境';
+```
+
+禁用自动暂停：
+
+```sql
+ALTER WAREHOUSE my_wh SET auto_suspend = NULL;
+```
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/create-warehouse.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/create-warehouse.md
@@ -1,29 +1,65 @@
 ---
 title: CREATE WAREHOUSE
+sidebar_position: 1
 ---
 
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
 <FunctionDescription description="引入或更新于：v1.2.687"/>
 
-创建一个具有指定大小的计算集群。
+创建计算集群。
 
 ## 语法
 
 ```sql
-CREATE WAREHOUSE '<warehouse_name>'
-    WITH WAREHOUSE_SIZE = '<warehouse_size>'
+CREATE WAREHOUSE [ IF NOT EXISTS ] <warehouse_name>
+    [ WITH ] warehouse_size = <size>
+    [ WITH ] auto_suspend = <nullable_unsigned_number>
+    [ WITH ] initially_suspended = <bool>
+    [ WITH ] auto_resume = <bool>
+    [ WITH ] max_cluster_count = <nullable_unsigned_number>
+    [ WITH ] min_cluster_count = <nullable_unsigned_number>
+    [ WITH ] comment = '<string_literal>'
 ```
 
-说明：
+| 参数 | 说明 |
+|------|------|
+| `IF NOT EXISTS` | 可选。若计算集群已存在则不执行任何操作。 |
+| warehouse_name | 长度 3–63 个字符，仅支持 `A-Z`、`a-z`、`0-9` 和 `-`。 |
 
-- `<warehouse_name>` 只能包含英文字母、数字和 `-`。建议统一使用单引号包裹。
-- `<warehouse_size>` 不区分大小写，可选值为：`XSMALL`、`SMALL`、`MEDIUM`、`LARGE`、`XLARGE`、`XXLARGE`、`XXXLARGE`。建议统一使用单引号包裹。
+## 选项
+
+| 选项 | 类型 / 取值 | 默认值 | 说明 |
+|------|-------------|--------|------|
+| `WAREHOUSE_SIZE` | `XSmall`、`Small`、`Medium`、`Large`、`XLarge`、`2XLarge`–`6XLarge`（不区分大小写） | `Small` | 计算集群规格。 |
+| `AUTO_SUSPEND` | `NULL`、`0` 或 ≥300 秒 | `600` 秒 | 空闲自动暂停时间。`0` 或 `NULL` 表示不自动暂停；小于 300 秒会报错。 |
+| `INITIALLY_SUSPENDED` | 布尔值 | `FALSE` | 设为 `TRUE` 时，创建后保持暂停状态，需手动恢复。 |
+| `AUTO_RESUME` | 布尔值 | `TRUE` | 是否在收到查询时自动恢复。 |
+| `MAX_CLUSTER_COUNT` | `NULL` 或非负整数 | `0` | 自动扩缩容的最大集群数。`0` 表示禁用。 |
+| `MIN_CLUSTER_COUNT` | `NULL` 或非负整数 | `0` | 自动扩缩容的最小集群数，应 ≤ `MAX_CLUSTER_COUNT`。 |
+| `COMMENT` | 字符串 | 空 | 备注信息，可通过 `SHOW WAREHOUSES` 查看。 |
+
+- 选项可任意顺序，重复时以最后一个为准。
+- `AUTO_SUSPEND`、`MAX_CLUSTER_COUNT`、`MIN_CLUSTER_COUNT` 设为 `NULL` 会重置为 `0`。
 
 ## 示例
 
-此示例创建一个 `XSMALL` 规格的计算集群：
+创建带自动扩缩容的 XLarge 计算集群：
+
+```sql
+CREATE WAREHOUSE IF NOT EXISTS etl_wh
+    WITH warehouse_size = XLarge
+    auto_suspend = 600
+    initially_suspended = TRUE
+    auto_resume = FALSE
+    max_cluster_count = 4
+    min_cluster_count = 2
+    comment = 'ETL 专用集群';
+```
+
+创建 Small 规格的计算集群：
 
 ```sql
-CREATE WAREHOUSE 'testwarehouse' WITH WAREHOUSE_SIZE = 'XSMALL';
+CREATE WAREHOUSE my_warehouse
+    WITH warehouse_size = Small;
 ```
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/drop-warehouse.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/drop-warehouse.md
@@ -1,24 +1,35 @@
 ---
 title: DROP WAREHOUSE
+sidebar_position: 5
 ---
+
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
 <FunctionDescription description="引入或更新于：v1.2.687"/>
 
-删除指定的计算集群并释放与其关联的资源。
+删除计算集群并释放相关资源。
 
 ## 语法
 
 ```sql
-DROP WAREHOUSE '<warehouse_name>'
+DROP WAREHOUSE [ IF EXISTS ] <warehouse_name>
 ```
 
-建议统一使用单引号包裹 `<warehouse_name>`。
+| 参数 | 说明 |
+|------|------|
+| `IF EXISTS` | 可选。若计算集群不存在则不报错。 |
+| warehouse_name | 要删除的计算集群名称。 |
 
 ## 示例
 
-此示例删除 `testwarehouse` 计算集群：
+删除计算集群：
+
+```sql
+DROP WAREHOUSE my_warehouse;
+```
+
+仅在存在时删除：
 
 ```sql
-DROP WAREHOUSE 'testwarehouse';
+DROP WAREHOUSE IF EXISTS my_warehouse;
 ```
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/index.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/index.md
@@ -1,23 +1,30 @@
 ---
 title: 计算集群（Warehouse）
+sidebar_position: 0
 ---
 
-计算集群相关的 SQL 命令。
+Databend Cloud 计算集群相关的 SQL 命令。
 
-## 计算集群管理
+## 基本规则
 
-| 命令 | 描述 |
-|---------|-------------|
-| [CREATE WAREHOUSE](create-warehouse.md) | 创建新的计算集群用于计算资源 |
-| [DROP WAREHOUSE](drop-warehouse.md) | 删除计算集群 |
-| [USE WAREHOUSE](use-warehouse.md) | 为当前会话设置计算集群 |
+- **命名规范**：长度 3–63 个字符，仅支持 `A-Z`、`a-z`、`0-9` 和 `-`。
+- **标识符**：不含空格或特殊字符时可省略引号，否则需用单引号包裹。
+- **数值参数**：支持整数或 `NULL`。设为 `NULL` 会重置为默认值（如 `AUTO_SUSPEND = NULL` 等同于 `0`）。
+- **布尔参数**：仅接受 `TRUE` / `FALSE`。
+- **`WITH` 关键字**：可放在整个选项列表前，也可放在每个选项前。选项间用空格分隔。
 
-## 计算集群信息
+## 计算集群管理
 
 | 命令 | 描述 |
-|---------|-------------|
-| [SHOW WAREHOUSES](show-warehouses.md) | 列出所有计算集群 |
+|------|------|
+| [CREATE WAREHOUSE](create-warehouse.md) | 创建计算集群 |
+| [USE WAREHOUSE](use-warehouse.md) | 切换当前会话的计算集群 |
+| [SHOW WAREHOUSES](show-warehouses.md) | 查看计算集群列表 |
+| [ALTER WAREHOUSE](alter-warehouse.md) | 暂停、恢复或修改计算集群配置 |
+| [DROP WAREHOUSE](drop-warehouse.md) | 删除计算集群 |
+| [REPLACE WAREHOUSE](replace-warehouse.md) | 重建计算集群 |
+| [QUERY_HISTORY](query-history.md) | 查询执行历史记录 |
 
 :::note
-计算集群代表用于执行查询的计算资源。
+计算集群是 Databend Cloud 中用于执行查询的计算资源。
 :::
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/query-history.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/query-history.md
@@ -0,0 +1,62 @@
+---
+title: QUERY_HISTORY
+sidebar_position: 7
+---
+
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="引入或更新于：v1.2.687"/>
+
+查询执行历史记录，用于分析和监控。
+
+## 语法
+
+```sql
+QUERY_HISTORY
+    [ BY WAREHOUSE <warehouse_name> ]
+    [ FROM '<timestamp>' ]
+    [ TO '<timestamp>' ]
+    [ LIMIT <unsigned_integer> ]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `BY WAREHOUSE` | 可选。按计算集群过滤，名称不能为空。 |
+| `FROM` | 可选。起始时间，格式 `YYYY-MM-DD HH:MM:SS`。默认为 `TO` 前 1 小时。 |
+| `TO` | 可选。结束时间，格式 `YYYY-MM-DD HH:MM:SS`。默认为当前时间。 |
+| `LIMIT` | 可选。返回记录数上限，默认 `10`，必须为正整数。 |
+
+## 输出列
+
+返回结果包含以下列：
+
+| 列名 | 说明 |
+|------|------|
+| `query_id` | 查询唯一标识 |
+| `query_text` | SQL 语句 |
+| `scan_bytes` | 扫描数据量 |
+| ... | 其他查询指标 |
+
+## 示例
+
+查询指定集群的历史记录：
+
+```sql
+QUERY_HISTORY
+    BY WAREHOUSE etl_wh
+    FROM '2023-08-20 00:00:00'
+    TO '2023-08-20 06:00:00'
+    LIMIT 200;
+```
+
+查询最近 10 条记录：
+
+```sql
+QUERY_HISTORY;
+```
+
+指定返回数量：
+
+```sql
+QUERY_HISTORY LIMIT 50;
+```
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/replace-warehouse.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/19-warehouse/replace-warehouse.md
@@ -0,0 +1,43 @@
+---
+title: REPLACE WAREHOUSE
+sidebar_position: 6
+---
+
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="引入或更新于：v1.2.687"/>
+
+重建计算集群。语义与 [CREATE WAREHOUSE](create-warehouse.md) 相同，适用于覆盖已有配置的场景。
+
+## 语法
+
+```sql
+REPLACE WAREHOUSE <warehouse_name>
+    [ WITH ] warehouse_size = <size>
+    [ WITH ] auto_suspend = <nullable_unsigned_number>
+    [ WITH ] initially_suspended = <bool>
+    [ WITH ] auto_resume = <bool>
+    [ WITH ] max_cluster_count = <nullable_unsigned_number>
+    [ WITH ] min_cluster_count = <nullable_unsigned_number>
+    [ WITH ] comment = '<string_literal>'
+```
+
+| 参数 | 说明 |
+|------|------|
+| warehouse_name | 长度 3–63 个字符，仅支持 `A-Z`、`a-z`、`0-9` 和 `-`。 |
+
+## 选项
+
+参见 [CREATE WAREHOUSE](create-warehouse.md#选项)。
+
+## 示例
+
+使用新配置重建计算集群：
+
+```sql
+REPLACE WAREHOUSE etl_wh
+    WITH warehouse_size = Large
+    auto_suspend = 300
+    auto_resume = TRUE
+    comment = '更新后的 ETL 集群';
+```