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

package/bin/skills/clickzetta-overview/references/object-model.md

@@ -0,0 +1,311 @@
+# ClickZetta Lakehouse 对象模型完整参考
+
+> 来源：官方产品文档 yunqi.tech
+> 参考：clickzetta-lakehouse-architecture.html
+
+---
+
+## ClickZetta 独特概念速查
+
+| 概念 | 独特之处 | 常见误区 |
+|---|---|---|
+| CRU | 跨云统一算力单位，旧规格 XS/S/M/L 已迁移为数字 1/2/4/8 | 不是 Snowflake Credit，不是 DBU |
+| VCluster 三类型 | GP/AP/Integration 各有适用场景，Dynamic Table 必须用 GP | AP 集群不支持小文件合并 |
+| Dynamic Table | CBO 自适应增量/全量，`OR REPLACE` 保留数据 | 最小 1 分钟，非秒级流式 |
+| Table Stream | 需先 `ALTER TABLE SET PROPERTIES ('change_tracking'='true')` | 实时写入数据需等 1 分钟才可读 |
+| Pipe | 每个 Pipe 对应独立 Volume，不可复用 | 不是 Snowflake Snowpipe，无自动触发 |
+| Synonym | 支持跨 Schema 别名，VOLUME/FUNCTION 类型需显式声明关键字 | 不是视图，不复制数据 |
+| 权限体系 | 无超级用户；实例角色与工作空间角色互不影响 | instance_admin 不能直接操作工作空间数据 |
+| Workspace | 连接时必须指定，≈ Snowflake Database | 不是 Databricks Workspace（那个是实例级） |
+| Schema TYPE | MANAGED（内部托管）/ EXTERNAL（外部数据湖） | EXTERNAL Schema 不支持 DML |
+
+---
+
+## 完整对象层级
+
+```
+账户 (Account)
+│  全局唯一 · SSO/MFA · 实名认证
+│
+└── 服务实例 (Instance)
+    │  资源隔离 · 多云多地域 · Instance Role
+    │
+    └── 工作空间 (Workspace)
+        │  业务隔离 · Workspace Role · VCluster 绑定 · 任务调度
+        │
+        ├── Schema（数据库/命名空间）
+        │   │  MANAGED / EXTERNAL 类型
+        │   │
+        │   ├── 内部表 (Managed Table)     — Iceberg · ACID · Time Travel · 索引
+        │   ├── 外部表 (External Table)    — Delta/Hudi/Kafka · 只读
+        │   ├── 视图 (View)               — 虚拟 · 无存储
+        │   ├── 动态表 (Dynamic Table)    — 声明式增量刷新
+        │   ├── 物化视图 (Materialized View) — 预计算 · 定时刷新
+        │   ├── Volume                    — User/Table/External(OSS/S3/COS)
+        │   ├── Table Stream              — CDC 变更捕获
+        │   ├── Pipe                      — Kafka/OSS 持续导入
+        │   ├── 函数 / External Function  — SQL UDF / Python / Java
+        │   ├── 索引                      — BloomFilter / Inverted / Vector(HNSW)
+        │   └── 同义词 (Synonym)          — 跨 Schema 别名
+        │
+        ├── Share                         — 跨账户零拷贝数据共享
+        ├── Connection                    — Storage(OSS/COS/S3) / API(云函数)
+        └── External Catalog              — Hive HMS / Iceberg REST / Databricks Unity
+```
+
+---
+
+## 工作空间（Workspace）详解
+
+### 核心定位
+
+Workspace 是 ClickZetta 中**业务隔离的最小单元**，也是连接时必须指定的对象。
+
+- 等同于 Snowflake 的 **Database**，或 Databricks 的 **Catalog**
+- 每个 Workspace 有独立的：用户角色、VCluster、任务调度、INFORMATION_SCHEMA
+- 连接参数中的 `workspace` 字段即指定此对象
+
+### 管理命令
+
+```sql
+-- 查看所有工作空间（需 instance_admin）
+SHOW WORKSPACES;
+
+-- 查看工作空间详情
+DESC WORKSPACE my_workspace;
+
+-- 修改注释
+ALTER WORKSPACE my_workspace SET COMMENT '生产环境';
+
+-- 查看属性
+SHOW PROPERTIES IN WORKSPACE my_workspace;
+```
+
+### DESC WORKSPACE 输出字段
+
+| 字段 | 说明 |
+|---|---|
+| name | 工作空间名称 |
+| creator | 创建者 |
+| created_time | 创建时间 |
+| last_modified_time | 最后修改时间 |
+| comment | 注释 |
+
+---
+
+## Schema 详解
+
+### 核心定位
+
+Schema 是 ClickZetta 中的**命名空间**，用于组织数据对象。
+
+- 等同于传统数据库的 **Database** 或 **Schema**（注意：不同系统叫法不同）
+- 是权限授予的边界（可对整个 Schema 授权）
+- 类型：`MANAGED`（平台托管存储）/ `EXTERNAL`（外部数据湖路径）
+
+### 管理命令
+
+```sql
+-- 创建 Schema
+CREATE SCHEMA my_schema;
+
+-- 创建外部 Schema（指向外部数据湖）
+CREATE EXTERNAL SCHEMA ext_schema LOCATION 'oss://bucket/path/';
+
+-- 切换默认 Schema
+USE SCHEMA my_schema;
+
+-- 查看所有 Schema
+SHOW SCHEMAS;
+
+-- 查看 Schema 详情
+DESC SCHEMA my_schema;
+
+-- 修改 Schema
+ALTER SCHEMA my_schema RENAME TO new_schema;
+ALTER SCHEMA my_schema SET COMMENT '数据仓库层';
+
+-- 删除 Schema（需先删除其中的对象）
+DROP SCHEMA my_schema;
+DROP SCHEMA IF EXISTS my_schema CASCADE;  -- 级联删除所有对象
+```
+
+---
+
+## VCluster（计算集群）详解
+
+### 三种类型对比
+
+| 属性 | 通用型 (GENERAL) | 分析型 (ANALYTICS) | 同步型 (INTEGRATION) |
+|---|---|---|---|
+| 适用场景 | ETL、批量导入、Ad-Hoc | 高并发 BI、在线查询 | 数据集成、CDC 同步 |
+| 弹性方式 | 纵向（规格扩缩） | 横向（副本数 1-10） | — |
+| 最小规格 | 1 CRU | 1 CRU | 0.25 CRU |
+| 最大规格 | 256 CRU | 256 CRU | 256 CRU |
+| 规格步长 | 1 CRU | 2^n CRU | 0.25 CRU |
+| 本地缓存 | 不支持 | 支持（PRELOAD） | 不支持 |
+| 小文件合并 | 支持（Dynamic Table 推荐） | 不支持 | — |
+
+### 任务类型与集群对应
+
+| 任务类型 | 推荐集群 |
+|---|---|
+| SQL ETL / 批量导入 | 通用型 |
+| Ad-Hoc 查询 / BI | 分析型 |
+| Dynamic Table（低频大量） | 通用型 |
+| Dynamic Table（高频小量） | 分析型 |
+| 离线同步 / 实时同步 / CDC | 同步型 |
+| Python / Shell / JDBC 任务 | 不使用 VCluster |
+
+### 管理命令
+
+```sql
+-- 创建通用型集群
+CREATE VCLUSTER my_gp TYPE GENERAL SIZE 4;
+
+-- 创建分析型集群（弹性 1-4 副本）
+CREATE VCLUSTER my_ap TYPE ANALYTICS SIZE 8 MIN_INSTANCE 1 MAX_INSTANCE 4;
+
+-- 启动 / 停止
+ALTER VCLUSTER my_gp RESUME;
+ALTER VCLUSTER my_gp SUSPEND;
+
+-- 查看所有集群
+SHOW VCLUSTERS;
+```
+
+---
+
+## 用户与权限体系
+
+### 用户层级
+
+```
+全局账号用户（Global User）
+│  在账户层面管理，user_name 全局唯一
+│
+└── 服务实例用户（Instance User）
+    │  全局用户自动同步，默认获得 instance_user 角色（无数据权限）
+    │
+    └── 工作空间用户（Workspace User）
+        通过 GRANT ROLE 授予工作空间角色后才能操作数据
+```
+
+### 用户类型
+
+| 类型 | 说明 |
+|---|---|
+| 普通用户 | 代表实际人员，可 Web 登录 |
+| 系统服务用户 | 平台内置，默认禁用（如 sysservice_auto_mv） |
+| 自定义服务用户 | 用于自动化程序，不可 Web 登录，可用 JDBC |
+
+### 预置角色
+
+| 角色 | 级别 | 权限范围 |
+|---|---|---|
+| instance_admin | 实例级 | 管理所有工作空间、用户、External Catalog |
+| instance_user | 实例级 | 默认角色，无数据权限 |
+| workspace_admin | 工作空间级 | 管理空间内所有对象和用户 |
+| workspace_dev | 工作空间级 | 读写权限 + 任务管理 |
+| workspace_analyst | 工作空间级 | 只读权限 |
+
+### 授权命令
+
+```sql
+-- 将角色授予用户
+GRANT ROLE workspace_dev TO USER alice;
+
+-- 授予表权限
+GRANT SELECT ON TABLE my_schema.my_table TO ROLE analyst_role;
+GRANT SELECT ON ALL TABLES IN SCHEMA my_schema TO ROLE analyst_role;
+
+-- 授予 information_schema 查询权限
+GRANT ALL ON ALL VIEWS IN SCHEMA information_schema TO ROLE analyst_role;
+
+-- 撤销权限
+REVOKE SELECT ON TABLE my_schema.my_table FROM ROLE analyst_role;
+
+-- 创建自定义角色（仅工作空间级，仅 SQL）
+CREATE ROLE my_custom_role;
+```
+
+---
+
+## 数据类型速查
+
+| 分类 | 类型 |
+|---|---|
+| 整数 | TINYINT / SMALLINT / INT / BIGINT |
+| 浮点 | FLOAT / DOUBLE / DECIMAL(p,s) |
+| 字符串 | CHAR(n) / VARCHAR(n) / STRING（最大 16MB） |
+| 时间 | DATE / TIMESTAMP（带时区 LTZ）/ TIMESTAMP_NTZ / INTERVAL |
+| 布尔 | BOOLEAN |
+| 复杂 | ARRAY\<T\> / MAP\<K,V\> / STRUCT\<field:type,...\> |
+| AI 专用 | VECTOR(FLOAT, n)（最大 65535 维）/ VECTOR(TINYINT, n) |
+| 特殊 | JSON / BINARY / BITMAP（Roaring Bitmap） |
+
+---
+
+## 平台架构层次
+
+```
+客户端层：Studio IDE · JDBC/ODBC · Python SDK · ZettaPark · BI 工具 · MCP Server
+    ↓
+计算层：VCluster（GENERAL / ANALYTICS / INTEGRATION）
+    ↓
+服务层：SQL 解析优化 · 向量化执行引擎 · Dynamic Table · AI Gateway · Result Cache
+    ↓
+存储层：内部表(Iceberg) · 外部表 · Volume · Time Travel · External Catalog · Share
+    ↓
+底层对象存储：阿里云 OSS · AWS S3 · 腾讯云 COS
+```
+
+**存算分离**：计算层和存储层独立扩展，VCluster 停止时不产生计算费用，存储按 GiB 计费。
+
+---
+
+## 数据对象横向对比
+
+### Dynamic Table vs Materialized View vs View
+
+| 维度 | 动态表 (Dynamic Table) | 物化视图 (Materialized View) | 视图 (View) |
+|---|---|---|---|
+| 数据存储 | 有（物化） | 有（物化） | 无（虚拟） |
+| 刷新方式 | 自动增量/全量（CBO 决策） | 手动或定时全量 | 每次查询实时执行 |
+| 最小刷新间隔 | 1 分钟 | 无限制（手动） | — |
+| Time Travel | 支持 | 不支持 | 不支持 |
+| UNDROP | 支持 | 不支持 | 不支持 |
+| CREATE OR REPLACE | 支持（保留数据和权限） | 支持 | 支持 |
+| 推荐集群 | GP（通用型） | GP 或 AP | — |
+| 适用场景 | 实时 ETL、多层级联 | BI 加速、固定聚合 | 简单逻辑封装 |
+
+### Table Stream 两种模式
+
+| 模式 | 捕获内容 | 典型用途 |
+|---|---|---|
+| STANDARD | INSERT + UPDATE_BEFORE + UPDATE_AFTER + DELETE | CDC UPSERT，MERGE INTO 消费 |
+| APPEND_ONLY | 仅 INSERT | 日志追加，简单 ETL |
+
+**STANDARD 模式的 delta 语义**：记录两个 offset 之间的净变化。若一行先 INSERT 后 DELETE，delta 中该行消失（不会出现 INSERT+DELETE 两条记录）。
+
+### Pipe 两种导入模式
+
+| 模式 | 触发方式 | 适用场景 | 云支持 |
+|---|---|---|---|
+| LIST_PURGE | 定期扫描 Volume 目录 | 通用，任何对象存储 | 全部 |
+| EVENT_NOTIFICATION | 云消息队列事件触发 | 低延迟，近实时 | 仅阿里云 OSS + AWS S3 |
+
+---
+
+## 地域与连接信息
+
+| 云服务商 | 地域 | 区域代码 | API Endpoint |
+|---|---|---|---|
+| 阿里云 | 华东2（上海） | cn-shanghai-alicloud | cn-shanghai-alicloud.api.clickzetta.com |
+| 腾讯云 | 华东（上海） | ap-shanghai-tencentcloud | ap-shanghai-tencentcloud.api.clickzetta.com |
+| 腾讯云 | 华北（北京） | ap-beijing-tencentcloud | ap-beijing-tencentcloud.api.clickzetta.com |
+| 腾讯云 | 华南（广州） | ap-guangzhou-tencentcloud | ap-guangzhou-tencentcloud.api.clickzetta.com |
+| AWS | 北京 | cn-north-1-aws | cn-north-1-aws.api.clickzetta.com |
+
+JDBC URL 格式：`jdbc:clickzetta://<instance_name>.<region_id>.api.clickzetta.com/`
+

package/bin/skills/clickzetta-overview/references/studio-modules.md

@@ -0,0 +1,173 @@
+# Studio 各模块详细说明
+
+> 来源：https://www.yunqi.tech/documents/LakehouseStudioTour 等官方文档
+
+---
+
+## 任务类型完整列表
+
+| 任务类型 | 触发方式 | 使用 VCluster | 典型用途 |
+|---|---|---|---|
+| SQL 任务 | 周期调度 / 手动 | GP 或 AP | ETL、Ad-Hoc 查询、DDL 操作 |
+| Python 任务 | 周期调度 / 手动 | 不使用 | ZettaPark 数据处理、文件操作 |
+| Shell 任务 | 周期调度 / 手动 | 不使用 | 系统命令、文件处理 |
+| JDBC 任务 | 周期调度 / 手动 | 不使用 | 操作 MySQL/Hive/ClickHouse 等 |
+| 动态表任务 | 向导式创建 | GP 或 AP | 声明式增量计算 |
+| 离线同步任务 | 周期调度 | 同步型 | 全量/增量批量同步 |
+| 实时同步任务（单表） | 持续运行 | 同步型 | Kafka/MySQL/PG 实时写入 |
+| 多表实时 CDC | 持续运行 | 同步型 | 整库镜像、分库分表合并 |
+| 组合任务 | 周期调度 | 取决于子任务 | 封装多个任务统一调度 |
+| 虚拟节点 | 周期调度 | 不使用 | 占位节点，用于依赖编排 |
+
+---
+
+## 任务状态说明
+
+| 状态 | 含义 |
+|---|---|
+| 已提交，有修改 | 任务已提交到生产，但本地有未提交的修改 |
+| 已提交，无修改 | 生产版本与本地版本一致 |
+| 已下线 | 任务已停止调度 |
+| 未提交 | 仅在开发环境，未发布到生产 |
+
+---
+
+## 调度配置关键参数
+
+### Cron 表达式示例
+
+```
+# 每天凌晨 2 点执行
+0 2 * * *
+
+# 每小时执行一次
+0 * * * *
+
+# 每 5 分钟执行一次
+*/5 * * * *
+
+# 每月 1 号凌晨 1 点执行
+0 1 1 * *
+```
+
+### 依赖策略
+
+| 策略 | 说明 | 适用场景 |
+|---|---|---|
+| 默认 | 上游当天实例完成后触发下游 | 标准 ETL 链路 |
+| 向前 | 上游最近一个完成的实例触发 | 上游频率高于下游 |
+| 向前就近 | 上游最近且时间最接近的实例触发 | 时间对齐要求高 |
+
+---
+
+## 任务参数内置时间函数
+
+| 表达式 | 含义 | 示例（今天 2024-01-15） |
+|---|---|---|
+| `$[yyyy-MM-dd]` | 当天日期 | 2024-01-15 |
+| `$[yyyy-MM-dd, -1d]` | 昨天 | 2024-01-14 |
+| `$[yyyy-MM-dd, +1d]` | 明天 | 2024-01-16 |
+| `$[yyyyMM]` | 当月 | 202401 |
+| `$[yyyyMM, -1M]` | 上月 | 202312 |
+| `$[yyyy-MM-dd HH:mm:ss]` | 当前时间 | 2024-01-15 10:30:00 |
+| `$[HH:mm:ss]` | 当前时间（仅时分秒） | 10:30:00 |
+| `sys_plan_datetime` | 任务计划执行时间 | 系统内置参数 |
+
+---
+
+## 数据质量规则六大维度
+
+| 维度 | 说明 | 示例规则 |
+|---|---|---|
+| 完整性 | 字段非空率 | `user_id` 非空率 ≥ 99% |
+| 唯一性 | 主键/唯一键重复检测 | `order_id` 无重复 |
+| 一致性 | 跨表数据一致 | 订单表与明细表金额一致 |
+| 准确性 | 数值范围合理性 | `age` 在 0-150 之间 |
+| 有效性 | 格式/枚举值合法 | `status` 在 ['active','inactive'] 中 |
+| 及时性 | 数据更新时效 | 每天 8 点前数据已更新 |
+
+### 触发方式
+
+- **定时触发**：Cron 表达式，独立于任务调度
+- **调度任务触发**：绑定到某个 SQL/同步任务，任务完成后自动触发质量检测
+- **手动触发**：在 Studio 界面手动执行
+
+---
+
+## 数据目录（Data Catalog）功能
+
+### 表详情页六大 Tab
+
+| Tab | 内容 |
+|---|---|
+| 详情 | DDL 语句（一键复制）、权限管理入口 |
+| 字段 | 字段名/类型/描述/主键/标准化标签 |
+| 预览 | 100 行数据预览（需 SELECT 权限 + 指定 VCluster） |
+| 血缘 | 上下游表关系图（数据血缘） |
+| 作业 | 该表相关的查询历史 |
+| 上传 | 本地文件直接上传到表 |
+
+### 搜索支持的过滤条件
+
+- 对象类型：Table / View / Materialized View
+- 工作空间 / Schema
+- 创建时间范围
+- 负责人
+
+---
+
+## 运维监控告警
+
+### 内置告警规则
+
+| 规则 | 触发条件 |
+|---|---|
+| 周期任务实例运行失败 | 任务实例执行失败 |
+| 数据质量检测失败 | 质量规则校验不通过 |
+| Pipe 延迟告警 | Kafka/OSS Pipe 消费延迟超阈值 |
+| 同步任务失败 | 离线/实时同步任务异常 |
+| 自定义规则 | 用户自定义 SQL 条件 |
+
+### 告警通知渠道
+
+- 飞书 webhook
+- 企业微信 webhook
+- 邮件（部分版本）
+
+---
+
+## 数据同步支持的数据源（部分）
+
+### 离线同步（批量）
+
+MySQL · PostgreSQL · SQL Server · Oracle · Aurora · PolarDB · ClickHouse · Hive · HDFS · OSS/S3/COS · Lakehouse
+
+### 实时同步（CDC）
+
+MySQL（Binlog）· PostgreSQL（WAL）· Kafka（JSON/Avro/CSV）
+
+### 连接方式
+
+- 公网直连
+- SSH Tunnel（连接 VPC 内数据库）
+- 私网连接（PrivateLink）
+
+---
+
+## Python 任务中使用数据源
+
+Studio Python 任务内置 `clickzetta-dbutils` 工具包，可直接使用预配置的数据源：
+
+```python
+from clickzetta import dbutils
+
+# 使用预配置的 Lakehouse 数据源
+conn = dbutils.get_connection('my_lakehouse_datasource')
+cursor = conn.cursor()
+cursor.execute("SELECT * FROM my_schema.my_table LIMIT 10")
+rows = cursor.fetchall()
+print(rows)
+
+# 使用预配置的 MySQL 数据源
+mysql_conn = dbutils.get_connection('my_mysql_datasource')
+```

package/bin/skills/clickzetta-query-optimizer/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"为什么这个 JOIN 查询这么慢？SELECT t1.user_id, t2.tenant_name FROM public.dim_studio_user_dmin_f t1 JOIN public.dim_studio_tenant_dmin_f t2 ON t1.tenant_id = t2.tenant_id","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["JOIN","优化"]}
+{"case_id":"002","type":"should_call","user_input":"public.dwd_studio_lakehouse_jobs_dd_i 表适合设置什么 Sort Key？","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["sort","key"]}
+{"case_id":"003","type":"should_call","user_input":"怎么开启结果缓存？Result Cache 的使用限制是什么？","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["cache","cz.sql.enable"]}
+{"case_id":"004","type":"should_call","user_input":"表有很多小文件影响查询性能，怎么合并优化？","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["OPTIMIZE","小文件"]}
+{"case_id":"005","type":"should_call","user_input":"怎么用 EXPLAIN 分析执行计划？Map Join 什么时候用？","expected_skill":"clickzetta-query-optimizer","expected_output_contains":["EXPLAIN","Map Join"]}

package/bin/skills/cz-cli/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: cz-cli-v2
+name: cz-cli
 description: Route ALL ClickZetta Lakehouse operations to cz-cli: SQL, Studio tasks, tables, pipelines, profiles. Use when user mentions ClickZetta, Lakehouse, cz-cli, or needs profile/connection configuration.
 ---
 

package/bin/skills/cz-cli-inner/SKILL.md

@@ -70,6 +70,14 @@ cz-cli job result <job-id>                    Fetch job result set
 
 cz-cli status                                 Check connection status
 cz-cli profile list                           List connection profiles
+
+cz-cli datasource list [--type <type>] [--name <filter>]
+                                              List external data sources (type: mysql/kafka/redis/postgresql/...)
+cz-cli datasource catalogs <name_or_id>      List catalogs (databases/topics/buckets) in a data source
+cz-cli datasource objects <name_or_id> <catalog>
+                                              List objects (tables/topics/collections) in a catalog
+cz-cli datasource describe <name_or_id> <catalog> <object>
+                                              Show object metadata (columns, types)
 ```
 
 ## Output Formats

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clickzetta/cz-cli-darwin-x64",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "cz-cli binary for macOS x64 (Intel)",
   "os": ["darwin"],
   "cpu": ["x64"],