# FTS5 volledige-tekst zoekopdracht

Synapse gebruikt FTS5 (Full-Text Search 5) voor snelle, flexibele memory-zoekopdrachten.
Deze pagina legt uit hoe het werkt en hoe u het effectief kunt gebruiken.

## Wat is FTS5?

FTS5 is een SQLite-extensie (ook beschikbaar in PostgreSQL via extensies) die
volledige-tekst zoekmogelijkheden biedt. Het:

- Indexeert tekstinhoud voor snelle trefwoordzoekopdrachten
- Ondersteunt booleaanse operatoren (AND, OR, NOT)
- Ondersteunt overeenkomsten met zinnen via aanhalingstekens
- Ondersteunt prefix-overeenkomsten met `*`
- Rangschikt resultaten op relevantie

Synapse gebruikt FTS5 om alle memory-inhoud te indexeren, waardoor sub-milliseconde
zoekopdrachten mogelijk zijn over duizenden herinneringen.

## Hoe Synapse FTS5 gebruikt

Wanneer u `POST /memory` uitvoert:

1. Memory-inhoud wordt opgeslagen in de `memories`-tabel
2. Inhoud wordt ook ingevoegd in de FTS5 virtuele tabel
3. FTS5 tokenizeert en indexeert de inhoud automatisch

Wanneer u `GET /memory/search?q=...` uitvoert:

1. Synapse parseert de query met FTS5-syntaxis
2. Voert een `MATCH` uit tegen de FTS5-index
3. Filtert op `mind_id` (tenant-isolatie)
4. Retourneert gerangschikte resultaten

## Query-syntaxis

### Eenvoudige trefwoordzoekopdracht

```
?q=docker
```

Retourneert herinneringen die "docker" bevatten.

### Meerdere trefwoorden (impliciete AND)

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

Retourneert herinneringen die ZOWEL "docker" ALS "swarm" bevatten.

### Zin-overeenkomst

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

Retourneert herinneringen die de exacte zin "docker swarm" bevatten.

### Prefix-overeenkomst

```
?q=docker*
```

Retourneert herinneringen die woorden bevatten die beginnen met "docker" (bijv. "dockers",
"dockerfile", "dockerize").

### Booleaans OR

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

Retourneert herinneringen die "docker" OF "kubernetes" bevatten.

### Booleaans NOT

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

Retourneert herinneringen die "docker" bevatten maar NIET "swarm".

### Groepering

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

Retourneert herinneringen die "docker" of "kubernetes" bevatten, maar niet "test".

## Praktische voorbeelden

### Vind herinneringen over een project

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

### Vind exacte zin

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

### Sluit test-herinneringen uit

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

### Vind op technologie

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

## Rangschikking

FTS5 rangschikt resultaten op relevantie met behulp van het BM25-algoritme. Factoren:

- Termfrequentie (hoe vaak de term voorkomt)
- Inverse documentfrequentie (zeldzame termen ranken hoger)
- Documentlengte (kortere docs met de term ranken hoger)
- Kolomgewicht (title > content)

Resultaten worden geretourneerd in rangschikkingsvolgorde (meest relevant eerst).

## Prestaties

| Bewerking | Latentie |
|-----------|----------|
| 100 herinneringen doorzoeken | < 5ms |
| 1.000 herinneringen doorzoeken | < 10ms |
| 10.000 herinneringen doorzoeken | < 25ms |
| 100.000 herinneringen doorzoeken | < 100ms |

FTS5 is sterk geoptimaliseerd voor lees-intensieve workloads.

## Beperkingen

### Stamvorming

FTS5 doet standaard geen stamvorming. "running" en "run" zijn verschillende termen.

**Tijdelijke oplossing:** Gebruik prefix-overeenkomst: `?q=run*`

### Typefout-tolerantie

FTS5 ondersteunt geen fuzzy matching. Een typefout levert geen resultaten op.

**Tijdelijke oplossing:** Gebruik semantisch zoeken (`/memory/semantic-search`) voor
conceptuele overeenkomsten.

### Stopwoorden

Veelvoorkomende woorden (the, a, an, is) worden geïndexeerd maar zijn mogelijk niet
nuttig voor zoekopdrachten. FTS5 handelt dit automatisch af.

## FTS5 versus semantisch zoeken

| Aspect | FTS5 | Semantisch zoeken |
|--------|------|-------------------|
| Snelheid | Sub-milliseconde | 50-100ms |
| Matching | Exacte trefwoorden | Conceptueel |
| Typefout-tolerantie | Geen | Enigszins |
| Stamvorming | Geen | Impliciet |
| Vereist embeddings | Nee | Ja |
| Geschikt voor | Specifieke termen | Concepten |

Gebruik FTS5 als u de trefwoorden kent. Gebruik semantisch zoeken als u
"herinneringen over X" wilt waarbij X anders wordt omschreven.

## Best practices

> [!TIP]
> - **Gebruik specifieke termen** — "docker swarm" is beter dan "container orchestration"
> - **Gebruik aanhalingstekens voor zinnen** — `"docker swarm"` garandeert zinsovereenkomst
> - **Gebruik prefix voor variaties** — `deploy*` vangt "deploy", "deployment", "deploying"
> - **Sluit ruis uit** — `-test` filtert test-herinneringen weg
> - **Combineer met tags** — `?q=docker&tag=production` verfijnt resultaten

## Volgende stappen

- [Semantisch zoeken](/docs/concepts/semantic-search)
- [Memory API](/docs/api/memory)
- [Memory-best-practices](/docs/guides/memory-best-practices)