# Полнотекстовый поиск 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. Факторы:

- Частота термина (как часто термин встречается)
- Обратная частота документа (более редкие термины ранжируются выше)
- Длина документа (более короткие документы с термином ранжируются выше)
- Вес колонки (заголовок > содержимое)

Результаты возвращаются в порядке ранжирования (наиболее релевантные — первыми).

## Производительность

| Операция | Задержка |
|-----------|---------|
| Поиск по 100 воспоминаниям | < 5 мс |
| Поиск по 1000 воспоминаний | < 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)