@clickzetta/cz-cli-darwin-arm64 0.3.17 → 0.3.19

package/bin/skills/clickzetta-external-function/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: clickzetta-external-function
+description: |
+  在 ClickZetta Lakehouse 中创建和使用外部函数（External Function / UDF），
+  通过 Python 或 Java 扩展 SQL 计算能力，调用 LLM、图像识别、自定义算法等外部服务。
+  覆盖 CREATE API CONNECTION（阿里云FC/腾讯云SCF/AWS Lambda）、
+  CREATE EXTERNAL FUNCTION、Python UDF 代码结构与打包、
+  内置 AI_COMPLETE 和 AI_EMBEDDING 函数的使用。
+  当用户说"外部函数"、"UDF"、"自定义函数"、"External Function"、
+  "Remote Function"、"调用 LLM"、"AI_COMPLETE"、"AI_EMBEDDING"、
+  "文本向量化"、"调用阿里云函数计算"、"调用云函数"、"Python UDF"、
+  "Java UDF"、"CREATE EXTERNAL FUNCTION"时触发。
+  Keywords: external function, UDF, Python UDF, Java UDF, LLM, custom function
+---
+
+# ClickZetta External Function
+
+External Function 让 SQL 可以调用外部计算能力（LLM、图像识别、自定义算法），通过 Python/Java 编写函数逻辑，部署在云函数服务上执行。
+
+阅读 [references/external-function-ddl.md](references/external-function-ddl.md) 了解完整语法。
+
+---
+
+## 两种使用路径
+
+| 路径 | 适用场景 | 复杂度 |
+|---|---|---|
+| **内置 AI 函数**（AI_COMPLETE / AI_EMBEDDING） | 调用 LLM 生成文本、文本向量化 | 低，只需创建 API Connection |
+| **External Function** | 自定义算法、图像处理、私有模型 | 高，需部署云函数 |
+
+---
+
+## 路径一：内置 AI 函数（推荐）
+
+### 1. 创建 AI API Connection
+
+```sql
+CREATE API CONNECTION conn_bailian
+    TYPE ai_function
+    PROVIDER = 'bailian'
+    BASE_URL = 'https://dashscope.aliyuncs.com/api/v1'
+    API_KEY = '<key>';
+```
+
+### 2. AI_COMPLETE — 调用 LLM
+
+```sql
+-- 文本摘要
+SELECT id,
+       AI_COMPLETE('connection:conn_bailian', '请用一句话总结：' || content) AS summary
+FROM articles;
+
+-- 情感分析
+SELECT id, review,
+       AI_COMPLETE('connection:conn_bailian',
+           '判断以下评论的情感（正面/负面/中性），只返回一个词：' || review) AS sentiment
+FROM user_reviews;
+
+-- 通过平台 Endpoint（管理员预配置）
+SELECT AI_COMPLETE('endpoint:my_llm_endpoint', prompt_col) AS result
+FROM my_table;
+```
+
+### 3. AI_EMBEDDING — 文本向量化
+
+```sql
+-- 批量生成 embedding
+SELECT id, content,
+       AI_EMBEDDING('connection:conn_bailian', content) AS vec
+FROM documents;
+
+-- 语义搜索（结合向量索引）
+SELECT id, content,
+       cosine_distance(vec, AI_EMBEDDING('connection:conn_bailian', '用户查询')) AS dist
+FROM doc_embeddings
+ORDER BY dist
+LIMIT 10;
+```
+
+---
+
+## 路径二：External Function（自定义 UDF）
+
+### 整体流程
+
+```
+1. 开通云函数服务（阿里云FC / 腾讯云SCF / AWS Lambda）
+2. 编写 Python/Java 函数代码
+3. 打包上传到对象存储或 User Volume
+4. 授权 Lakehouse 访问云函数服务（RAM 角色）
+5. CREATE API CONNECTION
+6. CREATE EXTERNAL FUNCTION
+7. 在 SQL 中调用
+```
+
+### 步骤 1：创建云函数 API Connection
+
+```sql
+-- 阿里云 FC
+CREATE API CONNECTION IF NOT EXISTS my_fc_conn
+  TYPE CLOUD_FUNCTION
+  PROVIDER = 'aliyun'
+  REGION = 'cn-shanghai'
+  ROLE_ARN = 'acs:ram::1234567890:role/CzUDFRole'
+  NAMESPACE = 'default'
+  CODE_BUCKET = 'my-oss-bucket';
+
+-- 腾讯云 SCF
+CREATE API CONNECTION IF NOT EXISTS my_scf_conn
+  TYPE CLOUD_FUNCTION
+  PROVIDER = 'tencent'
+  REGION = 'ap-shanghai'
+  ROLE_ARN = 'qcs::cam::uin/1234567890:roleName/CzUDFRole'
+  NAMESPACE = 'default'
+  CODE_BUCKET = 'my-cos-bucket';
+```
+
+### 步骤 2：编写 Python UDF
+
+```python
+# upper.py
+try:
+    from cz.udf import annotate
+except ImportError:
+    annotate = lambda _: lambda _: _
+
+@annotate("string->string")
+class Upper(object):
+    def evaluate(self, arg):
+        if arg is None:
+            return None
+        return arg.upper()
+```
+
+打包上传：
+```bash
+zip -rq upper.zip upper.py
+```
+
+```sql
+-- 上传到 User Volume（在 ClickZetta Studio 或 CLI 中执行，source_path 使用绝对路径）
+PUT '/path/to/upper.zip' TO USER VOLUME;
+```
+
+### 步骤 3：创建 External Function
+
+```sql
+-- ⚠️ CREATE EXTERNAL FUNCTION 不支持 OR REPLACE，只支持 IF NOT EXISTS
+-- ❌ 错误：CREATE OR REPLACE EXTERNAL FUNCTION ...
+-- ✅ 正确：
+-- 使用 User Volume 存放代码（无需 OSS）
+CREATE EXTERNAL FUNCTION IF NOT EXISTS public.str_upper
+  AS 'upper.Upper'
+  USING FILE = 'volume:user://~/upper.zip'
+  CONNECTION = my_fc_conn
+  WITH PROPERTIES ('remote.udf.api' = 'python3.mc.v0')
+  COMMENT '字符串转大写';
+
+-- 使用 OSS 存放代码
+CREATE EXTERNAL FUNCTION IF NOT EXISTS public.str_upper
+  AS 'upper.Upper'
+  USING FILE = 'oss://my-bucket/functions/upper.zip'
+  CONNECTION = my_fc_conn
+  WITH PROPERTIES ('remote.udf.api' = 'python3.mc.v0');
+```
+
+### 步骤 4：调用函数
+
+```sql
+-- ⚠️ 调用外部函数必须使用完整 Schema 路径，不能省略 schema
+-- ❌ 错误：SELECT str_upper(name) FROM my_table;
+-- ✅ 正确：
+SELECT id, public.str_upper(name) AS upper_name FROM my_table;
+```
+
+---
+
+## 管理操作
+
+```sql
+-- 查看所有外部函数
+SHOW EXTERNAL FUNCTIONS;
+SHOW EXTERNAL FUNCTIONS LIKE 'str_%';
+
+-- 删除函数（注意：用 DROP FUNCTION，不是 DROP EXTERNAL FUNCTION）
+DROP FUNCTION IF EXISTS public.str_upper;
+```
+
+> ⚠️ **注意**：`CREATE FUNCTION`（SQL 内联函数）只支持 SQL 表达式，不支持 Python/JavaScript 等编程语言。需要编程语言逻辑请使用 `CREATE EXTERNAL FUNCTION`。
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 函数调用超时 | 云函数冷启动或执行慢 | 增大超时配置，或预热函数 |
+| 依赖库 ABI 不兼容 | 在 macOS/Windows 打包 | 用 `quay.io/pypa/manylinux2014_x86_64` 容器打包 |
+| 代码包 > 500MB | 依赖过大 | 改用容器镜像方式部署 |
+| AI_COMPLETE 报错 | API Key 无效或余额不足 | 检查 API Connection 的 API_KEY |
+| ROLE_ARN 权限不足 | RAM 角色未授权 | 参考文档配置 AliyunFCFullAccess + OSS 权限 |
+| 函数调用报"not found" | 省略了 Schema 前缀 | 必须用完整路径：`schema.function_name(...)` |
+| CREATE OR REPLACE 报错 | EXTERNAL FUNCTION 不支持 OR REPLACE | 改用 `CREATE EXTERNAL FUNCTION IF NOT EXISTS` |

package/bin/skills/clickzetta-external-function/eval_cases.jsonl

@@ -0,0 +1,4 @@
+{"case_id":"001","type":"should_call","user_input":"怎么创建一个调用 LLM 的外部函数？需要哪些步骤？","expected_skill":"clickzetta-external-function","expected_output_contains":["API CONNECTION","EXTERNAL FUNCTION"]}
+{"case_id":"002","type":"should_call","user_input":"AI_COMPLETE 和 AI_EMBEDDING 内置函数怎么用？","expected_skill":"clickzetta-external-function","expected_output_contains":["AI_COMPLETE","AI_EMBEDDING"]}
+{"case_id":"003","type":"should_call","user_input":"Python UDF 的代码结构和打包方式是什么？","expected_skill":"clickzetta-external-function","expected_output_contains":["Python","def"]}
+{"case_id":"004","type":"should_call","user_input":"怎么创建 API CONNECTION 连接阿里云函数计算？","expected_skill":"clickzetta-external-function","expected_output_contains":["API CONNECTION"]}

package/bin/skills/clickzetta-external-function/references/external-function-ddl.md

@@ -0,0 +1,171 @@
+# External Function DDL 参考
+
+> 来源：https://www.yunqi.tech/documents/CREATE_EXTERNATL_FUNCTION 等
+
+## 概念
+
+External Function（外部函数）是通过 Python/Java 编写、在云函数服务（阿里云 FC / 腾讯云 SCF / AWS Lambda）上执行的自定义 UDF。可调用：
+- **在线服务**：LLM API、图像识别 API 等
+- **离线模型**：打包上传的 Hugging Face 模型等
+
+支持函数类型：UDF（标量）、UDAF（聚合，仅 Java）、UDTF（表函数，仅 Java）
+
+---
+
+## CREATE API CONNECTION（云函数连接）
+
+```sql
+CREATE API CONNECTION IF NOT EXISTS my_fc_conn
+  TYPE CLOUD_FUNCTION
+  PROVIDER = 'aliyun'           -- 'aliyun' | 'tencent' | 'aws'
+  REGION = 'cn-shanghai'
+  ROLE_ARN = 'acs:ram::1234567890:role/CzUDFRole'
+  NAMESPACE = 'default'         -- 腾讯云必填，其他填 'default'
+  CODE_BUCKET = 'my-oss-bucket';
+```
+
+| 参数 | 说明 |
+|---|---|
+| PROVIDER | `'aliyun'` / `'tencent'` / `'aws'` |
+| REGION | 阿里云：`cn-shanghai`；腾讯云：`ap-beijing`；AWS：`cn-northwest-1` |
+| ROLE_ARN | 授权给 Lakehouse 的 RAM 角色 ARN |
+| NAMESPACE | 腾讯云命名空间（必填）；其他填 `'default'` |
+| CODE_BUCKET | 存放函数代码包的 OSS/COS/S3 bucket 名称 |
+
+---
+
+## CREATE EXTERNAL FUNCTION
+
+```sql
+CREATE EXTERNAL FUNCTION IF NOT EXISTS my_schema.my_udf
+  AS 'module_name.ClassName'
+  USING FILE = 'oss://my-bucket/functions/code.zip'
+  CONNECTION = my_fc_conn
+  WITH PROPERTIES (
+      'remote.udf.api' = 'python3.mc.v0'   -- Python: python3.mc.v0 | Java: java8.hive2.v0
+  )
+  COMMENT '自定义函数说明';
+```
+
+### 资源文件地址格式
+
+```
+-- OSS/COS/S3
+oss://bucket-name/path/to/code.zip
+cos://bucket-name/path/to/code.zip
+s3://bucket-name/path/to/code.zip
+
+-- User Volume（无需开通对象存储）
+volume:user://~/code.zip
+
+-- External Volume
+volume://workspace.schema.volume_name/code.zip
+```
+
+### WITH PROPERTIES 参数
+
+| 参数 | 值 | 说明 |
+|---|---|---|
+| `remote.udf.api` | `python3.mc.v0` | Python 3.10 运行时 |
+| `remote.udf.api` | `java8.hive2.v0` | Java 8 Hive 风格 UDF |
+| `remote.udf.protocol` | `http.arrow.v0` | 默认，访问云函数的协议 |
+
+---
+
+## Python UDF 代码结构
+
+```python
+#!/usr/bin/env python
+try:
+    from cz.udf import annotate
+except ImportError:
+    annotate = lambda _: lambda _: _
+
+@annotate("string->string")   # 函数签名：输入类型->返回类型
+class Upper(object):
+    def evaluate(self, arg):
+        if arg is None:
+            return None
+        return arg.upper()
+```
+
+### 函数签名格式
+
+```
+"input_type1,input_type2->return_type"
+
+# 示例
+"string->string"           # 字符串转字符串
+"string,int->double"       # 两个输入，返回 double
+"string->array<string>"    # 返回数组
+```
+
+支持类型：`string`、`int`、`bigint`、`double`、`float`、`boolean`、`array<T>`、`map<K,V>`
+
+### 打包上传
+
+```bash
+# 安装依赖到当前目录
+pip3 install httpx pydantic -t .
+
+# 打包（< 500MB）
+zip -rq code.zip ./*
+```
+
+```sql
+-- 上传到 User Volume（在 ClickZetta Studio 或 CLI 中执行，source_path 使用绝对路径）
+PUT '/path/to/code.zip' TO USER VOLUME;
+```
+
+---
+
+## 管理操作
+
+```sql
+-- 查看外部函数列表
+SHOW EXTERNAL FUNCTIONS;
+SHOW EXTERNAL FUNCTIONS LIKE 'my_%';
+
+-- 删除外部函数
+DROP FUNCTION IF EXISTS my_schema.my_udf;
+```
+
+---
+
+## 内置 AI 函数（无需部署云函数）
+
+### AI_COMPLETE（调用 LLM）
+
+```sql
+-- 通过 API Connection 调用（需先创建连接）
+CREATE API CONNECTION conn_bailian
+    TYPE ai_function
+    PROVIDER = 'bailian'
+    BASE_URL = 'https://dashscope.aliyuncs.com/api/v1'
+    API_KEY = '<key>';
+
+-- 调用 LLM 生成文本
+SELECT AI_COMPLETE('connection:conn_bailian', '请用一句话总结：' || content) AS summary
+FROM articles
+LIMIT 10;
+
+-- 通过平台 Endpoint 调用（管理员预配置）
+SELECT AI_COMPLETE('endpoint:my_llm_endpoint', prompt_col) AS result
+FROM my_table;
+```
+
+### AI_EMBEDDING（文本向量化）
+
+```sql
+-- 将文本转为向量（用于语义搜索）
+SELECT id, content,
+       AI_EMBEDDING('connection:conn_bailian', content) AS embedding
+FROM documents;
+
+-- 结合向量索引做语义搜索
+SELECT id, content,
+       cosine_distance(embedding, AI_EMBEDDING('connection:conn_bailian', '查询文本')) AS dist
+FROM doc_embeddings
+ORDER BY dist
+LIMIT 10;
+```

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

@@ -0,0 +1,156 @@
+---
+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/文件数据导入工作流
+
+## 指令
+
+### 步骤 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-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"]}