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

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