# Wyszukiwanie pełnotekstowe FTS5

Synapse używa FTS5 (Full-Text Search 5) do szybkiego i elastycznego wyszukiwania
wspomnień. Ta strona wyjaśnia, jak to działa i jak efektywnie tego używać.

## Czym jest FTS5?

FTS5 to rozszerzenie SQLite (dostępne również w PostgreSQL przez rozszerzenia),
które zapewnia możliwości wyszukiwania pełnotekstowego. Spełnia funkcje:

- Indeksuje treść tekstową pod kątem szybkiego wyszukiwania słów kluczowych
- Obsługuje operatory logiczne (AND, OR, NOT)
- Obsługuje dopasowywanie fraz z cudzysłowami
- Obsługuje dopasowywanie prefiksów z `*`
- Ranguje wyniki według trafności

Synapse używa FTS5 do indeksowania całej treści wspomnień, co umożliwia
wyszukiwanie poniżej milisekundy w tysiącach wspomnień.

## Jak Synapse używa FTS5

Gdy wykonywane jest `POST /memory`:

1. Treść wspomnienia jest zapisywana w tabeli `memories`
2. Treść jest również wstawiana do tabeli wirtualnej FTS5
3. FTS5 automatycznie tokenizuje i indeksuje treść

Gdy wykonywane jest `GET /memory/search?q=...`:

1. Synapse parsuje zapytanie składnią FTS5
2. Wykonuje `MATCH` wobec indeksu FTS5
3. Filtruje po `mind_id` (izolacja dzierżawcy)
4. Zwraca wyniki z rankingiem

## Składnia zapytania

### Proste wyszukiwanie słów kluczowych

```
?q=docker
```

Zwraca wspomnienia zawierające „docker".

### Wiele słów kluczowych (domyślnie AND)

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

Zwraca wspomnienia zawierające ZARÓWNO „docker", JAK i „swarm".

### Dopasowywanie fraz

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

Zwraca wspomnienia zawierające dokładną frazę „docker swarm".

### Dopasowywanie prefiksów

```
?q=docker*
```

Zwraca wspomnienia zawierające słowa zaczynające się od „docker" (np. „dockers",
„dockerfile", „dockerize").

### Operator logiczny OR

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

Zwraca wspomnienia zawierające „docker" LUB „kubernetes".

### Operator logiczny NOT

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

Zwraca wspomnienia zawierające „docker", ale NIE „swarm".

### Grupowanie

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

Zwraca wspomnienia zawierające „docker" lub „kubernetes", ale nie „test".

## Praktyczne przykłady

### Znajdowanie wspomnień o projekcie

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

### Znajdowanie dokładnej frazy

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

### Wykluczanie wspomnień testowych

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

### Wyszukiwanie po technologii

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

## Ranking

FTS5 ranguje wyniki pod kątem trafności algorytmem BM25. Czynniki:

- Częstotliwość terminu (jak często występuje)
- Odwrotna częstotliwość dokumentu (rzadsze terminy mają wyższy ranking)
- Długość dokumentu (krótsze dokumenty z terminem mają wyższy ranking)
- Waga kolumny (tytuł > treść)

Wyniki są zwracane w kolejności rangi (najbardziej trafne najpierw).

## Wydajność

| Operacja | Opóźnienie |
|-----------|---------|
| Wyszukiwanie 100 wspomnień | < 5 ms |
| Wyszukiwanie 1 000 wspomnień | < 10 ms |
| Wyszukiwanie 10 000 wspomnień | < 25 ms |
| Wyszukiwanie 100 000 wspomnień | < 100 ms |

FTS5 jest wysoce zoptymalizowany dla obciążeń odczytu.

## Ograniczenia

### Stemming

FTS5 domyślnie nie wykonuje stemmingu. „Running" i „run" to różne terminy.

**Obejście:** Użyć dopasowania prefiksu: `?q=run*`

### Tolerancja literówek

FTS5 nie obsługuje dopasowywania rozmytego. Literówka zwróci brak wyników.

**Obejście:** Użyć wyszukiwania semantycznego (`/memory/semantic-search`) do
dopasowywania koncepcyjnego.

### Słowa stop

Popularne słowa (the, a, an, is) są indeksowane, ale mogą nie być użyteczne w
wyszukiwaniu. FTS5 obsługuje to automatycznie.

## FTS5 a wyszukiwanie semantyczne

| Aspekt | FTS5 | Wyszukiwanie semantyczne |
|--------|------|-----------------|
| Prędkość | Poniżej milisekundy | 50-100 ms |
| Dopasowywanie | Dokładne słowa kluczowe | Koncepcyjne |
| Tolerancja literówek | Brak | Pewna |
| Stemming | Brak | Domniemany |
| Wymaga osadzeń | Nie | Tak |
| Najlepsze do | Konkretnych terminów | Koncepcji |

Należy używać FTS5, gdy znane są słowa kluczowe. Wyszukiwanie semantyczne należy
stosować, gdy potrzebne są „wspomnienia o X", gdzie X jest opisane inaczej.

## Najlepsze praktyki

> [!TIP]
> - **Używać konkretnych terminów** — „docker swarm" jest lepsze niż „container orchestration"
> - **Cytować frazy** — `"docker swarm"` zapewnia dopasowanie frazy
> - **Używać prefiksu dla wariantów** — `deploy*` wyłapuje „deploy", „deployment", „deploying"
> - **Wykluczać szum** — `-test` odfiltrowuje wspomnienia testowe
> - **Łączyć z tagami** — `?q=docker&tag=production` zawęża wyniki

## Następne kroki

- [Wyszukiwanie semantyczne](/docs/concepts/semantic-search)
- [Memory API](/docs/api/memory)
- [Najlepsze praktyki pamięci](/docs/guides/memory-best-practices)