@clickzetta/cz-cli-darwin-x64 0.3.17 → 0.3.18

package/bin/skills/clickzetta-table-stream-pipeline/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: clickzetta-table-stream-pipeline
+description: |
+  搭建和管理 ClickZetta Table Stream 变更数据捕获管道，覆盖从源表配置、Stream 创建、
+  数据消费到增量 ETL 的端到端工作流。当用户说"创建 Table Stream"、"Table Stream CDC"、
+  "Table Stream 管道"、"Table Stream 增量消费"、"Stream 消费"时触发。
+  包含变更跟踪开启、模式选择、offset 管理、元数据字段使用、幂等消费等 ClickZetta 特有逻辑。
+  Keywords: table stream, CDC, change capture, incremental ETL, stream
+---
+
+# Table Stream 变更数据捕获工作流
+
+## 指令
+
+### 步骤 1：开启源表变更跟踪（必需前置）
+执行 SQL 开启源表的 change_tracking：
+```sql
+ALTER TABLE <source_table> SET PROPERTIES ('change_tracking' = 'true');
+```
+- 这是强制性前置步骤，不执行则 Stream 无法正确捕获变更
+- 验证属性是否生效（两种方法）：
+```sql
+-- 方法 1：DESC EXTENDED 查看 properties
+DESC EXTENDED <source_table>;
+
+-- 方法 2：查询 information_schema
+SELECT table_name, properties FROM information_schema.tables WHERE table_name = '<source_table>';
+```
+
+### 步骤 2：创建 Table Stream
+执行 SQL 创建 Stream：
+```sql
+CREATE [ OR REPLACE ] TABLE STREAM <stream_name>
+  ON TABLE <source_table>
+  [ TIMESTAMP AS OF '<timestamp>' ]
+  [ COMMENT '<描述>' ]
+  WITH PROPERTIES (
+    'TABLE_STREAM_MODE' = 'STANDARD | APPEND_ONLY',
+    'SHOW_INITIAL_ROWS' = 'TRUE | FALSE'
+  );
+```
+关键参数选择：
+- **STANDARD 模式**：捕获 INSERT/UPDATE/DELETE，反映表当前状态（delta 变化） → 适用于数据同步、增量 ETL
+  - delta 变化指两个事务时间点之间的净变化。例如：先 INSERT 再 DELETE 同一行 → delta 为空；先 INSERT 再 UPDATE → delta 为一条新行（最终状态）
+- **APPEND_ONLY 模式**：仅捕获 INSERT，保留所有历史插入记录 → 适用于审计、历史记录保留
+  - 即使后续 DELETE 了某行，APPEND_ONLY 模式仍保留该行的 INSERT 记录
+- **SHOW_INITIAL_ROWS = TRUE**：首次消费返回建 Stream 时表中已有行
+- **SHOW_INITIAL_ROWS = FALSE**（默认）：首次消费仅返回建 Stream 后的新变更
+- 可选：指定起始时间点
+```sql
+-- TIMESTAMP AS OF 用于指定 Stream 的起始读取位点
+-- 注意：此功能在某些场景下可能不稳定，建议优先使用默认行为（从创建时刻开始）
+CREATE TABLE STREAM <stream_name>
+  ON TABLE <source_table>
+  TIMESTAMP AS OF '<timestamp>'
+  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD');
+```
+
+### 步骤 3：准备目标表
+创建与源表结构兼容的目标表：
+- 目标表列定义需包含源表的业务列
+- 建议额外添加元数据列（如 sync_version、sync_timestamp）用于追踪
+
+### 步骤 4：查询 Stream 数据（预览，不移动 offset）
+执行 SELECT 预览 Stream 中的变更数据：
+```sql
+SELECT *, __change_type, __commit_version, __commit_timestamp
+FROM <stream_name>;
+```
+- 仅 SELECT 不会移动 offset
+- 元数据字段：`__change_type`（值：`INSERT` / `UPDATE_BEFORE` / `UPDATE_AFTER` / `DELETE`）、`__commit_version`、`__commit_timestamp`
+- **UPDATE 处理要点**：UPDATE 操作产生两条记录：
+  - `UPDATE_BEFORE`：更新前的旧值（通常在消费时忽略）
+  - `UPDATE_AFTER`：更新后的新值（用于写入目标表）
+  - 消费时务必过滤 `__change_type`，避免将 `UPDATE_BEFORE` 旧值误写入目标表
+
+### 步骤 5：消费 Stream 数据（移动 offset）
+执行 DML 操作消费数据：
+
+#### 方式 A：全量消费（INSERT INTO）
+```sql
+INSERT INTO <target_table>
+SELECT <columns> FROM <stream_name>;
+```
+
+#### 方式 B：幂等消费（MERGE，推荐）
+```sql
+MERGE INTO <target_table> t
+USING (SELECT * FROM <stream_name> WHERE __change_type != 'UPDATE_BEFORE') s
+ON t.<pk_column> = s.<pk_column>
+WHEN MATCHED AND s.__change_type IN ('INSERT', 'UPDATE_AFTER') THEN UPDATE SET t.col1 = s.col1, t.col2 = s.col2
+WHEN MATCHED AND s.__change_type = 'DELETE' THEN DELETE
+WHEN NOT MATCHED AND s.__change_type = 'INSERT' THEN INSERT (<columns>) VALUES (s.<columns>);
+```
+- DML 操作（INSERT/UPDATE/MERGE）会移动 offset
+- ⚠️ 即使使用 WHERE 条件过滤，**所有数据的 offset 仍会移动**（不仅是匹配的行）
+- 推荐使用 MERGE 实现幂等性，避免重复消费导致数据重复
+- 在 USING 子查询中过滤掉 `UPDATE_BEFORE`，避免旧值干扰 MERGE 逻辑
+- ⚠️ **MERGE 语法顺序要求**：多个 `WHEN MATCHED` 子句时，**UPDATE 必须在 DELETE 之前**，否则报错（错误信息：`update statement must be before delete statement`）
+
+### 步骤 6：验证消费状态
+执行查询确认消费完成：
+```sql
+SELECT COUNT(*) FROM <stream_name>;
+```
+- 消费成功后 COUNT 应为 0 或仅包含新变更
+- 记录最后消费的 `__commit_version` 用于故障恢复
+
+## Offset 移动规则
+
+| 操作 | 是否移动 offset | 说明 |
+|------|----------------|------|
+| `SELECT * FROM stream` | ❌ 不移动 | 仅预览，可反复查询 |
+| `INSERT INTO target SELECT ... FROM stream` | ✅ 移动 | 消费数据 |
+| `MERGE INTO target USING stream ...` | ✅ 移动 | 消费数据（推荐） |
+| `UPDATE target SET ... FROM stream` | ✅ 移动 | 消费数据 |
+| `DELETE FROM target USING stream` | ✅ 移动 | 消费数据 |
+| 带 WHERE 的 DML | ✅ 全部移动 | 即使 WHERE 过滤了部分行，所有行的 offset 都会移动 |
+
+> ⚠️ **关键注意**：offset 移动是全量的。一旦执行 DML 消费 Stream，所有变更记录的 offset 都会前进，无法部分消费。如果 DML 执行失败（如目标表不存在），offset 不会移动。
+
+## 模式选择速查
+
+| 需求 | 推荐模式 |
+|------|---------|
+| 数据同步（保持目标与源一致） | STANDARD |
+| 增量 ETL 流程 | STANDARD |
+| 审计所有插入记录 | APPEND_ONLY |
+| 历史记录保留 | APPEND_ONLY |
+
+## 性能优化要点
+
+- 只 SELECT 必要列，避免 `SELECT *`
+- 定期消费 Stream，避免数据累积
+- 高变更率表：更频繁消费；低变更率表：降低频率
+- 大型 Stream 可按主键范围拆分并行处理
+- 在源表上设置适当的数据保留期
+
+## 示例
+
+### 示例 1：订单表实时同步
+```sql
+-- 1. 开启源表变更跟踪
+ALTER TABLE orders SET PROPERTIES ('change_tracking' = 'true');
+
+-- 2. 创建 Table Stream
+CREATE TABLE STREAM orders_stream ON TABLE orders 
+WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD', 'SHOW_INITIAL_ROWS' = 'FALSE');
+
+-- 3. 创建目标表（与源表结构兼容）
+CREATE TABLE orders_sync (order_id INT, status STRING, amount DOUBLE);
+
+-- 4. 预览 Stream 数据（不移动 offset）
+SELECT *, __commit_version, __commit_timestamp FROM orders_stream;
+
+-- 5. 消费 Stream 数据（移动 offset）
+MERGE INTO orders_sync t 
+USING (SELECT * FROM orders_stream WHERE __change_type != 'UPDATE_BEFORE') s 
+ON t.order_id = s.order_id 
+WHEN MATCHED AND s.__change_type IN ('INSERT', 'UPDATE_AFTER') THEN UPDATE SET t.status = s.status, t.amount = s.amount 
+WHEN MATCHED AND s.__change_type = 'DELETE' THEN DELETE 
+WHEN NOT MATCHED AND s.__change_type = 'INSERT' THEN INSERT (order_id, status, amount) VALUES (s.order_id, s.status, s.amount);
+
+-- 6. 验证消费完成
+SELECT COUNT(*) FROM orders_stream;
+```
+
+### 示例 2：用户行为审计（保留全部插入历史）
+```sql
+-- 1. 开启源表变更跟踪
+ALTER TABLE user_actions SET PROPERTIES ('change_tracking' = 'true');
+
+-- 2. 创建 Table Stream（APPEND_ONLY 模式）
+CREATE TABLE STREAM user_actions_audit_stream ON TABLE user_actions 
+WITH PROPERTIES ('TABLE_STREAM_MODE' = 'APPEND_ONLY', 'SHOW_INITIAL_ROWS' = 'TRUE');
+
+-- 3. 预览 Stream 数据
+SELECT *, __commit_version, __commit_timestamp FROM user_actions_audit_stream;
+
+-- 4. 消费 Stream 数据（INSERT INTO 移动 offset）
+INSERT INTO user_actions_audit 
+SELECT *, __commit_version AS audit_version, __commit_timestamp AS audit_time 
+FROM user_actions_audit_stream;
+```
+
+## 故障排除
+
+Stream 不捕获变更：
+原因：源表未开启 change_tracking
+解决方案：执行 `ALTER TABLE <table> SET PROPERTIES ('change_tracking' = 'true')`，确认 DML 在 Stream 创建后执行
+
+无法区分变更类型：
+原因：未在 MERGE/INSERT 中过滤 `__change_type`，导致 `UPDATE_BEFORE` 旧值也被写入目标表
+解决方案：MERGE 时过滤 `__change_type IN ('UPDATE_AFTER', 'DELETE')`，忽略 `UPDATE_BEFORE` 记录
+
+消费后 offset 未移动：
+原因：仅使用 SELECT 查询，未执行 DML
+解决方案：必须通过 INSERT INTO / MERGE INTO / UPDATE 等 DML 操作消费数据
+
+重复消费导致目标表数据重复：
+原因：使用 INSERT INTO 而非 MERGE，或消费逻辑非幂等
+解决方案：改用 MERGE 语句；记录最后消费的 `__commit_version` 和 `__commit_timestamp` 用于断点恢复
+
+COMMENT 语法错误：
+原因：使用了 `COMMENT = '...'`（带等号）而非 `COMMENT '...'`
+解决方案：正确语法为 `COMMENT '注释内容'`，不带等号

package/bin/skills/clickzetta-vcluster-manager/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: clickzetta-vcluster-manager
+description: |
+  管理 ClickZetta Lakehouse 计算集群（VCluster）的完整生命周期。
+  覆盖创建（通用型/分析型/同步型）、启动/停止、规格调整、弹性扩缩容、
+  缓存配置（PRELOAD_TABLES）、查看集群状态等操作。
+  当用户说"创建集群"、"计算集群"、"VCluster"、"启动集群"、"停止集群"、
+  "调整集群规格"、"集群扩容"、"集群缩容"、"自动停止"、"自动启动"、
+  "预加载缓存"、"PRELOAD"、"集群类型"、"GP集群"、"AP集群"、"分析型集群"、
+  "通用型集群"、"同步型集群"时触发。
+  Keywords: VCluster, compute cluster, create, suspend, resume, resize, auto-scale
+---
+
+# ClickZetta 计算集群管理
+
+阅读 [references/vcluster-ddl.md](references/vcluster-ddl.md) 了解完整语法。
+
+## 集群类型选择
+
+| 类型 | 关键字 | 适用场景 | 扩缩容方式 |
+|---|---|---|---|
+| 通用型（GP） | `GENERAL` | 离线 ETL、数据摄取、综合场景 | 纵向（规格大小） |
+| 分析型（AP） | `ANALYTICS` | 高并发在线查询、BI 报表、Ad-Hoc | 横向（副本数） |
+| 同步型 | `INTEGRATION` | 数据集成同步任务 | 纵向（规格大小） |
+
+**规格单位**：CRU（Compute Resource Unit）
+- 通用型/同步型：1-256 CRU，步长 1（同步型额外支持 0.25、0.5）
+- 分析型：1-256 CRU，须为 2 的 n 次幂（1、2、4、8、16...）
+
+---
+
+## 创建集群
+
+```sql
+-- 通用型：离线 ETL，8 CRU，作业完成后 60 秒自动停止
+CREATE VCLUSTER IF NOT EXISTS etl_vc
+  VCLUSTER_TYPE = GENERAL
+  VCLUSTER_SIZE = 8
+  AUTO_SUSPEND_IN_SECOND = 60
+  AUTO_RESUME = TRUE
+  COMMENT '离线ETL专用集群';
+
+-- 通用型：弹性规格（1-16 CRU）
+CREATE VCLUSTER IF NOT EXISTS etl_elastic_vc
+  VCLUSTER_TYPE = GENERAL
+  MIN_VCLUSTER_SIZE = 1
+  MAX_VCLUSTER_SIZE = 16
+  AUTO_SUSPEND_IN_SECOND = 300;
+
+-- 分析型：BI 报表，4 CRU，1-10 副本，最大 80 并发
+CREATE VCLUSTER IF NOT EXISTS bi_vc
+  VCLUSTER_TYPE = ANALYTICS
+  VCLUSTER_SIZE = 4
+  MIN_REPLICAS = 1
+  MAX_REPLICAS = 10
+  MAX_CONCURRENCY = 8
+  AUTO_SUSPEND_IN_SECOND = 1800
+  AUTO_RESUME = TRUE
+  COMMENT 'BI报表在线查询集群';
+
+-- 同步型：数据集成任务
+CREATE VCLUSTER IF NOT EXISTS sync_vc
+  VCLUSTER_TYPE = INTEGRATION
+  VCLUSTER_SIZE = 1
+  AUTO_RESUME = TRUE;
+```
+
+---
+
+## 启动 / 停止
+
+```sql
+-- 启动集群
+ALTER VCLUSTER IF EXISTS etl_vc RESUME;
+
+-- 正常停止（等待当前作业完成）
+ALTER VCLUSTER IF EXISTS etl_vc SUSPEND;
+
+-- 强制停止（立即中断所有作业）
+ALTER VCLUSTER IF EXISTS etl_vc SUSPEND FORCE;
+
+-- 取消集群中所有作业
+ALTER VCLUSTER IF EXISTS etl_vc CANCEL ALL JOBS;
+```
+
+---
+
+## 修改集群属性
+
+```sql
+-- 调整规格
+ALTER VCLUSTER IF EXISTS etl_vc SET VCLUSTER_SIZE = 16;
+
+-- 修改自动停止时间
+ALTER VCLUSTER IF EXISTS etl_vc SET AUTO_SUSPEND_IN_SECOND = 300;
+
+-- 分析型：调整副本数和并发
+ALTER VCLUSTER IF EXISTS bi_vc SET
+  MIN_REPLICAS = 2
+  MAX_REPLICAS = 5
+  MAX_CONCURRENCY = 16;
+
+-- 修改注释
+ALTER VCLUSTER IF EXISTS etl_vc SET COMMENT '新注释';
+```
+
+---
+
+## 缓存配置（仅分析型）
+
+阅读 [references/vc-cache.md](references/vc-cache.md) 了解缓存详情。
+
+```sql
+-- 设置预加载表（覆盖写，需带上所有已有表）
+ALTER VCLUSTER bi_vc SET PRELOAD_TABLES = "public.orders,public.customers";
+
+-- 查看当前集群缓存状态
+SHOW PRELOAD CACHED STATUS;
+
+-- 查看指定集群缓存状态
+SHOW VCLUSTER bi_vc PRELOAD CACHED STATUS;
+```
+
+---
+
+## 查看集群信息
+
+```sql
+-- 列出所有集群
+SHOW VCLUSTERS;
+
+-- 按类型过滤
+SHOW VCLUSTERS WHERE vcluster_type = 'ANALYTICS';
+SHOW VCLUSTERS WHERE state = 'SUSPENDED';
+
+-- 按名称模糊匹配
+SHOW VCLUSTERS LIKE 'etl%';
+
+-- 查看集群详情
+DESC VCLUSTER etl_vc;
+DESC VCLUSTER EXTENDED bi_vc;
+```
+
+---
+
+## 删除集群
+
+```sql
+-- 等待当前作业完成后删除
+DROP VCLUSTER IF EXISTS etl_vc;
+
+-- 立即强制删除（中断正在运行的作业）
+DROP VCLUSTER IF EXISTS etl_vc FORCE;
+```
+
+---
+
+## 切换当前会话集群
+
+```sql
+USE VCLUSTER bi_vc;
+```
+
+---
+
+## 典型场景
+
+### 场景 1：离线 ETL 集群
+
+```sql
+CREATE VCLUSTER IF NOT EXISTS etl_daily
+  VCLUSTER_TYPE = GENERAL
+  VCLUSTER_SIZE = 8
+  AUTO_SUSPEND_IN_SECOND = 60
+  AUTO_RESUME = TRUE
+  COMMENT '每日ETL作业，完成后1分钟自动停止';
+```
+
+### 场景 2：在线 BI 报表集群（高并发）
+
+```sql
+CREATE VCLUSTER IF NOT EXISTS bi_online
+  VCLUSTER_TYPE = ANALYTICS
+  VCLUSTER_SIZE = 4
+  MIN_REPLICAS = 1
+  MAX_REPLICAS = 10
+  MAX_CONCURRENCY = 8
+  AUTO_SUSPEND_IN_SECOND = 1800
+  AUTO_RESUME = TRUE
+  COMMENT 'BI在线查询，最大支持80并发';
+```
+
+### 场景 3：数据集成同步集群
+
+```sql
+CREATE VCLUSTER IF NOT EXISTS cdc_sync
+  VCLUSTER_TYPE = INTEGRATION
+  VCLUSTER_SIZE = 0.5
+  AUTO_RESUME = TRUE
+  COMMENT '轻量CDC同步任务';
+```
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 分析型集群规格报错 | 规格须为 2 的 n 次幂 | 使用 1、2、4、8、16、32... |
+| PRELOAD_TABLES 不生效 | 仅 AP 型集群支持 | 确认集群类型为 ANALYTICS |
+| 添加预加载表后原有表消失 | PRELOAD_TABLES 是覆盖写 | 设置时带上所有已有表 |
+| 集群停止后缓存丢失 | 本地缓存随集群停止释放 | 重启后自动重新加载 PRELOAD 表 |

package/bin/skills/clickzetta-vcluster-manager/references/vc-cache.md

@@ -0,0 +1,54 @@
+# 计算集群缓存参考
+
+> 来源：https://www.yunqi.tech/documents/vc_cache
+
+## 缓存类型
+
+Lakehouse 提供三种缓存：
+1. **查询结果缓存（ResultCache）** - 服务层，工作空间内共享
+2. **元数据缓存（MetadataCache）** - 服务层，工作空间内共享
+3. **计算集群本地缓存（Local Disk Cache）** - 保存在集群本地节点，仅使用指定集群时可用
+
+## 主动缓存（PRELOAD_TABLES）
+
+仅适用于**分析型（AP）**集群。集群每次启动时自动加载预缓存表的最新数据/分区。
+
+```sql
+-- 设置预加载表（覆盖写，需带上所有已有表）
+ALTER VCLUSTER default SET PRELOAD_TABLES = "schema1.table1,schema2.table2";
+
+-- 添加新表时，必须包含原有表，否则会覆盖
+ALTER VCLUSTER default SET PRELOAD_TABLES = "schema1.table1,schema2.table2,schema3.table3";
+
+-- 支持通配符
+ALTER VCLUSTER bi_vc SET PRELOAD_TABLES = "sales.*,public.dim_date";
+```
+
+⚠️ 注意：执行缓存命令后，只有新写入的数据才会被缓存。
+
+## 被动缓存
+
+首次查询时自动缓存读取的文件，后续相同查询直接命中缓存。支持 GP 型和 AP 型集群。
+
+## 查看缓存状态
+
+```sql
+-- 显示当前集群的预加载表/分区状态
+SHOW PRELOAD CACHED STATUS;
+
+-- 显示指定集群的预加载状态
+SHOW VCLUSTER <vc_name> PRELOAD CACHED STATUS;
+
+-- 按表名过滤
+SHOW VCLUSTER <vc_name> PRELOAD CACHED STATUS WHERE table LIKE '%table_name%';
+
+-- 显示预加载缓存汇总信息
+SHOW EXTENDED PRELOAD CACHED STATUS;
+```
+
+## 注意事项
+
+- 集群停止时，本地缓存自动释放
+- AP 型集群重启时只缓存最新写入的数据或分区
+- `SHOW PRELOAD` 状态更新可能有约 10 分钟延迟，但缓存实际已生效
+- PRELOAD_TABLES 是覆盖写，添加新表时需带上所有已有表

package/bin/skills/clickzetta-vcluster-manager/references/vcluster-ddl.md

@@ -0,0 +1,150 @@
+# CREATE / ALTER / DROP VCLUSTER 参考
+
+> 来源：https://www.yunqi.tech/documents/create_cluster 和 alter-vcluster 和 drop-vcluster
+
+---
+
+## 集群类型选择
+
+| 类型 | 关键字 | 适用场景 | 扩缩容方式 |
+|---|---|---|---|
+| 通用型（GP） | `GENERAL` | 离线 ETL、数据摄取、综合场景 | 纵向（规格大小） |
+| 分析型（AP） | `ANALYTICS` | 高并发在线查询、BI 报表、Ad-Hoc | 横向（副本数） |
+| 同步型 | `INTEGRATION` | 数据集成同步任务 | 纵向（规格大小） |
+
+**规格单位**：CRU（Compute Resource Unit）
+- 通用型/同步型：1-256 CRU，步长 1（同步型额外支持 0.25、0.5）
+- 分析型：1-256 CRU，须为 2 的 n 次幂（1、2、4、8、16...）
+
+---
+
+## CREATE VCLUSTER
+
+```sql
+CREATE VCLUSTER [IF NOT EXISTS] <name>
+  VCLUSTER_TYPE = GENERAL | ANALYTICS | INTEGRATION
+  VCLUSTER_SIZE = num                    -- 固定规格
+  -- 或弹性规格（通用型/同步型）
+  MIN_VCLUSTER_SIZE = num
+  MAX_VCLUSTER_SIZE = num
+  AUTO_SUSPEND_IN_SECOND = num           -- 空闲自动停止秒数，-1 表示不停止，默认 600
+  AUTO_RESUME = TRUE | FALSE             -- 是否自动启动，默认 TRUE
+  QUERY_RUNTIME_LIMIT_IN_SECOND = num    -- 单作业最大执行时长（秒），默认 86400
+  [COMMENT '']
+```
+
+### 分析型专有参数
+
+```sql
+  MIN_REPLICAS = num          -- 最小实例数（1-10），默认 1
+  MAX_REPLICAS = num          -- 最大实例数（1-10），默认 1
+  MAX_CONCURRENCY = num       -- 每实例最大并发数（1-32），默认 8
+  PRELOAD_TABLES = "schema.table1,schema.table2"  -- 预加载缓存表
+```
+
+### 示例
+
+```sql
+-- 通用型：离线 ETL，8 CRU，作业完成后 60 秒自动停止
+CREATE VCLUSTER IF NOT EXISTS etl_vc
+  VCLUSTER_TYPE = GENERAL
+  VCLUSTER_SIZE = 8
+  AUTO_SUSPEND_IN_SECOND = 60
+  AUTO_RESUME = TRUE
+  COMMENT '离线ETL专用集群';
+
+-- 通用型：弹性规格（1-16 CRU）
+CREATE VCLUSTER IF NOT EXISTS etl_elastic_vc
+  VCLUSTER_TYPE = GENERAL
+  MIN_VCLUSTER_SIZE = 1
+  MAX_VCLUSTER_SIZE = 16
+  AUTO_SUSPEND_IN_SECOND = 300;
+
+-- 分析型：BI 报表，4 CRU，1-10 副本，最大 80 并发
+CREATE VCLUSTER IF NOT EXISTS bi_vc
+  VCLUSTER_TYPE = ANALYTICS
+  VCLUSTER_SIZE = 4
+  MIN_REPLICAS = 1
+  MAX_REPLICAS = 10
+  MAX_CONCURRENCY = 8
+  AUTO_SUSPEND_IN_SECOND = 1800
+  AUTO_RESUME = TRUE
+  COMMENT 'BI报表在线查询集群';
+
+-- 同步型：数据集成任务
+CREATE VCLUSTER IF NOT EXISTS sync_vc
+  VCLUSTER_TYPE = INTEGRATION
+  VCLUSTER_SIZE = 1
+  AUTO_RESUME = TRUE;
+```
+
+---
+
+## ALTER VCLUSTER
+
+```sql
+-- 启动集群
+ALTER VCLUSTER [IF EXISTS] <name> RESUME;
+
+-- 停止集群
+ALTER VCLUSTER [IF EXISTS] <name> SUSPEND [FORCE];
+
+-- 取消集群中所有作业
+ALTER VCLUSTER [IF EXISTS] <name> CANCEL ALL JOBS;
+
+-- 修改属性
+ALTER VCLUSTER [IF EXISTS] <name> SET
+  VCLUSTER_SIZE = num
+  AUTO_SUSPEND_IN_SECOND = num
+  AUTO_RESUME = TRUE | FALSE
+  MAX_CONCURRENCY = num          -- 仅分析型
+  MIN_REPLICAS = num             -- 仅分析型
+  MAX_REPLICAS = num             -- 仅分析型
+  PRELOAD_TABLES = "schema.table";
+
+-- 修改注释
+ALTER VCLUSTER [IF EXISTS] <name> SET COMMENT '新注释';
+```
+
+---
+
+## DROP VCLUSTER
+
+```sql
+-- 等待当前作业完成后删除
+DROP VCLUSTER [IF EXISTS] <name>;
+
+-- 立即强制删除（中断正在运行的作业）
+DROP VCLUSTER [IF EXISTS] <name> FORCE;
+```
+
+---
+
+## DESC / SHOW VCLUSTER
+
+```sql
+-- 查看集群基本信息
+DESC VCLUSTER <name>;
+
+-- 查看扩展信息
+DESC VCLUSTER EXTENDED <name>;
+
+-- 列出所有集群
+SHOW VCLUSTERS;
+
+-- 按类型过滤
+SHOW VCLUSTERS WHERE vcluster_type = 'GENERAL';
+SHOW VCLUSTERS WHERE state = 'SUSPENDED';
+SHOW VCLUSTERS WHERE vcluster_type = 'ANALYTICS';
+
+-- 按名称模糊匹配
+SHOW VCLUSTERS LIKE 'etl%';
+```
+
+---
+
+## USE VCLUSTER（切换当前会话集群）
+
+```sql
+USE VCLUSTER <name>;
+```