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 เกี่ยวกับโปรเจกต์

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

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

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

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

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

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

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 ถูกอธิบายต่างกัน

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

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

• Semantic Search
• Memory API
• Memory Best Practices