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

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-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;
+```