sql5 4.1.0

# v4.0 - 向量資料庫 (Vector Search)

## 日期：2026-05-14

## 概述

本版本為 sql5 引入向量搜尋功能，支援近似最近鄰（ANN）查詢。參考 `sqlite-vec` API 設計，實現向量儲存、檢索、距離計算等功能。

---

## 主要功能

### 1. vec0 虛擬表

建立向量儲存的虛擬表結構：

```sql
CREATE VIRTUAL TABLE vec_items USING vec0(
  embedding float[768],      -- 向量欄位，維度需指定
  id integer primary key,   -- 主鍵
  name text,                 -- 元資料欄位
  +description text          -- 輔助欄位（前綴 +）
);
```

**欄位類型**：
- `float[N]` - N 維浮點向量（4 bytes/element）
- `int8[N]` - N 維 int8 向量
- `bit[N]` - N 維二值向量
- `integer partition key` - 分區鍵（用於分片查詢）
- `text` / `integer` / `float` - 元資料欄位
- `+column_name type` - 輔助欄位（不建立索引）

### 2. 向量插入

```sql
-- JSON 格式（自動偵測類型）
INSERT INTO vec_items(rowid, embedding) VALUES (1, '[1.0, 2.0, 3.0]');
INSERT INTO vec_items(rowid, embedding) VALUES (2, '[1, 2, 3]');  -- int8
```

### 3. KNN 查詢

```sql
SELECT rowid, distance
FROM vec_items
WHERE embedding MATCH '[0.1, 0.2, 0.3, ...]'
LIMIT 10;
```

### 4. 距離函數

| 函數 | 描述 | 支援類型 |
|------|------|----------|
| `vec_distance_L2(a, b)` | 歐氏距離 | float32, int8 |
| `vec_distance_cosine(a, b)` | 餘弦距離 | float32, int8 |
| `vec_distance_hamming(a, b)` | 漢明距離 | bit |

### 5. 向量操作函數

| 函數 | 描述 |
|------|------|
| `vec_f32(vector)` | 建立 float32 向量 |
| `vec_int8(vector)` | 建立 int8 向量 |
| `vec_bit(vector)` | 建立 bit 向量 |
| `vec_length(vector)` | 回傳向量維度 |
| `vec_type(vector)` | 回傳向量類型 |
| `vec_normalize(vector)` | L2 正規化 |
| `vec_to_json(vector)` | 轉為 JSON |
| `vec_quantize_binary(vector)` | 二值化量化 |

---

## 實作架構

### 模組結構

```
src/vector/
├── mod.rs              # 模組入口
├── vec_table.rs        # vec0 虛擬表實作
├── vector.rs           # 向量資料結構
├── distance.rs        # 距離計算（L2, cosine, hamming）
└── functions.rs       # SQL 函數
```

### 向量儲存格式

```rust
enum VectorType {
    Float32(Vec<f32>),
    Int8(Vec<i8>),
    Bit(Vec<u8>),
}
```

---

## SQL 相容性

| sqlite-vec | sql5 v4.0 | 狀態 |
|------------|-----------|------|
| `vec0` virtual table | `vec0` virtual table | ✅ |
| `vec_f32()` | `vec_f32()` | ✅ |
| `vec_to_json()` | `vec_to_json()` | ✅ |
| `vec_length()` | `vec_length()` | ✅ |
| `vec_distance_L2()` | `vec_distance_L2()` | ✅ |
| `vec_distance_cosine()` | `vec_distance_cosine()` | ✅ |
| `vec_normalize()` | `vec_normalize()` | ✅ |
| `vec_quantize_binary()` | `vec_quantize_binary()` | ✅ |
| KNN with `match` | KNN with `match` | ✅ |
| Metadata columns | Metadata columns | ✅ |
| Partition keys | Partition keys | ✅ |
| Auxiliary columns | Auxiliary columns | ✅ |

---

## 使用範例

### REPL 模式

```bash
sql5> CREATE VIRTUAL TABLE items USING vec0(embedding float[3]);
result                    
--------------------------
vec0 virtual table created

sql5> INSERT INTO items(rowid, embedding) VALUES (1, '[1,2,3]');
result           
-----------------
1 row(s) inserted

sql5> SELECT rowid, distance FROM items WHERE embedding MATCH '[1,2,3]' LIMIT 5;
rowid | distance
------+---------
1     | 0       
```

### Server 模式

```bash
# 啟動伺服器
sql5 --server my.db

# JSON 請求
{"method":"execute","sql":"CREATE VIRTUAL TABLE items USING vec0(embedding float[3])"}
{"method":"execute","sql":"INSERT INTO items(rowid, embedding) VALUES (1, '[1,2,3]')"}
{"method":"execute","sql":"SELECT rowid, distance FROM items WHERE embedding MATCH '[1,2,3]'"}
```

### WebSocket 模式

```bash
# 啟動 WebSocket 伺服器
sql5 --websocket 8080 my.db
```

---

## 測試結果

```
[PASS] Rust unit tests (cargo test)      — 379 passed
[PASS] CLI integration tests (shtest.sh) — 114 passed
[PASS] Python pytest tests               — 48 passed, 5 skipped
[PASS] Python client test (subprocess)     — PASSED
[PASS] WebSocket test (v3.0)               — PASSED
```

---

## 已知限制

1. **維度限制** - 初期支援最大 4096 維
2. **索引類型** - 初期僅支援平坦搜尋
3. **量化** - 初期不支援 int8 量化

---

## 修訂歷史

- 2026-05-14：v4.0 初始版本（向量資料庫功能）