# البحث النصي الكامل FTS5

يستخدم Synapse امتداد FTS5 (Full-Text Search 5) للبحث السريع والمرن في الذاكرة.
تشرح هذه الصفحة كيف يعمل وكيفية استخدامه بفعالية.

## ما هو FTS5؟

FTS5 امتداد SQLite (متاح أيضًا في PostgreSQL عبر امتدادات) يُوفّر قدرات
البحث النصي الكامل. يقوم بـ:

- فهرسة المحتوى النصي للبحث السريع بالكلمات المفتاحية
- دعم المعاملات المنطقية (AND، OR، NOT)
- دعم مطابقة العبارات مع علامات الاقتباس
- دعم مطابقة البادئات مع `*`
- ترتيب النتائج حسب الصلة

يستخدم Synapse امتداد FTS5 لفهرسة جميع محتويات الذاكرة، مما يُمكّن البحث بزمن
أقل من مللي ثانية عبر آلاف الذكريات.

## كيف يستخدم Synapse FTS5

عند تنفيذ `POST /memory`:

1. يُخزَّن محتوى الذاكرة في جدول `memories`
2. يُدرج المحتوى أيضًا في الجدول الافتراضي FTS5
3. يقوم FTS5 تلقائيًا بتجزئة المحتوى وفهرسته

عند تنفيذ `GET /memory/search?q=...`:

1. يحلل Synapse الاستعلام باستخدام صياغة FTS5
2. ينفذ `MATCH` مقابل فهرس FTS5
3. يصفّي حسب `mind_id` (عزل المستأجر)
4. يُرجع النتائج مرتّبة

## صياغة الاستعلام

### بحث بالكلمات المفتاحية البسيطة

```
?q=docker
```

يُرجع الذكريات التي تحتوي على "docker".

### كلمات مفتاحية متعددة (AND ضمني)

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

يُرجع الذكريات التي تحتوي على "docker" AND "swarm" معًا.

### مطابقة العبارات

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

يُرجع الذكريات التي تحتوي على العبارة الدقيقة "docker swarm".

### مطابقة البادئات

```
?q=docker*
```

يُرجع الذكريات التي تحتوي على كلمات تبدأ بـ "docker" (مثل "dockers"،
"dockerfile"، "dockerize").

### OR المنطقية

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

يُرجع الذكريات التي تحتوي على "docker" OR "kubernetes".

### NOT المنطقية

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

يُرجع الذكريات التي تحتوي على "docker" وليس "swarm".

### التجميع

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

يُرجع الذكريات التي تحتوي على "docker" أو "kubernetes"، لكن ليس "test".

## أمثلة عملية

### البحث عن ذكريات حول مشروع

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

### البحث عن عبارة دقيقة

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

### استبعاد ذكريات الاختبار

```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. العوامل:

- تكرار المصطلح (كم مرة يظهر المصطلح)
- معكوس تكرار المستند (المصطلحات النادرة تُرتّب أعلى)
- طول المستند (المستندات الأقصر التي تحتوي على المصطلح تُرتّب أعلى)
- وزن العمود (العنوان > المحتوى)

تُرجع النتائج بترتيب الصلة (الأكثر صلة أولًا).

## الأداء

| العملية | زمن الاستجابة |
|-----------|---------|
| البحث في 100 ذاكرة | < 5 مللي ث |
| البحث في 1,000 ذاكرة | < 10 مللي ث |
| البحث في 10,000 ذاكرة | < 25 مللي ث |
| البحث في 100,000 ذاكرة | < 100 مللي ث |

FTS5 مُحسّن للغاية لأحمال العمل الكثيفة القراءة.

## القيود

### الاشتقاق

FTS5 لا يقوم بالاشتقاق افتراضيًا. "running" و "run" مصطلحان مختلفان.

**الحل البديل:** استخدم مطابقة البادئات: `?q=run*`

### التسامح مع الأخطاء المطبعية

FTS5 لا يدعم المطابقة الضبابية. خطأ مطبعي سيُرجع نتائج فارغة.

**الحل البديل:** استخدم البحث الدلالي (`/memory/semantic-search`) للمطابقة
المفاهيمية.

### كلمات الوقف

الكلمات الشائعة (the، a، an، is) مفهرسة لكن قد لا تكون مفيدة للبحث.
يتعامل FTS5 مع هذا تلقائيًا.

## FTS5 مقابل البحث الدلالي

| الجانب | FTS5 | البحث الدلالي |
|--------|------|-----------------|
| السرعة | أقل من مللي ثانية | 50-100 مللي ث |
| المطابقة | كلمات مفتاحية دقيقة | مفاهيمية |
| التسامح مع الأخطاء | لا شيء | بعض |
| الاشتقاق | لا شيء | ضمني |
| يتطلب تضمينات | لا | نعم |
| الأفضل لـ | مصطلحات محددة | المفاهيم |

استخدم FTS5 عندما تعرف الكلمات المفتاحية. استخدم البحث الدلالي عندما تريد
"ذكريات حول X" حيث يُوصف X بشكل مختلف.

## أفضل الممارسات

> [!TIP]
> - **استخدم مصطلحات محددة** — "docker swarm" أفضل من "container orchestration"
> - **اضبط العبارات بين علامات اقتباس** — `"docker swarm"` يضمن مطابقة العبارة
> - **استخدم البادئات للاختلافات** — `deploy*` يلتقط "deploy" و "deployment" و "deploying"
> - **استبعد الضوضاء** — `-test` يصفّي ذكريات الاختبار
> - **اجمع مع الوسوم** — `?q=docker&tag=production` يضيّق النتائج

## الخطوات التالية

- [البحث الدلالي](/docs/concepts/semantic-search)
- [Memory API](/docs/api/memory)
- [أفضل ممارسات الذاكرة](/docs/guides/memory-best-practices)