@clickzetta/cz-cli-linux-x64 0.3.0 → 0.3.1

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