# FTS5 Full-Text Search

Synapse ใช้ FTS5 (Full-Text Search 5) สำหรับการค้นหา memory ที่รวดเร็วและยืดหยุ่น เอกสารหน้านี้อธิบายวิธีการทำงานและวิธีใช้อย่างมีประสิทธิภาพ

## FTS5 คืออะไร?

FTS5 เป็น SQLite extension (มีใน PostgreSQL ผ่าน extension ด้วย) ที่ให้ความสามารถ full-text search โดย:

- Index เนื้อหา text สำหรับ keyword search ที่รวดเร็ว
- รองรับ boolean operator (AND, OR, NOT)
- รองรับ phrase matching ด้วยเครื่องหมายคำพูด
- รองรับ prefix matching ด้วย `*`
- จัดอันดับผลลัพธ์ตามความเกี่ยวข้อง

Synapse ใช้ FTS5 ในการ index เนื้อหา memory ทั้งหมด เปิดใช้งานการค้นหาในระดับ sub-millisecond ทั่ว memory หลายพันรายการ

## วิธีที่ Synapse ใช้ FTS5

เมื่อคุณ `POST /memory`:

1. เนื้อหา memory ถูกเก็บในตาราง `memories`
2. เนื้อหายังถูกแทรกลงใน FTS5 virtual table
3. FTS5 แบ่งคำและ index เนื้อหาโดยอัตโนมัติ

เมื่อคุณ `GET /memory/search?q=...`:

1. Synapse แยกวิเคราะห์ query โดยใช้ไวยากรณ์ FTS5
2. ปฏิบัติการ `MATCH` กับ FTS5 index
3. กรองตาม `mind_id` (tenant isolation)
4. ส่งกลับผลลัพธ์ที่จัดอันดับแล้ว

## ไวยากรณ์ Query

### ค้นหา keyword แบบง่าย

```
?q=docker
```

ส่งกลับ memory ที่มี "docker"

### หลาย keyword (AND โดยนัย)

```
?q=docker+swarm
?q=docker%20swarm
```

ส่งกลับ memory ที่มีทั้ง "docker" และ "swarm"

### Phrase matching

```
?q="docker+swarm"
?q=%22docker%20swarm%22
```

ส่งกลับ memory ที่มี phrase "docker swarm" ตรงตัว

### Prefix matching

```
?q=docker*
```

ส่งกลับ memory ที่มีคำขึ้นต้นด้วย "docker" (เช่น "dockers", "dockerfile", "dockerize")

### Boolean OR

```
?q=docker+OR+kubernetes
```

ส่งกลับ memory ที่มี "docker" หรือ "kubernetes"

### Boolean NOT

```
?q=docker+-swarm
?q=docker+NOT+swarm
```

ส่งกลับ memory ที่มี "docker" แต่ไม่มี "swarm"

### การจัดกลุ่ม

```
?q=(docker+OR+kubernetes)+-test
```

ส่งกลับ memory ที่มี "docker" หรือ "kubernetes" แต่ไม่มี "test"

## ตัวอย่างปฏิบัติ

### ค้นหา memory เกี่ยวกับโปรเจกต์

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=synapse+deployment"
```

### ค้นหา phrase ตรงตัว

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22"
```

### แยก memory ทดสอบออก

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=production+-test"
```

### ค้นหาตามเทคโนโลยี

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql"
```

## การจัดอันดับ

FTS5 จัดอันดับผลลัพธ์ตามความเกี่ยวข้องโดยใช้อัลกอริทึม BM25 ปัจจัย:

- ความถี่ของคำ (term ปรากฏบ่อยแค่ไหน)
- Inverse document frequency (คำที่หายากอันดับสูงกว่า)
- ความยาวเอกสาร (เอกสารสั้นที่มีคำนั้นอันดับสูงกว่า)
- น้ำหนัก column (title > content)

ผลลัพธ์ส่งกลับตามลำดับอันดับ (เกี่ยวข้องที่สุดก่อน)

## ประสิทธิภาพ

| การดำเนินการ | Latency |
|-----------|---------|
| ค้นหา 100 memory | < 5ms |
| ค้นหา 1,000 memory | < 10ms |
| ค้นหา 10,000 memory | < 25ms |
| ค้นหา 100,000 memory | < 100ms |

FTS5 ถูกปรับให้เหมาะกับ workload ที่อ่านหนัก

## ข้อจำกัด

### Stemming

FTS5 ไม่ทำ stemming โดยค่าเริ่มต้น "running" และ "run" เป็นคำต่างกัน

**วิธีแก้:** ใช้ prefix matching: `?q=run*`

### ความทนต่อการพิมพ์ผิด

FTS5 ไม่รองรับ fuzzy matching พิมพ์ผิดจะไม่ส่งกลับผลลัพธ์

**วิธีแก้:** ใช้ semantic search (`/memory/semantic-search`) สำหรับการจับคู่เชิงแนวคิด

### Stop word

คำทั่วไป (the, a, an, is) ถูก index แต่อาจไม่มีประโยชน์ต่อการค้นหา FTS5 จัดการสิ่งนี้โดยอัตโนมัติ

## FTS5 vs Semantic Search

| แง่มุม | FTS5 | Semantic Search |
|--------|------|-----------------|
| ความเร็ว | Sub-millisecond | 50-100ms |
| การจับคู่ | Exact keyword | เชิงแนวคิด |
| ทนพิมพ์ผิด | None | บางส่วน |
| Stemming | None | โดยนัย |
| ต้องการ embedding | ไม่ | ใช่ |
| เหมาะกับ | คำเฉพาะ | แนวคิด |

ใช้ FTS5 เมื่อคุณรู้ keyword ใช้ semantic search เมื่อคุณต้องการ "memory เกี่ยวกับ X" โดยที่ X ถูกอธิบายต่างกัน

## แนวทางปฏิบัติที่ดีที่สุด

> [!TIP]
> - **ใช้คำที่เฉพาะเจาะจง** — "docker swarm" ดีกว่า "container orchestration"
> - **ใส่เครื่องหมายคำพูดรอบ phrase** — `"docker swarm"` รับประกัน phrase match
> - **ใช้ prefix สำหรับรูปแปร** — `deploy*` จับ "deploy", "deployment", "deploying"
> - **แยกสัญญาณรบกวน** — `-test` กรอง memory ทดสอบออก
> - **รวมกับ tag** — `?q=docker&tag=production` จำกัดผลลัพธ์

## ขั้นตอนถัดไป

- [Semantic Search](/docs/concepts/semantic-search)
- [Memory API](/docs/api/memory)
- [Memory Best Practices](/docs/guides/memory-best-practices)