# Повнотекстовий пошук 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» та «swarm».

### Пошук фраз

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

Повертає спогади, що містять точну фразу «docker swarm».

### Пошук за префіксом

```
?q=docker*
```

Повертає спогади зі словами, що починаються на «docker» (напр. «dockers»,
«dockerfile», «dockerize»).

### Булеве OR

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

Повертає спогади, що містять «docker» АБО «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. Фактори:

- Частота терміна (як часто термін зустрічається)
- Зворотна частота документа (рідкісні терміни ранжуються вище)
- Довжина документа (коротші документи з терміном ранжуються вище)
- Вага колонки (title > content)

Результати повертаються в порядку ранжування (найрелевантніші першими).

## Продуктивність

| Операція | Затримка |
|-----------|---------|
| Пошук у 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)