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

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

@@ -1,140 +0,0 @@
----
-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

@@ -1,67 +0,0 @@
-# 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

@@ -1,73 +0,0 @@
-# 索引管理命令参考
-
-> 来源：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

@@ -1,80 +0,0 @@
-# 倒排索引参考
-
-> 来源：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

@@ -1,81 +0,0 @@
-# 向量索引参考
-
-> 来源：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;
-```