@clickzetta/cz-cli-linux-x64 0.3.2 → 0.3.5

package/bin/skills/clickzetta-query-optimizer/references/optimize.md

@@ -1,65 +0,0 @@
-# OPTIMIZE 命令参考
-
-> 来源：https://www.yunqi.tech/documents/OPTIMIZE 和 https://www.yunqi.tech/documents/small_file_optimization
-
-## 语法
-
-```sql
-OPTIMIZE table_name
-[WHERE predicate]
-[OPTIONS('key' = 'value')]
-```
-
-## 参数说明
-
-- `table_name`：格式为 `[schema_name.]table_name`
-- `WHERE predicate`：（可选）分区过滤条件，必须包含完整分区列匹配
-  - 格式：`partition_column = 'value'` 或 `dt='2023-01-01' AND region='us'`
-- `OPTIONS`：（可选）控制执行模式
-
-## 执行模式
-
-### 异步模式（默认）
-
-立即返回 Job ID，后台执行，不阻塞当前连接。
-
-```sql
--- 默认异步
-OPTIMIZE my_schema.orders;
-
--- 显式指定异步
-OPTIMIZE my_schema.orders OPTIONS('cz.sql.optimize.table.async' = 'true');
-```
-
-### 同步模式
-
-阻塞直到完成，适合开发测试和小表优化。
-
-```sql
-OPTIMIZE my_schema.orders OPTIONS('cz.sql.optimize.table.async' = 'false');
-```
-
-## 核心功能
-
-- **小文件合并**：将多个小文件整合为大文件，减少文件元数据开销
-- **删除标记清理**：清理 UPDATE/DELETE 产生的删除标记，回收存储空间
-- **数据重组**：重新整理数据布局，提升查询性能
-
-## 注意事项
-
-- **只能在通用型计算集群（GENERAL PURPOSE VIRTUAL CLUSTER）运行**，分析型集群不生效
-- 后台默认会不定时自动执行文件合并，手动 OPTIMIZE 用于精细控制
-
-## DML 写入时自动触发小文件合并
-
-```sql
--- 在 DML 执行时同时触发小文件合并
-SET cz.sql.compaction.after.commit = true;
-INSERT INTO my_table VALUES (...);
-```
-
-## 查看分区文件数量
-
-```sql
-SHOW PARTITIONS EXTENDED table_name;
-```

package/bin/skills/clickzetta-query-optimizer/references/result-cache.md

@@ -1,49 +0,0 @@
-# Result Cache（查询结果缓存）参考
-
-> 来源：https://www.yunqi.tech/documents/result_cache
-
-## 概述
-
-ClickZetta Lakehouse 提供三种缓存：
-1. **查询结果缓存（Result Cache）** — 本文档
-2. 元数据缓存（Metadata Cache）— 工作空间内共享
-3. 虚拟集群本地缓存（Local Disk Cache）— 仅限指定集群
-
-## 启用 / 禁用
-
-```sql
--- 开启结果缓存（SESSION 级别）
-SET cz.sql.enable.shortcut.result.cache = true;
-
--- 关闭结果缓存
-SET cz.sql.enable.shortcut.result.cache = false;
-```
-
-> 注意：当前默认未开启，需手动启用。
-
-## 缓存复用条件（同时满足才能命中）
-
-1. 查询中使用的表数据未发生变更
-2. 查询中不包含视图引用
-3. 新 SQL 与之前执行的 SQL 语法精确匹配
-4. 查询中不包含非确定性函数（如 `CURRENT_TIMESTAMP()`）或 UDF
-5. 之前的 Result Cache 未过期
-
-## 过期周期
-
-- 默认保留 **24 小时**
-- 24 小时内有查询复用，则额外延长 24 小时
-- 超过 24 小时无复用则清除
-
-## 约束与限制
-
-| 项目 | 限制 |
-|---|---|
-| 缓存保留周期 | 24 小时 |
-| 单工作空间最大缓存作业数 | 10 万 |
-| 缓存大小 | 无限制（≤10MB 存内存，>10MB 持久化到对象存储） |
-| 不支持 | 含非确定性函数、UDF 的查询 |
-
-## 验证是否命中缓存
-
-第二次执行相同查询后，在 Job Profile 的执行计划图中查看是否出现 `JOB RESULT REUSE` 标记。命中缓存的查询通常在 15ms 内返回。

package/bin/skills/clickzetta-query-optimizer/references/show-jobs.md

@@ -1,42 +0,0 @@
-# SHOW JOBS 参考
-
-> 来源：https://www.yunqi.tech/documents/show-jobs
-
-## 语法
-
-```sql
-SHOW JOBS [IN VCLUSTER vc_name] [LIKE 'pattern'] [WHERE <expr>] [LIMIT num];
-```
-
-## 参数说明
-
-- `IN VCLUSTER vc_name`：（可选）筛选指定计算集群下的作业
-- `WHERE <expr>`：（可选）按字段过滤，支持 SHOW JOBS 返回的所有字段
-- `LIMIT num`：（可选）限制返回数量，范围 1-10000
-- `LIKE 'pattern'`：（可选）按 job_id 模式匹配，支持 `%` 和 `_`
-
-默认显示最近 7 天内提交的任务，最多 10000 条。
-
-## 示例
-
-```sql
--- 查看执行时间超过 2 分钟的作业
-SHOW JOBS IN VCLUSTER default_ap WHERE execution_time > interval 2 minute;
-
--- 查看指定集群的所有作业
-SHOW JOBS IN VCLUSTER default_ap;
-
--- 限制返回 100 条
-SHOW JOBS LIMIT 100;
-
--- 查看指定集群最近 50 条
-SHOW JOBS IN VCLUSTER default_ap LIMIT 50;
-
--- 按 job_id 模式匹配
-SHOW JOBS LIKE 'job_2024%';
-```
-
-## 注意事项
-
-- 只能查看最近 7 天内的作业记录
-- 未指定 VCLUSTER 时显示所有集群的作业

package/bin/skills/clickzetta-realtime-sync-pipeline/SKILL.md

@@ -1,197 +0,0 @@
----
-name: clickzetta-realtime-sync-pipeline
-description: |
-  创建和管理 ClickZetta Lakehouse 实时同步任务（单表），将外部数据源的数据实时同步到 Lakehouse。
-  支持 Kafka、MySQL、PostgreSQL 等数据源作为来源端，Lakehouse 作为目标端。
-  实时同步任务为持续运行的流式任务，无需配置调度策略，提交后即持续运行。
-  当用户说"Studio 实时同步"、"realtime sync"、"单表 CDC 同步"、"实时数据同步"、"Kafka 实时同步到 Lakehouse"、
-  "MySQL 单表实时同步"、"单表实时同步"、"实时数据迁移"时触发。
-  包含实时同步任务创建、数据源配置、字段映射（含 JSONPath 计算列）、部署运维等
-  ClickZetta Studio 特有逻辑。
-  Keywords: real-time sync, single table, Kafka source, MySQL source, streaming
----
-
-# 实时同步（单表）Pipeline 工作流
-
-## 适用场景
-
-- 将外部数据源的数据实时同步到 Lakehouse（低延迟、持续运行）
-- Kafka Topic → Lakehouse 表（支持 JSON 消息解析）
-- MySQL / PostgreSQL / SQL Server 等数据库 → Lakehouse 表（CDC 变更捕获）
-- 数据时效性要求高，需要秒级或分钟级延迟
-- 单张源表/Topic 到单张目标表的实时同步
-- 关键词：实时同步、CDC、流式同步、realtime sync、Kafka 实时同步
-
-## 与其他同步方式的区别
-
-| 维度 | 实时同步（本 Skill） | 离线同步 | 多表实时同步 |
-|------|---------------------|---------|------------|
-| 任务类型 ID | `28`（实时同步） | `10` / `291` | `281` |
-| 同步粒度 | 单表/单 Topic | 单表/多表 | 整库/多表 |
-| 运行模式 | 持续运行（流式） | 周期调度（批量） | 持续运行（流式） |
-| 调度策略 | 无需配置，提交即运行 | 需配置 Cron 表达式 | 无需配置，提交即运行 |
-| 延迟 | 秒级~分钟级 | 取决于调度周期 | 秒级~分钟级 |
-| 适用 Skill | `clickzetta-realtime-sync-pipeline` | `clickzetta-batch-sync-pipeline` | `clickzetta-cdc-sync-pipeline` |
-
-## 前置依赖
-
-- ClickZetta Lakehouse Studio 账户，具备创建同步任务、目标表的权限
-- 源端数据源已在 Studio 中配置（Kafka / MySQL / PostgreSQL / SQL Server 等）
-- 目标端 Lakehouse 数据源可用
-- Sync VCluster 可用（实时同步任务 task_type=28 需要 Sync VCluster）
-- clickzetta-studio-mcp 工具可用（`create_task`、`save_integration_task`、`publish_task`、`list_data_sources`、`LH_show_object_list` 等）
-
-## 工作流
-
-### 步骤 1：确认 Sync VCluster 可用
-
-```
-使用 LH_show_object_list（object_type='VCLUSTERS'）查看可用虚拟集群。
-筛选 vcluster_type 包含 SYNC 的集群。
-如无可用 Sync VCluster，需先创建后再继续。
-```
-
-### 步骤 2：查找可用数据源
-
-```
-使用 list_data_sources 查看已配置的数据源列表。
-按类型过滤：
-- Kafka: ds_type=2
-- MySQL: ds_type=5
-- PostgreSQL: ds_type=7
-- SQL Server: ds_type=8
-记录源端 datasource_name 和目标端 Lakehouse datasource_name。
-```
-
-### 步骤 3：探查源端数据结构（可选）
-
-```
-使用 list_namespaces 查看源端数据源的命名空间（数据库/Schema）。
-使用 list_metadata_objects 查看命名空间下的表/Topic 列表。
-使用 get_metadata_detail 查看具体表/Topic 的字段结构。
-```
-
-### 步骤 4：创建实时同步任务
-
-```
-使用 create_task 创建任务：
-- task_type: 28（实时同步）
-- task_name: 自定义任务名称（建议包含源和目标信息，如 "rt_sync_kafka_orders"）
-- data_folder_id: 目标文件夹 ID（可通过 list_folders 获取）
-
-记录返回的 task_id 和 studio_url。
-```
-
-### 步骤 5：配置同步内容
-
-```
-使用 save_integration_task 配置同步：
-- task_id: 步骤 4 返回的任务 ID
-- source_datasource_name: 源端数据源名称
-- source_schema: 源端数据库/Schema（Kafka 场景为 Topic 所在命名空间）
-- source_table: 源端表名或 Kafka Topic 名称
-- source_ds_type: 源端类型（2=Kafka, 5=MySQL, 7=PostgreSQL, 8=SQL Server）
-- sink_datasource_name: 目标 Lakehouse 数据源名称
-- sink_schema: 目标 Schema（默认 public）
-- sink_table: 目标表名（可选，默认与源表同名）
-- sink_ds_type: 1（Lakehouse）
-```
-
-> **说明**：系统会自动获取源端和目标端的元数据，生成字段映射。如目标表不存在，会自动创建。
-
-### 步骤 6：Kafka JSON 消息解析（Kafka 数据源专用）
-
-如果 Kafka Topic 的消息格式为 JSON，可在 Studio UI 中通过新增计算列解析嵌套字段：
-
-- 使用 JSONPath 规则解析 value 字段中的内容
-- 示例：`$.id` 提取顶层 id 字段，`$.data.code` 提取嵌套字段
-- 默认使用 Kafka Topic 内置字段（key、value、timestamp、partition、offset）进行映射
-- 计算列配置需在 Studio UI 中完成（通过 studio_url 打开）
-
-### 步骤 7：提交部署
-
-```
-实时同步任务不需要配置调度策略（无需调用 save_task_configuration）。
-直接使用 publish_task 提交任务：
-- task_id: 任务 ID
-- task_version: 当前版本号（通过 get_task_detail 获取）
-
-提交后任务即开始持续运行。
-```
-
-> **重要**：实时同步任务不支持开发状态下的测试运行，提交即为正式部署。
-
-### 步骤 8：运维监控
-
-```
-提交后在运维中心管理实时同步任务：
-
-查看任务状态：get_task_detail
-查看运行记录：list_task_run（注意实时任务为持续运行，不同于离线任务的周期实例）
-
-Studio UI 中可进行：
-- 启动/停止任务
-- 查看同步延迟和吞吐量
-- 查看错误日志
-```
-
----
-
-## 支持的数据源
-
-### 来源端
-
-| 数据源 | ds_type | 说明 |
-|--------|---------|------|
-| Kafka | 2 | 支持 JSON 消息解析（JSONPath 计算列） |
-| MySQL | 5 | CDC 变更捕获 |
-| PostgreSQL | 7 | CDC 变更捕获 |
-| SQL Server | 8 | CDC 变更捕获 |
-| Aurora MySQL | 39 | CDC 变更捕获 |
-| Aurora PostgreSQL | 40 | CDC 变更捕获 |
-| PolarDB MySQL | 19 | CDC 变更捕获 |
-| PolarDB PostgreSQL | 48 | CDC 变更捕获 |
-
-### 目标端
-
-| 数据源 | ds_type |
-|--------|---------|
-| Lakehouse | 1 |
-
-## 故障排除
-
-| 问题 | 排查方向 |
-|------|---------|
-| 任务创建失败 | 检查是否有可用的 Sync VCluster（`LH_show_object_list` 查看 VCLUSTERS，筛选 SYNC 类型） |
-| 源端连接失败 | 检查数据源配置中的连接信息、网络可达性、账号权限 |
-| Kafka 消费无数据 | 检查 Topic 名称是否正确、消费位点设置、Kafka 集群连通性 |
-| JSON 解析失败 | 检查 JSONPath 表达式是否正确、消息格式是否为合法 JSON |
-| 同步延迟增大 | 检查 Sync VCluster 资源是否充足、源端数据量是否突增 |
-| 目标表写入失败 | 检查目标表是否存在、字段类型是否兼容、权限是否充足 |
-| 任务异常停止 | 查看执行日志（`list_executions` + `get_execution_log`）排查具体错误 |
-
-## 注意事项
-
-### 运行模式
-
-- 实时同步任务为持续运行的流式任务，提交后即开始运行，无需配置调度
-- 不支持开发状态下的测试运行
-- 停止后需手动重新启动
-
-### Sync VCluster 要求
-
-- 实时同步任务（task_type=28）必须使用 Sync VCluster
-- 创建任务前需确认有可用的 Sync VCluster
-- 可通过 `LH_show_object_list`（object_type='VCLUSTERS'）查看，筛选 vcluster_type 包含 SYNC 的集群
-
-### Kafka 数据源特殊说明
-
-- 支持指定消费起始位点（earliest / latest / 指定 offset）
-- JSON 消息可通过 JSONPath 计算列解析嵌套字段
-- 默认字段包括：key、value、timestamp、partition、offset
-
-### 与多表实时同步的选择
-
-- 单表实时同步（本 Skill）：适合单张表/Topic 的精细化同步
-- 多表实时同步（`clickzetta-cdc-sync-pipeline`）：适合整库 CDC、多表批量实时同步
-- 如需同步整个数据库的所有表，建议使用多表实时同步

package/bin/skills/clickzetta-semantic-view/SKILL.md

@@ -1,207 +0,0 @@
----
-name: clickzetta-semantic-view
-description: |
-  创建和查询 ClickZetta Lakehouse 语义视图（Semantic View）。语义视图是架构级逻辑
-  数据模型对象，通过声明逻辑表、维度、指标、过滤器，将复杂的多表 JOIN 和聚合逻辑封装
-  为业务友好的语义层，使用 semantic_view() 函数查询，无需手写 JOIN。
-  当前为邀测功能（1.3 版本起）。
-  当用户说"创建语义视图"、"semantic view"、"语义层"、"定义指标"、"定义维度"、
-  "semantic_view() 怎么用"、"统一指标口径"、"业务语义模型"、"逻辑表"、
-  "DIMENSIONS"、"METRICS"、"FILTERS"、"DROP SEMANTIC VIEW"、
-  "SHOW SEMANTIC VIEWS"时触发。
-  Keywords: semantic view, dimension, metric, logical model, unified metrics, semantic layer
----
-
-# ClickZetta 语义视图（Semantic View）
-
-阅读 [references/semantic-view-reference.md](references/semantic-view-reference.md) 了解完整语法。
-
----
-
-## 概述
-
-语义视图是 ClickZetta Lakehouse 的**架构级逻辑数据模型对象**，解决两类核心问题：
-
-- **数据分析**：统一维度和指标定义，业务用户无需编写复杂 JOIN 即可查询跨表数据
-- **数据治理**：集中管理表关系、维度、指标定义，确保全组织使用相同数据口径
-
-> ⚠️ 当前为**邀测功能**（1.3 版本），需联系技术支持开通。
-
----
-
-## 四大组件
-
-| 组件 | 关键字 | 说明 |
-|---|---|---|
-| 逻辑表 | `TABLES` | 映射物理表，声明主键和外键关系，引擎自动处理 JOIN |
-| 维度 | `DIMENSIONS` | 分类属性（谁/什么/哪里/何时），支持计算维度 |
-| 指标 | `METRICS` | 聚合度量（SUM/AVG/COUNT/MIN/MAX），业务 KPI |
-| 过滤器 | `FILTERS` | 预定义可重用过滤条件（语义注解，不可直接传入查询） |
-
----
-
-## 创建语义视图
-
-```sql
-CREATE SEMANTIC VIEW <视图名>
-TABLES (
-    <表别名> AS <schema>.<物理表>
-        PRIMARY KEY (<列名>)
-        [ FOREIGN KEY (<列名>) REFERENCES <其他表别名> ]
-        [ WITH SYNONYMS ('<同义词>') ]
-        [ COMMENT = '<说明>' ]
-    [ , ... ]
-)
-[ FILTERS (
-    <表别名>.<过滤器名> AS <布尔表达式>
-    [ , ... ]
-) ]
-DIMENSIONS (
-    { <表别名>.<维度名> | <维度名> } AS <表达式>
-        [ WITH SYNONYMS = ('<同义词>' [ , ... ]) ]
-        [ is_unique = { true | false } ]
-        [ is_time = { true | false } ]
-        [ enum_values = [ <值1>, <值2>, ... ] ]
-        [ COMMENT = '<说明>' ]
-    [ , ... ]
-)
-METRICS (
-    <表别名>.<指标名> AS <聚合表达式>
-        [ COMMENT = '<说明>' ]
-    [ , ... ]
-)
-[ COMMENT = '<视图说明>' ];
-```
-
-### 完整示例（TPC-H 收入分析）
-
-```sql
-DROP SEMANTIC VIEW IF EXISTS tpch_rev_analysis;
-CREATE SEMANTIC VIEW tpch_rev_analysis
-TABLES (
-    customers AS tpch.customer
-        PRIMARY KEY (c_custkey)
-        COMMENT = '客户主表',
-    orders AS tpch.orders
-        PRIMARY KEY (o_orderkey)
-        FOREIGN KEY (o_custkey) REFERENCES customers
-        WITH SYNONYMS ('销售订单')
-        COMMENT = '订单表',
-    line_items AS tpch.lineitem
-        PRIMARY KEY (l_orderkey, l_linenumber)
-        FOREIGN KEY (l_orderkey) REFERENCES orders
-        COMMENT = '订单明细'
-)
-FILTERS (
-    customers.is_building AS customers.c_mktsegment = 'BUILDING'
-)
-DIMENSIONS (
-    customers.customer_name AS c_name
-        WITH SYNONYMS = ('客户名称', 'customer name')
-        is_unique = true
-        COMMENT = '客户名称',
-    orders.order_date AS o_orderdate
-        is_time = true
-        COMMENT = '下单日期',
-    orders.order_year AS YEAR(o_orderdate)
-        COMMENT = '下单年份',
-    orders.order_status AS o_orderstatus
-        enum_values = ['O', 'F', 'P']
-        COMMENT = '订单状态'
-)
-METRICS (
-    customers.customer_count AS COUNT(c_custkey)
-        COMMENT = '客户总数',
-    orders.avg_order_value AS AVG(o_totalprice)
-        COMMENT = '平均订单金额',
-    orders.total_revenue AS SUM(o_totalprice)
-        COMMENT = '总收入'
-)
-COMMENT = '收入分析语义视图';
-```
-
----
-
-## 查询语义视图
-
-使用 `semantic_view()` 表函数，**无需手写 JOIN 和 GROUP BY**：
-
-```sql
--- 基础查询：按订单日期统计平均订单金额
-SELECT * FROM semantic_view(
-    tpch_rev_analysis,
-    DIMENSIONS orders.order_date,
-    METRICS orders.avg_order_value
-);
-
--- 多维度查询：按日期和客户名称
-SELECT * FROM semantic_view(
-    tpch_rev_analysis,
-    DIMENSIONS orders.order_date,
-    DIMENSIONS customers.customer_name,
-    METRICS orders.avg_order_value
-);
-
--- 使用短名称（名称唯一时可省略表别名前缀）
-SELECT * FROM semantic_view(
-    tpch_rev_analysis,
-    DIMENSIONS order_date,
-    DIMENSIONS customer_name,
-    METRICS avg_order_value
-);
-
--- 加 WHERE 过滤（需将过滤列定义为 DIMENSION）
-SELECT * FROM semantic_view(
-    tpch_rev_analysis,
-    DIMENSIONS customers.customer_name,
-    DIMENSIONS orders.order_status,
-    METRICS orders.total_revenue
-) WHERE order_status = 'O';
-```
-
-### 与传统 SQL 对比
-
-```sql
--- 传统 SQL（需手写 JOIN + GROUP BY）
-SELECT o.o_orderdate, c.c_name, AVG(o.o_totalprice)
-FROM tpch.orders o
-JOIN tpch.customer c ON o.o_custkey = c.c_custkey
-GROUP BY o.o_orderdate, c.c_name;
-
--- 语义视图（自动处理 JOIN 和聚合）
-SELECT * FROM semantic_view(
-    tpch_rev_analysis,
-    DIMENSIONS order_date,
-    DIMENSIONS customer_name,
-    METRICS avg_order_value
-);
-```
-
----
-
-## 管理命令
-
-```sql
--- 删除（推荐先删再建，确保幂等）
-DROP SEMANTIC VIEW IF EXISTS tpch_rev_analysis;
-
--- 列出当前 Schema 的所有语义视图
-SHOW SEMANTIC VIEWS;
-SHOW SEMANTIC VIEWS IN my_schema;
-
--- 查看详细定义（逻辑表、维度、指标、外键）
-DESC EXTENDED tpch_rev_analysis;
-```
-
----
-
-## 注意事项
-
-1. **TABLES 定义顺序**：被外键引用的表必须先定义（如 `customers` 必须在 `orders` 之前）
-2. **FILTERS 是语义注解**：`FILTERS` 中的命名过滤器不能作为 `semantic_view()` 的参数，WHERE 子句只能引用 `DIMENSIONS` 中定义的列名（短名），不能用物理列名
-3. **WHERE 只能用 DIMENSION 短名**：`WHERE customer_name = 'Alice'` ✅，`WHERE c_name = 'Alice'` ❌
-4. **短名称 vs 限定名称**：名称在视图内唯一时可用短名称，有冲突时必须用 `表别名.名称`
-5. **幂等创建**：始终先 `DROP SEMANTIC VIEW IF EXISTS` 再创建，避免重复执行报错
-6. **计算维度**：DIMENSIONS 支持表达式，如 `YEAR(CAST(order_date AS DATE))` 提取年份
-7. **指标聚合函数**：仅支持 `COUNT`、`AVG`、`SUM`、`MIN`、`MAX`
-8. **DIMENSIONS 和 METRICS 可单独使用**：可以只查 METRICS（全局聚合），也可以只查 DIMENSIONS（去重列表）