@clickzetta/cz-cli-darwin-arm64 0.3.81 → 0.3.84

package/bin/skills/clickzetta-file-import-pipeline/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: clickzetta-file-import-pipeline
+description: |
+  从 URL、本地文件或 Volume 路径将数据导入到 ClickZetta 表中，覆盖文件下载、格式推断、
+  表创建、COPY INTO 导入、结果验证的完整流程。当用户说"导入数据"、"从 URL 加载"、
+  "上传 CSV 到表"、"文件导入"、"COPY INTO"时触发。包含 ClickZetta USER VOLUME 机制、
+  COPY INTO 语法、格式推断规则、写入模式语义等平台特有知识。
+  Keywords: file import, URL, CSV, JSON, Parquet, COPY INTO, Volume
+---
+
+# URL/文件数据导入工作流
+
+## 向导：收集必要信息
+
+开始导入前，优先使用交互式问答工具（如 `question`）收集以下信息并弹出选项菜单；若无此类工具，则用文字一次性列出所有问题：
+
+```
+question({
+  questions: [
+    {
+      question: "文件来源？",
+      options: [
+        { label: "HTTP/HTTPS URL", description: "提供完整链接，自动下载" },
+        { label: "本地文件", description: "本地路径，上传到 User Volume" },
+        { label: "已在 Volume 上", description: "提供 Volume 名称和文件路径" },
+        { label: "外部 Volume（OSS/S3/COS）", description: "提供外部存储路径" }
+      ]
+    },
+    {
+      question: "写入模式？",
+      options: [
+        { label: "create（自动建表）", description: "表不存在，推断 schema 后建表" },
+        { label: "append（追加）", description: "追加到已有表，不删除历史数据" },
+        { label: "overwrite（覆盖）", description: "清空已有表再写入" }
+      ]
+    }
+  ]
+})
+```
+
+**如果用户已经提供了足够信息，直接进入工作流，不再弹出菜单。**
+
+**如果用户已经提供了足够信息（如"把这个 URL 的 CSV 导入到 ods.orders 表"），直接进入步骤 1，不再重复询问。**
+
+---
+
+## 指令
+
+### 步骤 1：获取源文件并上传到 Volume
+根据数据来源选择对应方式：
+- **HTTP/HTTPS URL**：需要先用外部工具下载到本地，然后用 `PUT` 命令上传到 User Volume
+- **本地文件**：执行 SQL `PUT '/local/path/file.csv' TO USER VOLUME` 上传
+- **Volume 路径**：文件已在 Volume 上，跳过此步骤
+- **外部 Volume（OSS/S3/COS）**：文件已在外部 Volume，直接使用
+- 记录上传后的 Volume 名称和文件名，后续步骤需要
+
+> ⚠️ **注意**：文件上传操作参考 `clickzetta-volume-manager` skill。
+
+### 步骤 2：推断文件格式
+根据文件扩展名推断格式（ClickZetta COPY INTO 支持的格式）：
+- `.csv`, `.tsv`, `.txt` → CSV 格式
+- `.json`, `.jsonl`, `.ndjson` → JSON 格式
+- `.parquet`, `.pq` → PARQUET 格式
+- `.orc` → ORC 格式
+- `.bson` → BSON 格式
+如果扩展名不明确，执行 `SELECT FROM VOLUME ... USING format` 预览文件内容来确认格式和 schema。
+
+### 步骤 3：确认或创建目标表
+根据写入模式处理目标表：
+- **create 模式**：表必须不存在。执行 `SELECT FROM VOLUME ... LIMIT 5` 推断 schema，然后执行 `CREATE TABLE` 创建表
+- **append 模式**：表必须已存在。用 `DESC TABLE <table_name>` 确认表存在并检查列兼容性
+- **overwrite 模式**：表存在则先清空。执行 `TRUNCATE TABLE table_name`，再执行 COPY INTO（⚠️ 不支持 `COPY OVERWRITE INTO` 语法）
+
+### 步骤 4：执行 COPY INTO 导入数据
+执行 COPY INTO 语句。核心语法：
+
+```sql
+COPY INTO target_table
+FROM VOLUME volume_name
+USING format_type
+OPTIONS('option_name' = 'value')
+FILES('filename');
+```
+
+对于 USER VOLUME（通过 PUT 命令上传的文件）：
+```sql
+COPY INTO target_table
+FROM USER VOLUME
+USING CSV
+OPTIONS('header' = 'true')
+FILES('uploaded_filename');
+```
+
+CSV 格式可附加 OPTIONS：
+```sql
+COPY INTO target_table
+FROM VOLUME vol
+USING CSV
+OPTIONS('header' = 'true', 'sep' = ',', 'quote' = '"', 'nullValue' = '')
+FILES('data.csv');
+```
+
+⚠️ **语法顺序要求**：`OPTIONS` 必须在 `FILES` 之前，否则报错 `Syntax error - missing EQ at '('`
+
+overwrite 模式（⚠️ 不支持 `COPY OVERWRITE INTO`）：
+```sql
+-- 正确方式：先 TRUNCATE 再 COPY
+TRUNCATE TABLE target_table;
+COPY INTO target_table FROM VOLUME vol USING CSV FILES('data.csv');
+```
+
+### 步骤 5：验证导入结果
+执行验证查询：
+```sql
+SELECT COUNT(*) as row_count FROM target_table;
+SELECT * FROM target_table LIMIT 5;
+```
+确认行数符合预期，数据内容正确。
+
+## 示例
+
+### 示例 1：从 URL 导入 CSV 到新表
+```sql
+-- 1. 下载 URL 文件到本地，然后上传到 User Volume
+PUT '/tmp/data.csv' TO USER VOLUME;
+
+-- 2. 预览文件内容推断 schema
+SELECT * FROM USER VOLUME USING CSV OPTIONS('header' = 'true') FILES('data.csv') LIMIT 5;
+-- 推断出列：id INT, name STRING, value DOUBLE
+
+-- 3. 创建目标表
+CREATE TABLE imported_data (id INT, name STRING, value DOUBLE);
+
+-- 4. 执行 COPY INTO 导入（注意：OPTIONS 必须在 FILES 之前）
+COPY INTO imported_data FROM USER VOLUME USING CSV OPTIONS('header' = 'true') FILES('data.csv');
+
+-- 5. 验证导入结果
+SELECT COUNT(*) FROM imported_data;
+```
+
+### 示例 2：追加 Parquet 数据到已有表
+```sql
+-- 1. 上传本地文件到 User Volume
+PUT '/local/new_batch.parquet' TO USER VOLUME;
+
+-- 2. 确认目标表存在
+DESC TABLE existing_table;
+
+-- 3. 执行 COPY INTO 导入（Parquet 格式通常不需要 OPTIONS）
+COPY INTO existing_table FROM USER VOLUME USING PARQUET FILES('new_batch.parquet');
+
+-- 4. 验证导入结果
+SELECT COUNT(*) FROM existing_table;
+```
+
+### 示例 3：从外部 Volume（OSS）导入
+```sql
+-- 1. 查看 Volume 中的文件列表
+SHOW VOLUME DIRECTORY my_oss_volume;
+
+-- 2. 预览文件内容
+SELECT * FROM VOLUME my_oss_volume USING CSV OPTIONS('header' = 'true') FILES('data.csv') LIMIT 5;
+
+-- 3. 创建目标表并导入（注意：OPTIONS 必须在 FILES 之前）
+CREATE TABLE imported_data (col1 INT, col2 STRING);
+COPY INTO imported_data FROM VOLUME my_oss_volume USING CSV OPTIONS('header' = 'true') FILES('data.csv');
+```
+
+## 故障排除
+
+| 错误 | 原因 | 解决方案 |
+|------|------|----------|
+| COPY INTO 报 "table not found" | create 模式下表未创建，或 append 模式下表名拼写错误 | 先用 `SHOW TABLES` 确认表是否存在 |
+| COPY INTO 报 "file not found" | FILES 中的文件名与 Volume 上的实际文件名不匹配 | 执行 `SHOW VOLUME DIRECTORY vol_name` 或 `SHOW USER VOLUME DIRECTORY` 确认文件名，注意大小写敏感 |
+| COPY INTO 报语法错误 "missing EQ at '('" | OPTIONS 放在了 FILES 之后 | 调整顺序，确保 `OPTIONS` 在 `FILES` 之前：`USING CSV OPTIONS(...) FILES(...)` |
+| CSV 导入列数不匹配 | CSV 文件有 header 行但未指定 `OPTIONS('header'='true')`，导致 header 被当作数据行 | 添加 `OPTIONS('header' = 'true')`，或检查 CSV 分隔符是否正确（sep 参数） |
+| COPY INTO 报 "schema mismatch" | 文件中的数据类型与目标表列定义不兼容 | 执行 `SELECT FROM VOLUME ... USING format LIMIT 5` 预览实际数据，调整表定义或使用列映射 |
+| overwrite 模式数据未清空 | 使用了 `COPY OVERWRITE INTO` 语法（不支持） | overwrite 模式应先用 `TRUNCATE TABLE` 清空表，再执行 `COPY INTO` |
+| SELECT FROM VOLUME 报错 | 格式不匹配或多格式文件混合 | 确认 USING 后的格式与实际文件格式一致；使用 `FILES()` 指定文件或 `SUBDIRECTORY` 指定子目录 |
+| PUT 命令失败 | 本地文件路径不存在 | 确认本地文件路径正确，文件存在 |
+
+---
+
+## 依赖的 Skills
+
+| 操作 | 需要加载的 Skill |
+|------|-----------------|
+| 文件上传/下载/删除 | `clickzetta-volume-manager` |
+| 查询 Volume 文件内容 | `clickzetta-volume-manager` |
+| COPY INTO 导入 | 本 Skill |

package/bin/skills/clickzetta-file-import-pipeline/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"从 URL 导入文件到 Lakehouse 的步骤和语法是什么？","expected_skill":"clickzetta-file-import-pipeline","expected_output_contains":["Volume","COPY INTO"]}
+{"case_id":"002","type":"should_call","user_input":"本地文件上传到 Lakehouse 表的流程是什么？需要哪些步骤？","expected_skill":"clickzetta-file-import-pipeline","expected_output_contains":["Volume","COPY INTO"]}
+{"case_id":"003","type":"should_call","user_input":"COPY INTO 导入数据时 append 和 overwrite 写入模式有什么区别？请说明语法","expected_skill":"clickzetta-file-import-pipeline","expected_output_contains":["append","overwrite"]}
+{"case_id":"004","type":"should_call","user_input":"COPY INTO 导入前怎么推断文件格式？有哪些支持的格式类型？","expected_skill":"clickzetta-file-import-pipeline","expected_output_contains":["CSV","JSON","Parquet"]}
+{"case_id":"005","type":"should_call","user_input":"CSV 有自定义分隔符，COPY INTO 的 OPTIONS 怎么写？","expected_skill":"clickzetta-file-import-pipeline","expected_output_contains":["CSV","OPTIONS"]}

package/bin/skills/clickzetta-index-manager/LICENSE

@@ -0,0 +1,16 @@
+ClickZetta Skills License
+© 2026 Yunqi Inc. All rights reserved.
+LICENSE: Use of these materials (including all code, prompts, assets, files, and other components of these skills (collectively, "Skills")) is governed by your agreement with ClickZetta for the Service. If no separate agreement exists, use is governed by ClickZetta's Terms of Service (available at: https://yunqi.tech/documents/user-aggrement).
+Your applicable agreement is referred to as the "Agreement." "Service" is as defined in the Agreement.
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the contrary, you may not:
+
+Extract from the Service or retain copies of the Skills outside use with the Service;
+Reproduce or copy the Skills, except for temporary copies created automatically during authorized use of the Service;
+Create derivative works based on the Skills;
+Distribute, sublicense, or transfer the Skills to any third party;
+Make, offer to sell, sell, or import any inventions embodied in the Skills; nor,
+Reverse engineer, decompile, or disassemble the Skills.
+
+The receipt, viewing, or possession of the Skills does not convey or imply any license or right beyond those expressly granted above.
+Yunqi retains all rights, title, and interest in the Skills, including all copyrights, trademarks, patents, and all other applicable intellectual property rights.
+THE SKILLS ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SKILLS OR THE USE OR OTHER DEALINGS IN THE SKILLS.

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

@@ -0,0 +1,140 @@
+---
+name: clickzetta-index-manager
+description: |
+  管理 ClickZetta Lakehouse 的三类索引：Bloom Filter 索引（等值查询加速）、
+  倒排索引（全文检索）、向量索引（语义相似度搜索）。覆盖创建、构建存量数据、
+  删除、查看等完整生命周期，以及索引类型选择指南。
+  当用户说"创建索引"、"加索引"、"Bloom Filter"、"布隆过滤器"、"倒排索引"、
+  "全文检索"、"向量索引"、"向量搜索"、"相似度搜索"、"BUILD INDEX"、
+  "DROP INDEX"、"SHOW INDEX"、"查询加速"、"索引优化"时触发。
+  Keywords: index, bloom filter, inverted index, vector index, full-text search
+---
+
+# ClickZetta 索引管理
+
+## 索引类型选择
+
+| 需求 | 推荐索引 | 参考文件 |
+|---|---|---|
+| 高基数列等值查询（ID、邮箱、手机号） | Bloom Filter | [references/bloomfilter-index.md](references/bloomfilter-index.md) |
+| 文本关键词搜索、全文检索 | 倒排索引 | [references/inverted-index.md](references/inverted-index.md) |
+| 向量相似度搜索、语义检索、RAG | 向量索引 | [references/vector-index.md](references/vector-index.md) |
+| 存量数据补建索引、删除、查看 | — | [references/index-management.md](references/index-management.md) |
+
+## ⚠️ 关键注意事项
+
+- **所有索引只对新写入数据生效**，旧数据需用 `BUILD INDEX` 补建（Bloom Filter 除外，不支持 BUILD INDEX）
+- Bloom Filter 旧数据生效方法：`INSERT OVERWRITE table SELECT * FROM table`（重写数据）
+- `BUILD INDEX` 是同步任务，大表建议按分区逐批执行
+- **索引必须与表在同一 Schema 中**，跨 Schema 创建索引会报错（`index and table must in the same schema`）
+
+---
+
+## 步骤 1：选择索引类型并创建
+
+### Bloom Filter（等值查询加速）
+
+阅读 [references/bloomfilter-index.md](references/bloomfilter-index.md)
+
+```sql
+-- 建表时指定
+CREATE TABLE orders (
+    order_id INT,
+    INDEX order_id_idx (order_id) BLOOMFILTER
+);
+
+-- 已有表添加
+CREATE BLOOMFILTER INDEX idx_name
+ON TABLE my_schema.orders(order_id)
+COMMENT '订单ID布隆过滤器';
+```
+
+### 倒排索引（全文检索）
+
+阅读 [references/inverted-index.md](references/inverted-index.md)
+
+```sql
+-- 数值/日期列（不需要 PROPERTIES）
+CREATE INVERTED INDEX id_idx ON TABLE t(order_id);
+
+-- 字符串列（必须指定分词器，否则报错）
+-- ⚠️ 字符串列不指定 analyzer 会创建失败
+CREATE INVERTED INDEX title_idx
+ON TABLE articles(title)
+PROPERTIES('analyzer'='chinese');   -- 中文内容用 chinese
+
+-- 其他分词器选项：
+-- 'keyword'  → 不分词，整列作为一个词（适合精确匹配：状态码、标签）
+-- 'english'  → 英文分词
+-- 'unicode'  → 通用 Unicode 分词（中英混合）
+-- 'chinese'  → 中文分词（默认推荐）
+
+-- 查询
+SELECT * FROM articles WHERE match_any(title, '关键词', 'analyzer'='chinese');
+```
+
+### 向量索引（相似度搜索）
+
+阅读 [references/vector-index.md](references/vector-index.md)
+
+```sql
+CREATE VECTOR INDEX vec_idx
+ON TABLE embeddings(vec)
+PROPERTIES(
+    "scalar.type" = "f32",
+    "distance.function" = "cosine_distance"
+);
+```
+
+---
+
+## 步骤 2：为存量数据构建索引
+
+阅读 [references/index-management.md](references/index-management.md)
+
+```sql
+-- 全表构建（倒排索引和向量索引支持，Bloom Filter 不支持）
+BUILD INDEX index_name ON my_schema.table_name;
+
+-- 按分区构建（大表推荐）
+BUILD INDEX index_name ON table_name WHERE dt = '2024-01-01';
+```
+
+---
+
+## 步骤 3：查看和管理索引
+
+```sql
+-- 列出表的所有索引
+SHOW INDEX FROM my_schema.orders;
+
+-- 查看索引详情
+DESC INDEX index_name;
+DESC INDEX EXTENDED index_name;  -- 含索引大小
+
+-- 删除索引
+DROP INDEX IF EXISTS index_name;
+```
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 加了索引但查询没变快 | 旧数据未建索引 | 执行 `BUILD INDEX`（倒排/向量）或重写数据（Bloom Filter） |
+| BUILD INDEX 执行很慢 | 数据量大 | 按分区逐批执行 `BUILD INDEX ... WHERE partition=...` |
+| 倒排索引字符串列报错 | 未指定分词器（字符串列必须指定） | 添加 `PROPERTIES('analyzer'='chinese')` 或其他分词器 |
+| 向量索引查询结果不准 | ef.construction 太小 | 调大 `ef.construction`（默认 128，可调至 200-500） |
+
+---
+
+## 参考文档
+
+- [CREATE BLOOMFILTER INDEX](https://www.yunqi.tech/documents/CREATE-BLOOMFILTER-INDEX)
+- [CREATE INVERTED INDEX](https://www.yunqi.tech/documents/create-inverted-index)
+- [CREATE VECTOR INDEX](https://www.yunqi.tech/documents/create-vector-index)
+- [BUILD INDEX](https://www.yunqi.tech/documents/build-inverted-index)
+- [DROP INDEX](https://www.yunqi.tech/documents/DROP-INDEX)
+- [SHOW INDEX](https://www.yunqi.tech/documents/SHOW-INDEX)
+- [DESC INDEX](https://www.yunqi.tech/documents/DESC-INDEX)

package/bin/skills/clickzetta-index-manager/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"我想给 public.dim_studio_user_dmin_f 表的 user_id 列加个索引，加快等值查询速度","expected_skill":"clickzetta-index-manager","expected_output_contains":["BLOOMFILTER","INDEX"]}
+{"case_id":"002","type":"should_call","user_input":"我想在 login_name 列上创建倒排索引，支持用户名的模糊搜索","expected_skill":"clickzetta-index-manager","expected_output_contains":["INVERTED","INDEX"]}
+{"case_id":"003","type":"should_call","user_input":"Bloom Filter 索引和倒排索引分别适合什么场景？怎么选？","expected_skill":"clickzetta-index-manager","expected_output_contains":["Bloom","倒排"]}
+{"case_id":"004","type":"should_call","user_input":"索引创建后存量数据怎么生效？BUILD INDEX 怎么用？","expected_skill":"clickzetta-index-manager","expected_output_contains":["BUILD INDEX"]}
+{"case_id":"005","type":"should_call","user_input":"怎么查看表上有哪些索引？怎么删除不需要的索引？","expected_skill":"clickzetta-index-manager","expected_output_contains":["SHOW INDEX","DROP INDEX"]}

package/bin/skills/clickzetta-index-manager/references/bloomfilter-index.md

@@ -0,0 +1,67 @@
+# Bloom Filter 索引参考
+
+> 来源：https://www.yunqi.tech/documents/CREATE-BLOOMFILTER-INDEX
+
+## 适用场景
+
+高基数列（如 ID、邮箱、手机号）的**等值查询**加速。通过跳过不含目标值的数据文件，减少 I/O。
+
+不支持的列类型：INTERVAL、STRUCT、MAP、ARRAY。
+
+## 建表时创建
+
+```sql
+CREATE TABLE orders (
+    order_id INT,
+    customer_id INT,
+    amount DOUBLE,
+    INDEX order_id_idx (order_id) BLOOMFILTER COMMENT 'bloom filter on order_id',
+    INDEX customer_id_idx (customer_id) BLOOMFILTER
+) USING parquet;
+```
+
+## 已有表添加
+
+```sql
+CREATE BLOOMFILTER INDEX [IF NOT EXISTS] index_name
+ON TABLE [schema.]table_name(column_name)
+[COMMENT 'comment']
+[PROPERTIES ('key' = 'value')];
+```
+
+### ngram 分词器（用于字符串模糊匹配）
+
+```sql
+CREATE BLOOMFILTER INDEX idx_ngram
+ON TABLE demo(col_name)
+PROPERTIES ('analyzer' = 'ngram', 'n' = '3');
+```
+
+`n` 为 ngram 长度，例如 n=4 时 "Lakehouse" 被索引为 "Lake"、"akeh"、"keho"...
+
+## 注意事项
+
+- **只对新写入数据生效**，旧数据不生效
+- 旧数据需要生效：执行 `INSERT OVERWRITE table SELECT * FROM table` 重写数据
+- 一张表可以创建多个 Bloom Filter 索引
+- 目前只支持**单列索引**
+
+## 示例（完整流程）
+
+```sql
+-- 建表时指定
+CREATE TABLE t (
+    order_id INT,
+    customer_id INT,
+    INDEX order_id_index (order_id) BLOOMFILTER COMMENT 'BLOOMFILTER'
+);
+
+-- 查看索引
+SHOW INDEX FROM t;
+
+-- 查看索引详情
+DESC INDEX order_id_index;
+
+-- 删除索引
+DROP INDEX order_id_index;
+```

package/bin/skills/clickzetta-index-manager/references/index-management.md

@@ -0,0 +1,73 @@
+# 索引管理命令参考
+
+> 来源：https://www.yunqi.tech/documents/build-inverted-index、DROP-INDEX、SHOW-INDEX、DESC-INDEX
+
+---
+
+## BUILD INDEX（为存量数据构建索引）
+
+支持向量索引和倒排索引，**不支持 Bloom Filter**。
+
+```sql
+-- 全表构建
+BUILD INDEX index_name ON [schema.]table_name;
+
+-- 指定分区构建（支持 =, !=, >, >=, <, <=）
+BUILD INDEX index_name ON table_name
+WHERE partition_col1 = '2024-01-01' AND partition_col2 = 'us';
+```
+
+说明：
+- `BUILD INDEX` 是**同步任务**，执行过程消耗计算资源
+- 大分区表建议**按分区逐批**构建，避免单次消耗过多资源
+- 进度可通过 Job Profile 查看
+
+---
+
+## DROP INDEX（删除索引）
+
+```sql
+DROP INDEX [IF EXISTS] index_name;
+```
+
+注意：删除索引**不会立即释放存储空间**，后续新增数据不再构建该索引数据。
+
+---
+
+## SHOW INDEX（列出表的所有索引）
+
+```sql
+SHOW INDEX [IN|FROM] [schema.]table_name [LIMIT num];
+```
+
+示例：
+```sql
+SHOW INDEX FROM orders;
+SHOW INDEX FROM my_schema.orders;
+```
+
+---
+
+## DESC INDEX（查看索引详情）
+
+```sql
+DESC INDEX [EXTENDED] index_name;
+```
+
+- 基础模式：显示名称、创建时间、类型、所属表、列名
+- `EXTENDED`：额外显示索引大小（倒排索引支持，Bloom Filter 暂不支持）
+
+示例输出：
+```
++--------------------------+--------------------------+
+|        info_name         |        info_value        |
++--------------------------+--------------------------+
+| name                     | order_year_index         |
+| creator                  | my_user                  |
+| created_time             | 2024-12-27 10:51:58.977  |
+| index_type               | inverted                 |
+| table_name               | t                        |
+| table_column             | order_year               |
+| total_index_size         | 296                      |
++--------------------------+--------------------------+
+```

package/bin/skills/clickzetta-index-manager/references/inverted-index.md

@@ -0,0 +1,80 @@
+# 倒排索引参考
+
+> 来源：https://www.yunqi.tech/documents/create-inverted-index
+
+## 适用场景
+
+文本搜索、关键词匹配。支持数值、日期、字符串列。字符串列必须指定分词器。
+
+## 分词器选择
+
+| 分词器 | 适用场景 | 说明 |
+|---|---|---|
+| `keyword` | 精确匹配 | 不分词，整个字符串作为一个词根 |
+| `english` | 英文文本 | 识别连续 ASCII 字母和数字，转小写 |
+| `chinese` | 中英文混合 | 识别中文和英文，过滤标点，英文转小写 |
+| `unicode` | 多语言 | 基于 Unicode 文本分割算法，支持多语言 |
+
+数值和日期类型**不需要**指定 PROPERTIES。
+
+## 建表时创建
+
+```sql
+CREATE TABLE articles (
+    id INT,
+    title STRING,
+    content STRING,
+    INDEX id_idx (id) INVERTED,
+    INDEX title_idx (title) INVERTED PROPERTIES('analyzer'='chinese'),
+    INDEX content_idx (content) INVERTED PROPERTIES('analyzer'='english')
+);
+```
+
+## 已有表添加
+
+```sql
+CREATE INVERTED INDEX [IF NOT EXISTS] index_name
+ON TABLE [schema.]table_name(column_name)
+[COMMENT 'comment']
+[PROPERTIES('analyzer'='english|chinese|keyword|unicode')];
+```
+
+## 注意事项
+
+- **只对新写入数据生效**，旧数据需用 `BUILD INDEX` 命令补建
+- 只支持**单列索引**
+
+## 查询语法
+
+```sql
+-- 匹配任意词（OR）
+SELECT * FROM articles WHERE match_any(content, 'keyword1 keyword2');
+
+-- 匹配所有词（AND）
+SELECT * FROM articles WHERE match_all(content, 'keyword1 keyword2');
+```
+
+## 完整示例
+
+```sql
+-- 建表
+CREATE TABLE t (
+    order_id INT,
+    order_year STRING,
+    INDEX order_id_index (order_id) INVERTED COMMENT 'INVERTED'
+);
+
+-- 给已有列添加索引
+CREATE INVERTED INDEX order_year_index
+ON TABLE public.t(order_year)
+PROPERTIES('analyzer'='chinese');
+
+-- 对存量数据构建索引
+BUILD INDEX order_year_index ON public.t;
+
+-- 查询
+SELECT * FROM t WHERE match_all(order_year, '2023');
+
+-- 查看索引详情
+DESC INDEX EXTENDED order_year_index;
+```

package/bin/skills/clickzetta-index-manager/references/vector-index.md

@@ -0,0 +1,81 @@
+# 向量索引参考
+
+> 来源：https://www.yunqi.tech/documents/create-vector-index
+
+## 适用场景
+
+语义相似度搜索、RAG 检索、推荐系统。基于 HNSW 算法。
+
+## 建表时创建
+
+```sql
+CREATE TABLE embeddings (
+    id INT,
+    vec VECTOR(FLOAT, 512),
+    INDEX vec_idx (vec) USING VECTOR PROPERTIES(
+        "scalar.type" = "f32",
+        "distance.function" = "l2_distance"
+    )
+);
+```
+
+## 已有表添加
+
+```sql
+CREATE VECTOR INDEX [IF NOT EXISTS] index_name
+ON TABLE [schema.]table_name(column_name)
+PROPERTIES(
+    "property1" = "value1",
+    ...
+);
+```
+
+## PROPERTIES 参数说明
+
+| 参数 | 可选值 | 默认值 | 说明 |
+|---|---|---|---|
+| `distance.function` | `l2_distance`, `cosine_distance`, `jaccard_distance`, `hamming_distance` | `cosine_distance` | 距离函数 |
+| `scalar.type` | `f32`, `f16`, `i8`, `b1` | `f32` | 向量元素类型 |
+| `m` | 建议不超过 1000 | `16` | HNSW 最大邻居数 |
+| `ef.construction` | 建议不超过 5000 | `128` | HNSW 构建时候选集大小 |
+| `reuse.vector.column` | `true`, `false` | `false` | 复用 vector column 数据节省存储 |
+| `compress.codec` | `uncompressed`, `zstd`, `lz4` | `uncompressed` | 压缩算法（复用 column 时不生效） |
+| `compress.level` | `fastest`, `default`, `best` | `default` | 压缩级别 |
+
+## 向量列类型与索引元素类型对应
+
+| 索引元素类型（scalar.type） | 支持的向量列类型 |
+|---|---|
+| `f32` | int, float |
+| `f16` | int, float |
+| `i8` | tinyint, int, float |
+| `b1` | tinyint, int, float（按位建索引需设 `conversion.rule=as_bits`） |
+
+## 注意事项
+
+- **只对新写入数据生效**，旧数据需用 `BUILD INDEX` 命令补建
+
+## 完整示例
+
+```sql
+-- 建表时创建向量索引
+CREATE TABLE test_vector (
+    vec VECTOR(FLOAT, 4),
+    id INT,
+    INDEX vec_idx (vec) USING VECTOR PROPERTIES(
+        "scalar.type" = "f32",
+        "distance.function" = "l2_distance"
+    )
+);
+
+-- 已有表添加向量索引
+CREATE VECTOR INDEX vec_idx
+ON TABLE public.test_vector(vec)
+PROPERTIES(
+    "scalar.type" = "f32",
+    "distance.function" = "cosine_distance"
+);
+
+-- 对存量数据构建索引
+BUILD INDEX vec_idx ON public.test_vector;
+```

package/bin/skills/clickzetta-java-sdk/LICENSE

@@ -0,0 +1,16 @@
+ClickZetta Skills License
+© 2026 Yunqi Inc. All rights reserved.
+LICENSE: Use of these materials (including all code, prompts, assets, files, and other components of these skills (collectively, "Skills")) is governed by your agreement with ClickZetta for the Service. If no separate agreement exists, use is governed by ClickZetta's Terms of Service (available at: https://yunqi.tech/documents/user-aggrement).
+Your applicable agreement is referred to as the "Agreement." "Service" is as defined in the Agreement.
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the contrary, you may not:
+
+Extract from the Service or retain copies of the Skills outside use with the Service;
+Reproduce or copy the Skills, except for temporary copies created automatically during authorized use of the Service;
+Create derivative works based on the Skills;
+Distribute, sublicense, or transfer the Skills to any third party;
+Make, offer to sell, sell, or import any inventions embodied in the Skills; nor,
+Reverse engineer, decompile, or disassemble the Skills.
+
+The receipt, viewing, or possession of the Skills does not convey or imply any license or right beyond those expressly granted above.
+Yunqi retains all rights, title, and interest in the Skills, including all copyrights, trademarks, patents, and all other applicable intellectual property rights.
+THE SKILLS ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SKILLS OR THE USE OR OTHER DEALINGS IN THE SKILLS.