@clickzetta/cz-cli-linux-x64 0.3.0 → 0.3.1

package/bin/skills/clickzetta-dba-guide/SKILL.md

@@ -0,0 +1,540 @@
+---
+name: clickzetta-dba-guide
+description: |
+  ClickZetta Lakehouse DBA 日常运维操作手册。集中覆盖 DBA 最常用的 8 类操作：
+  用户与权限管理、计算集群运维、作业监控与诊断、数据恢复与保护、
+  存储优化与维护、网络策略与安全、Schema 与对象管理、成本与资源分析。
+  每个操作提供可直接执行的 SQL，并标注 ClickZetta 特有限制。
+  当用户说"创建用户"、"授权"、"撤销权限"、"启停集群"、"调整集群规格"、
+  "取消作业"、"慢查询"、"恢复误删表"、"UNDROP"、"RESTORE"、
+  "小文件合并"、"OPTIMIZE"、"ANALYZE TABLE"、"网络策略"、"IP 白名单"、
+  "动态脱敏"、"成本分析"、"存储用量"、"DBA 操作"时触发。
+  Keywords: DBA, operations, monitoring, troubleshooting, cluster management, cost
+---
+
+# ClickZetta Lakehouse DBA 运维手册
+
+---
+
+## 模块 1：用户与权限管理
+
+### 用户管理
+
+```sql
+-- 创建用户（设置默认集群和 Schema）
+CREATE USER alice DEFAULT_VCLUSTER default_ap DEFAULT_SCHEMA my_schema;
+
+-- 修改用户默认集群
+ALTER USER alice SET DEFAULT_VCLUSTER = analytics_cluster;
+
+-- 删除用户（从当前工作空间移除）
+DROP USER alice;
+
+-- 查看所有用户
+SHOW USERS;
+```
+
+### 角色管理
+
+```sql
+-- 创建自定义角色（仅工作空间级，仅 SQL）
+CREATE ROLE data_engineer;
+
+-- 将角色授予用户
+GRANT ROLE data_engineer TO USER alice;
+
+-- 撤销角色
+REVOKE ROLE data_engineer FROM USER alice;
+
+-- 查看所有角色
+SHOW ROLES;
+
+-- 查看用户权限
+SHOW GRANTS TO USER alice;
+SHOW GRANTS TO ROLE data_engineer;
+```
+
+### 权限授予
+
+```sql
+-- 授予 Schema 下所有表的读权限
+GRANT SELECT ON ALL TABLES IN SCHEMA my_schema TO ROLE data_engineer;
+
+-- 授予单张表的读写权限
+GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE my_schema.orders TO USER alice;
+
+-- 授予创建表的权限
+GRANT CREATE TABLE ON SCHEMA my_schema TO ROLE data_engineer;
+
+-- 授予使用集群的权限
+GRANT USE ON VCLUSTER default_ap TO ROLE data_engineer;
+
+-- 授予 information_schema 查询权限
+GRANT ALL ON ALL VIEWS IN SCHEMA information_schema TO ROLE data_engineer;
+
+-- 批量授权（Schema 级别）
+GRANT SELECT ON ALL TABLES IN SCHEMA ods TO ROLE analyst;
+GRANT SELECT ON ALL TABLES IN SCHEMA dwd TO ROLE analyst;
+GRANT SELECT ON ALL TABLES IN SCHEMA dws TO ROLE analyst;
+```
+
+### 权限撤销
+
+```sql
+-- 撤销表权限
+REVOKE SELECT ON TABLE my_schema.orders FROM USER alice;
+
+-- 撤销 Schema 创建权限
+REVOKE CREATE TABLE ON SCHEMA my_schema FROM ROLE data_engineer;
+```
+
+### 动态脱敏（列级安全，邀测功能）
+
+```sql
+-- 创建脱敏函数（基于角色）
+CREATE FUNCTION my_schema.phone_masking(phone STRING)
+RETURNS STRING
+AS CASE
+  WHEN ARRAY_CONTAINS(current_roles(), 'data_admin') THEN phone
+  ELSE CONCAT(SUBSTR(phone, 1, 3), '****', SUBSTR(phone, 8, 4))
+END;
+
+-- 绑定脱敏策略到列
+ALTER TABLE my_schema.users
+CHANGE COLUMN phone SET MASK my_schema.phone_masking;
+
+-- 解除脱敏
+ALTER TABLE my_schema.users
+CHANGE COLUMN phone UNSET MASK;
+```
+
+**ClickZetta 特有限制：**
+- 无超级用户，所有操作必须明确授权
+- `instance_admin` 不能直接操作工作空间数据
+- 自定义角色仅工作空间级，不支持实例级自定义角色
+
+---
+
+## 模块 2：计算集群运维
+
+### 启停与状态
+
+```sql
+-- 启动集群
+ALTER VCLUSTER my_cluster RESUME;
+ALTER VCLUSTER IF EXISTS my_cluster RESUME;
+
+-- 停止集群
+ALTER VCLUSTER my_cluster SUSPEND;
+ALTER VCLUSTER my_cluster SUSPEND FORCE;  -- 强制停止（中断运行中的作业）
+
+-- 取消集群所有作业
+ALTER VCLUSTER my_cluster CANCEL ALL JOBS;
+
+-- 查看集群状态
+SHOW VCLUSTERS;
+SHOW VCLUSTERS WHERE state = 'RUNNING';
+SHOW VCLUSTERS WHERE state = 'SUSPENDED';
+DESC VCLUSTER my_cluster;
+DESC VCLUSTER EXTENDED my_cluster;
+
+-- 切换当前会话使用的集群
+USE VCLUSTER my_cluster;
+```
+
+### 调整规格
+
+```sql
+-- 通用型（GP）：固定规格
+ALTER VCLUSTER my_gp SET VCLUSTER_SIZE = 8;
+
+-- 通用型（GP）：弹性规格
+ALTER VCLUSTER my_gp SET MIN_VCLUSTER_SIZE = 2 MAX_VCLUSTER_SIZE = 16;
+
+-- 分析型（AP）：调整副本数
+ALTER VCLUSTER my_ap SET MIN_REPLICAS = 1 MAX_REPLICAS = 4;
+
+-- 分析型（AP）：调整最大并发
+ALTER VCLUSTER my_ap SET MAX_CONCURRENCY = 16;
+
+-- 设置查询超时（秒，-1 表示无限制）
+ALTER VCLUSTER my_cluster SET QUERY_RUNTIME_LIMIT_IN_SECOND = 3600;
+```
+
+### 自动停止与启动
+
+```sql
+-- 设置 60 秒无作业自动停止，有作业自动启动
+ALTER VCLUSTER my_cluster SET
+  AUTO_SUSPEND_IN_SECOND = 60
+  AUTO_RESUME = TRUE;
+
+-- 关闭自动停止
+ALTER VCLUSTER my_cluster SET AUTO_SUSPEND_IN_SECOND = -1;
+```
+
+### AP 集群预加载缓存
+
+```sql
+-- 设置预加载表（集群启动时自动缓存最新数据）
+ALTER VCLUSTER my_ap SET PRELOAD_TABLES = "sales.orders,sales.products";
+
+-- 查看缓存状态
+SHOW PRELOAD CACHED STATUS;
+SHOW EXTENDED PRELOAD CACHED STATUS;
+```
+
+**ClickZetta 特有限制：**
+- OPTIMIZE（小文件合并）仅 GP 集群支持，AP 集群不生效
+- 分析型集群规格步长为 2^n（1/2/4/8/16...），通用型步长为 1
+
+---
+
+## 模块 3：作业监控与诊断
+
+### 实时作业查看
+
+```sql
+-- 查看最近作业（最多 7 天，10000 条）
+SHOW JOBS LIMIT 20;
+SHOW JOBS IN VCLUSTER default_ap LIMIT 20;
+
+-- 取消指定作业
+CANCEL JOB '2026050118342658136171272';
+
+-- 查看执行计划
+EXPLAIN SELECT * FROM orders WHERE order_date = '2024-01-01';
+EXPLAIN EXTENDED SELECT * FROM orders WHERE order_date = '2024-01-01';
+```
+
+### 历史作业分析（information_schema）
+
+```sql
+-- 慢查询 TOP 20（最近 7 天）
+SELECT job_id, job_creator, execution_time, input_bytes, job_text
+FROM information_schema.job_history
+WHERE pt_date >= CAST(CURRENT_DATE - INTERVAL 7 DAY AS DATE)
+  AND status = 'SUCCEED'
+ORDER BY execution_time DESC
+LIMIT 20;
+
+-- 失败作业（最近 24 小时）
+SELECT job_id, job_creator, error_message, start_time, job_text
+FROM information_schema.job_history
+WHERE pt_date >= CAST(CURRENT_DATE - INTERVAL 1 DAY AS DATE)
+  AND status = 'FAILED'
+ORDER BY start_time DESC;
+
+-- 按用户统计 CRU 消耗（最近 30 天）
+SELECT job_creator,
+       COUNT(*) AS job_count,
+       ROUND(SUM(cru), 2) AS total_cru,
+       ROUND(AVG(execution_time), 1) AS avg_exec_sec
+FROM information_schema.job_history
+WHERE pt_date >= CAST(CURRENT_DATE - INTERVAL 30 DAY AS DATE)
+  AND status = 'SUCCEED'
+GROUP BY job_creator
+ORDER BY total_cru DESC;
+
+-- 按集群统计作业分布
+SELECT virtual_cluster,
+       COUNT(*) AS job_count,
+       ROUND(SUM(cru), 2) AS total_cru
+FROM information_schema.job_history
+WHERE pt_date >= CAST(CURRENT_DATE - INTERVAL 7 DAY AS DATE)
+GROUP BY virtual_cluster
+ORDER BY total_cru DESC;
+```
+
+---
+
+## 模块 4：数据恢复与保护
+
+### 恢复误删对象
+
+```sql
+-- 查看已删除的表（delete_time 不为 NULL）
+SHOW TABLES HISTORY IN my_schema;
+SHOW TABLES HISTORY LIKE '%orders%';
+
+-- 恢复误删的表/动态表/物化视图
+UNDROP TABLE my_schema.orders;
+UNDROP TABLE my_schema.my_dynamic_table;
+UNDROP TABLE my_schema.my_mv;
+-- ⚠️ 恢复外部函数用 UNDROP FUNCTION，不是 UNDROP EXTERNAL FUNCTION
+UNDROP FUNCTION my_schema.my_ext_function;
+```
+
+### 回滚到历史版本
+
+```sql
+-- 查看表的版本历史
+DESC HISTORY my_schema.orders;
+-- 返回：version, time, total_rows, total_bytes, user, operation, job_id
+
+-- 恢复到指定时间点（覆盖当前数据）
+-- ⚠️ 时间戳必须用 CAST() 或完整毫秒格式，不能用简单字符串
+-- ❌ 错误：RESTORE TABLE t TO TIMESTAMP AS OF '2024-01-15';
+-- ✅ 正确写法：
+RESTORE TABLE my_schema.orders TO TIMESTAMP AS OF CAST('2024-01-15 10:00:00' AS TIMESTAMP);
+RESTORE TABLE my_schema.orders TO TIMESTAMP AS OF CURRENT_TIMESTAMP() - INTERVAL '2' HOURS;
+-- 也支持完整毫秒时间戳字符串（从 DESC HISTORY 复制）：
+RESTORE TABLE my_schema.orders TO TIMESTAMP AS OF '2024-01-15 10:00:00.123';
+
+-- 查询历史数据（不覆盖，仅查看）
+SELECT * FROM my_schema.orders TIMESTAMP AS OF CAST('2024-01-15 10:00:00' AS TIMESTAMP);
+```
+
+### 设置数据保留周期
+
+```sql
+-- 设置 Time Travel 保留 30 天（范围 0-90）
+ALTER TABLE my_schema.orders SET PROPERTIES ('data_retention_days' = '30');
+
+-- 查看当前设置
+SHOW CREATE TABLE my_schema.orders;
+```
+
+**ClickZetta 特有限制：**
+- `RESTORE TABLE` 目标时间点不能早于表创建时间
+- `UNDROP` 需在 `data_retention_days` 保留期内（默认 1 天）
+- 物化视图支持 UNDROP，但不支持 RESTORE
+
+---
+
+## 模块 5：存储优化与维护
+
+### 小文件合并
+
+```sql
+-- 手动触发小文件合并（异步，仅 GP 集群）
+OPTIMIZE my_schema.orders;
+
+-- 同步执行（等待完成）
+OPTIMIZE my_schema.orders OPTIONS('cz.sql.optimize.table.async' = 'false');
+
+-- 只优化特定分区
+OPTIMIZE my_schema.orders WHERE dt = '2024-01-01';
+OPTIMIZE my_schema.orders WHERE dt = '2024-01-01' AND region = 'cn';
+
+-- DML 写入时自动触发合并（GP 集群）
+SET cz.sql.compaction.after.commit = true;
+INSERT INTO my_schema.orders SELECT * FROM staging;
+```
+
+### 统计信息收集
+
+```sql
+-- 收集表统计信息（优化查询计划）
+ANALYZE TABLE my_schema.orders COMPUTE STATISTICS;
+
+-- 仅收集大小，不扫描数据（快速）
+ANALYZE TABLE my_schema.orders COMPUTE STATISTICS NOSCAN;
+
+-- 收集指定列的统计信息
+ANALYZE TABLE my_schema.orders COMPUTE STATISTICS FOR COLUMNS order_date, customer_id;
+
+-- 收集 Schema 下所有表
+ANALYZE TABLES IN my_schema COMPUTE STATISTICS;
+```
+
+### 清空数据
+
+```sql
+-- 清空整张表（保留表结构）
+TRUNCATE TABLE my_schema.staging;
+
+-- 清空指定分区
+TRUNCATE TABLE my_schema.orders WHERE dt = '2024-01-01';
+```
+
+### 查看存储用量
+
+```sql
+-- 当前 Schema 下大表排行
+SELECT table_schema, table_name,
+       ROUND(bytes / 1024.0 / 1024 / 1024, 2) AS size_gb,
+       row_count
+FROM information_schema.tables
+WHERE table_type = 'MANAGED_TABLE'
+ORDER BY bytes DESC
+LIMIT 20;
+
+-- Sort Key 推荐（系统自动分析）
+SELECT table_name, col, statement, ratio
+FROM information_schema.sortkey_candidates
+ORDER BY ratio DESC;
+```
+
+---
+
+## 模块 6：网络策略与安全
+
+### 网络策略管理
+
+```sql
+-- 创建网络策略（白名单）
+CREATE NETWORK POLICY office_policy
+  ALLOWED_IP_LIST = ('10.0.0.0/8', '192.168.1.0/24')
+  COMMENT '办公网络白名单';
+
+-- 创建网络策略（白名单 + 黑名单）
+CREATE NETWORK POLICY strict_policy
+  ALLOWED_IP_LIST = ('10.0.0.0/8')
+  BLOCKED_IP_LIST = ('10.0.1.100')
+  COMMENT '严格访问控制';
+
+-- 修改网络策略（覆盖式，必须包含所有 IP）
+ALTER NETWORK POLICY office_policy
+  ALLOWED_IP_LIST = ('10.0.0.0/8', '172.16.0.0/12')
+  BLOCKED_IP_LIST = ('10.0.1.100');
+
+-- 停用/启用策略
+ALTER NETWORK POLICY office_policy INACTIVATE;
+ALTER NETWORK POLICY office_policy ACTIVATE;
+
+-- 删除策略
+DROP NETWORK POLICY IF EXISTS office_policy;
+
+-- 查看所有策略（注意：单数 POLICY，无 S）
+SHOW NETWORK POLICY;
+
+-- 查看策略详情
+DESC NETWORK POLICY office_policy;
+```
+
+**关键规则（Deny 优先）：**
+- 无任何策略时：允许所有 IP
+- 有白名单策略时：不在白名单的 IP 被拒绝
+- 黑名单命中时：无论白名单如何，该 IP 被拒绝
+- MySQL 协议：只要有任何生效策略，所有 MySQL 流量均被拦截
+- 策略生效延迟：最多 5 分钟
+
+---
+
+## 模块 7：Schema 与对象管理
+
+### Schema 管理
+
+```sql
+-- 创建 Schema
+CREATE SCHEMA ods;
+CREATE SCHEMA IF NOT EXISTS dwd;
+
+-- 修改 Schema 注释
+ALTER SCHEMA ods SET COMMENT 'ODS 原始数据层';
+
+-- 重命名 Schema
+ALTER SCHEMA old_name RENAME TO new_name;
+
+-- 删除 Schema（级联删除所有对象）
+DROP SCHEMA IF EXISTS temp_schema CASCADE;
+
+-- 切换默认 Schema
+USE SCHEMA my_schema;
+```
+
+### 表管理
+
+```sql
+-- 修改表：加列
+ALTER TABLE my_schema.orders ADD COLUMN (discount DECIMAL(5,2) COMMENT '折扣率');
+
+-- 修改表：改列注释
+ALTER TABLE my_schema.orders CHANGE COLUMN order_id SET COMMENT '订单唯一标识';
+
+-- 修改表：设置生命周期
+ALTER TABLE my_schema.orders SET PROPERTIES ('data_lifecycle' = '90');
+
+-- 修改表：设置 Sort Key
+ALTER TABLE my_schema.orders SET PROPERTIES ('hint.sort.columns' = 'order_date');
+
+-- 重命名表
+ALTER TABLE my_schema.orders RENAME TO my_schema.orders_v2;
+
+-- 删除表（可 UNDROP 恢复）
+DROP TABLE IF EXISTS my_schema.temp_table;
+
+-- 删除动态表
+DROP DYNAMIC TABLE IF EXISTS my_schema.my_dt;
+
+-- 删除物化视图
+DROP MATERIALIZED VIEW IF EXISTS my_schema.my_mv;
+```
+
+### 批量对象查看
+
+```sql
+-- 统计各类型对象数量
+SELECT
+  CASE WHEN is_view THEN 'VIEW'
+       WHEN is_materialized_view THEN 'MV'
+       WHEN is_dynamic THEN 'DT'
+       WHEN is_external THEN 'EXTERNAL'
+       ELSE 'TABLE' END AS type,
+  COUNT(*) AS cnt
+FROM (SHOW TABLES IN my_schema)
+GROUP BY 1;
+
+-- 查找大于 30 天未更新的表（潜在废弃表）
+SELECT table_schema, table_name, last_modify_time,
+       ROUND(bytes / 1024.0 / 1024 / 1024, 2) AS size_gb
+FROM information_schema.tables
+WHERE table_type = 'MANAGED_TABLE'
+  AND last_modify_time < CURRENT_TIMESTAMP - INTERVAL 30 DAY
+ORDER BY bytes DESC;
+```
+
+---
+
+## 模块 8：成本与资源分析（需 INSTANCE ADMIN）
+
+```sql
+-- 本月各工作空间计算费用
+SELECT workspace_name, sku_name,
+       ROUND(SUM(measurements_consumption), 2) AS total_cru,
+       ROUND(SUM(amount), 2) AS total_yuan
+FROM SYS.information_schema.instance_usage
+WHERE measurement_start >= DATE_TRUNC('month', CURRENT_DATE)
+GROUP BY workspace_name, sku_name
+ORDER BY total_yuan DESC;
+
+-- 本月各工作空间存储费用
+SELECT workspace_name, sku_name,
+       ROUND(SUM(measurements_consumption), 4) AS consumption,
+       measurements_unit,
+       ROUND(SUM(amount), 4) AS total_yuan
+FROM SYS.information_schema.storage_metering
+WHERE measurement_start >= DATE_TRUNC('month', CURRENT_DATE)
+GROUP BY workspace_name, sku_name, measurements_unit
+ORDER BY workspace_name, total_yuan DESC;
+
+-- 跨空间存储用量排行
+SELECT workspace_name,
+       ROUND(workspace_storage / 1024.0 / 1024 / 1024, 2) AS storage_gb
+FROM SYS.information_schema.workspaces
+WHERE delete_time IS NULL
+ORDER BY workspace_storage DESC;
+
+-- 跨空间大表排行（大于 10GB）
+SELECT table_catalog, table_schema, table_name,
+       ROUND(bytes / 1024.0 / 1024 / 1024, 2) AS size_gb, row_count
+FROM SYS.information_schema.tables
+WHERE delete_time IS NULL AND bytes > 10 * 1024 * 1024 * 1024
+ORDER BY bytes DESC;
+```
+
+---
+
+## ClickZetta DBA 特有注意事项
+
+| 场景 | 注意事项 |
+|---|---|
+| 权限体系 | 无超级用户；`instance_admin` 不能直接操作工作空间数据 |
+| 自定义角色 | 仅工作空间级，不支持实例级；只能 SQL 创建，不支持 Web 端 |
+| OPTIMIZE | 仅 GP 集群支持；AP 集群不支持小文件合并 |
+| UNDROP | 需在 `data_retention_days` 保留期内（默认 1 天） |
+| RESTORE | 目标时间点不能早于表创建时间 |
+| 网络策略 | Deny 优先；MySQL 协议有任何策略即全部拦截；生效延迟最多 5 分钟 |
+| 动态脱敏 | 邀测功能，需联系技术支持开通 |
+| 集群规格 | AP 集群步长 2^n；GP 集群步长 1；同步型最小 0.25 CRU |