{"title":"Ricerca full-text FTS5","slug":"fts5-search","category":"concepts","summary":"Come Synapse usa SQLite FTS5 per la ricerca full-text delle memorie sub-millisecond.","audience":["human","llm"],"tags":["concept","search","fts5","fulltext"],"difficulty":"advanced","updated":"2026-06-27","word_count":634,"read_minutes":3,"lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Ricerca full-text FTS5\n\nSynapse usa FTS5 (Full-Text Search 5) per la ricerca nelle memorie veloce e\nflessibile. Questa pagina spiega come funziona e come usarlo efficacemente.\n\n## Cos'è FTS5?\n\nFTS5 è un'estensione SQLite (disponibile anche in PostgreSQL tramite estensioni)\nche fornisce funzionalità di ricerca full-text. Essa:\n\n- Indicizza il contenuto testuale per la ricerca veloce per parola chiave\n- Supporta operatori booleani (AND, OR, NOT)\n- Supporta la corrispondenza di frasi con virgolette\n- Supporta la corrispondenza di prefisso con `*`\n- Classifica i risultati per rilevanza\n\nSynapse usa FTS5 per indicizzare tutti i contenuti delle memorie, abilitando\nricerca sub-millisecond su migliaia di memorie.\n\n## Come Synapse usa FTS5\n\nQuando fa `POST /memory`:\n\n1. Il contenuto della memoria viene salvato nella tabella `memories`\n2. Il contenuto viene anche inserito nella tabella virtuale FTS5\n3. FTS5 tokenizza e indicizza automaticamente il contenuto\n\nQuando fa `GET /memory/search?q=...`:\n\n1. Synapse analizza la query usando la sintassi FTS5\n2. Esegue un `MATCH` contro l'indice FTS5\n3. Filtra per `mind_id` (isolamento tenant)\n4. Restituisce i risultati classificati\n\n## Sintassi delle query\n\n### Ricerca semplice per parola chiave\n\n```\n?q=docker\n```\n\nRestituisce le memorie che contengono \"docker\".\n\n### Più parole chiave (AND implicito)\n\n```\n?q=docker+swarm\n?q=docker%20swarm\n```\n\nRestituisce le memorie che contengono SIA \"docker\" E \"swarm\".\n\n### Corrispondenza di frase\n\n```\n?q=\"docker+swarm\"\n?q=%22docker%20swarm%22\n```\n\nRestituisce le memorie che contengono la frase esatta \"docker swarm\".\n\n### Corrispondenza di prefisso\n\n```\n?q=docker*\n```\n\nRestituisce le memorie che contengono parole che iniziano con \"docker\" (es.\n\"dockers\", \"dockerfile\", \"dockerize\").\n\n### OR booleano\n\n```\n?q=docker+OR+kubernetes\n```\n\nRestituisce le memorie che contengono \"docker\" OR \"kubernetes\".\n\n### NOT booleano\n\n```\n?q=docker+-swarm\n?q=docker+NOT+swarm\n```\n\nRestituisce le memorie che contengono \"docker\" ma NON \"swarm\".\n\n### Raggruppamento\n\n```\n?q=(docker+OR+kubernetes)+-test\n```\n\nRestituisce le memorie che contengono \"docker\" o \"kubernetes\", ma non \"test\".\n\n## Esempi pratici\n\n### Trova memorie su un progetto\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n     \"https://synapse.schaefer.zone/memory/search?q=synapse+deployment\"\n```\n\n### Trova frase esatta\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n     \"https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22\"\n```\n\n### Escludi memorie di test\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n     \"https://synapse.schaefer.zone/memory/search?q=production+-test\"\n```\n\n### Trova per tecnologia\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n     \"https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql\"\n```\n\n## Classificazione\n\nFTS5 classifica i risultati per rilevanza usando l'algoritmo BM25. Fattori:\n\n- Frequenza del termine (quanto spesso appare il termine)\n- Inverse document frequency (termini più rari ottengono classifiche più alte)\n- Lunghezza del documento (documenti più corti con il termine ottengono classifica più alta)\n- Peso della colonna (title > content)\n\nI risultati vengono restituiti in ordine di classifica (più rilevanti per primi).\n\n## Prestazioni\n\n| Operazione | Latenza |\n|-----------|---------|\n| Ricerca su 100 memorie | < 5ms |\n| Ricerca su 1.000 memorie | < 10ms |\n| Ricerca su 10.000 memorie | < 25ms |\n| Ricerca su 100.000 memorie | < 100ms |\n\nFTS5 è altamente ottimizzato per workload con molti read.\n\n## Limitazioni\n\n### Stemming\n\nFTS5 non fa stemming per default. \"running\" e \"run\" sono termini diversi.\n\n**Soluzione:** Usi la corrispondenza di prefisso: `?q=run*`\n\n### Tolleranza ai refusi\n\nFTS5 non supporta il fuzzy matching. Un refuso non restituirà risultati.\n\n**Soluzione:** Usi la ricerca semantica (`/memory/semantic-search`) per\ncorrispondenza concettuale.\n\n### Stop word\n\nLe parole comuni (the, a, an, is) vengono indicizzate ma potrebbero non essere\nutili per la ricerca. FTS5 le gestisce automaticamente.\n\n## FTS5 vs ricerca semantica\n\n| Aspetto | FTS5 | Ricerca semantica |\n|--------|------|-----------------|\n| Velocità | Sub-millisecond | 50-100ms |\n| Corrispondenza | Parole chiave esatte | Concettuale |\n| Tolleranza ai refusi | Nessuna | Qualcuna |\n| Stemming | Nessuno | Implicito |\n| Richiede embedding | No | Sì |\n| Ideale per | Termini specifici | Concetti |\n\nUsi FTS5 quando conosce le parole chiave. Usi la ricerca semantica quando vuole\n\"memorie su X\" dove X è descritto diversamente.\n\n## Best practice\n\n> [!TIP]\n> - **Usi termini specifici** — \"docker swarm\" batte \"container orchestration\"\n> - **Usi virgolette per le frasi** — `\"docker swarm\"` garantisce corrispondenza di frase\n> - **Usi il prefisso per le variazioni** — `deploy*` cattura \"deploy\", \"deployment\", \"deploying\"\n> - **Escluda il rumore** — `-test` filtra le memorie di test\n> - **Combini con i tag** — `?q=docker&tag=production` restringe i risultati\n\n## Prossimi passi\n\n- [Ricerca semantica](/docs/concepts/semantic-search)\n- [Memory API](/docs/api/memory)\n- [Best practice per la memoria](/docs/guides/memory-best-practices)\n","content_html":"<h1>Ricerca full-text FTS5</h1>\n<p>Synapse usa FTS5 (Full-Text Search 5) per la ricerca nelle memorie veloce e\nflessibile. Questa pagina spiega come funziona e come usarlo efficacemente.</p>\n<h2>Cos&#39;è FTS5?</h2>\n<p>FTS5 è un&#39;estensione SQLite (disponibile anche in PostgreSQL tramite estensioni)\nche fornisce funzionalità di ricerca full-text. Essa:</p>\n<ul>\n<li>Indicizza il contenuto testuale per la ricerca veloce per parola chiave</li>\n<li>Supporta operatori booleani (AND, OR, NOT)</li>\n<li>Supporta la corrispondenza di frasi con virgolette</li>\n<li>Supporta la corrispondenza di prefisso con <code>*</code></li>\n<li>Classifica i risultati per rilevanza</li>\n</ul>\n<p>Synapse usa FTS5 per indicizzare tutti i contenuti delle memorie, abilitando\nricerca sub-millisecond su migliaia di memorie.</p>\n<h2>Come Synapse usa FTS5</h2>\n<p>Quando fa <code>POST /memory</code>:</p>\n<ol>\n<li>Il contenuto della memoria viene salvato nella tabella <code>memories</code></li>\n<li>Il contenuto viene anche inserito nella tabella virtuale FTS5</li>\n<li>FTS5 tokenizza e indicizza automaticamente il contenuto</li>\n</ol>\n<p>Quando fa <code>GET /memory/search?q=...</code>:</p>\n<ol>\n<li>Synapse analizza la query usando la sintassi FTS5</li>\n<li>Esegue un <code>MATCH</code> contro l&#39;indice FTS5</li>\n<li>Filtra per <code>mind_id</code> (isolamento tenant)</li>\n<li>Restituisce i risultati classificati</li>\n</ol>\n<h2>Sintassi delle query</h2>\n<h3>Ricerca semplice per parola chiave</h3>\n<pre><code class=\"hljs language-plaintext\">?q=docker</code></pre><p>Restituisce le memorie che contengono &quot;docker&quot;.</p>\n<h3>Più parole chiave (AND implicito)</h3>\n<pre><code class=\"hljs language-plaintext\">?q=docker+swarm\n?q=docker%20swarm</code></pre><p>Restituisce le memorie che contengono SIA &quot;docker&quot; E &quot;swarm&quot;.</p>\n<h3>Corrispondenza di frase</h3>\n<pre><code class=\"hljs language-plaintext\">?q=&quot;docker+swarm&quot;\n?q=%22docker%20swarm%22</code></pre><p>Restituisce le memorie che contengono la frase esatta &quot;docker swarm&quot;.</p>\n<h3>Corrispondenza di prefisso</h3>\n<pre><code class=\"hljs language-plaintext\">?q=docker*</code></pre><p>Restituisce le memorie che contengono parole che iniziano con &quot;docker&quot; (es.\n&quot;dockers&quot;, &quot;dockerfile&quot;, &quot;dockerize&quot;).</p>\n<h3>OR booleano</h3>\n<pre><code class=\"hljs language-plaintext\">?q=docker+OR+kubernetes</code></pre><p>Restituisce le memorie che contengono &quot;docker&quot; OR &quot;kubernetes&quot;.</p>\n<h3>NOT booleano</h3>\n<pre><code class=\"hljs language-plaintext\">?q=docker+-swarm\n?q=docker+NOT+swarm</code></pre><p>Restituisce le memorie che contengono &quot;docker&quot; ma NON &quot;swarm&quot;.</p>\n<h3>Raggruppamento</h3>\n<pre><code class=\"hljs language-plaintext\">?q=(docker+OR+kubernetes)+-test</code></pre><p>Restituisce le memorie che contengono &quot;docker&quot; o &quot;kubernetes&quot;, ma non &quot;test&quot;.</p>\n<h2>Esempi pratici</h2>\n<h3>Trova memorie su un progetto</h3>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/memory/search?q=synapse+deployment&quot;</span></code></pre><h3>Trova frase esatta</h3>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22&quot;</span></code></pre><h3>Escludi memorie di test</h3>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/memory/search?q=production+-test&quot;</span></code></pre><h3>Trova per tecnologia</h3>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_MIND_KEY&quot;</span> \\\n     <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql&quot;</span></code></pre><h2>Classificazione</h2>\n<p>FTS5 classifica i risultati per rilevanza usando l&#39;algoritmo BM25. Fattori:</p>\n<ul>\n<li>Frequenza del termine (quanto spesso appare il termine)</li>\n<li>Inverse document frequency (termini più rari ottengono classifiche più alte)</li>\n<li>Lunghezza del documento (documenti più corti con il termine ottengono classifica più alta)</li>\n<li>Peso della colonna (title &gt; content)</li>\n</ul>\n<p>I risultati vengono restituiti in ordine di classifica (più rilevanti per primi).</p>\n<h2>Prestazioni</h2>\n<table>\n<thead>\n<tr>\n<th>Operazione</th>\n<th>Latenza</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Ricerca su 100 memorie</td>\n<td>&lt; 5ms</td>\n</tr>\n<tr>\n<td>Ricerca su 1.000 memorie</td>\n<td>&lt; 10ms</td>\n</tr>\n<tr>\n<td>Ricerca su 10.000 memorie</td>\n<td>&lt; 25ms</td>\n</tr>\n<tr>\n<td>Ricerca su 100.000 memorie</td>\n<td>&lt; 100ms</td>\n</tr>\n</tbody></table>\n<p>FTS5 è altamente ottimizzato per workload con molti read.</p>\n<h2>Limitazioni</h2>\n<h3>Stemming</h3>\n<p>FTS5 non fa stemming per default. &quot;running&quot; e &quot;run&quot; sono termini diversi.</p>\n<p><strong>Soluzione:</strong> Usi la corrispondenza di prefisso: <code>?q=run*</code></p>\n<h3>Tolleranza ai refusi</h3>\n<p>FTS5 non supporta il fuzzy matching. Un refuso non restituirà risultati.</p>\n<p><strong>Soluzione:</strong> Usi la ricerca semantica (<code>/memory/semantic-search</code>) per\ncorrispondenza concettuale.</p>\n<h3>Stop word</h3>\n<p>Le parole comuni (the, a, an, is) vengono indicizzate ma potrebbero non essere\nutili per la ricerca. FTS5 le gestisce automaticamente.</p>\n<h2>FTS5 vs ricerca semantica</h2>\n<table>\n<thead>\n<tr>\n<th>Aspetto</th>\n<th>FTS5</th>\n<th>Ricerca semantica</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Velocità</td>\n<td>Sub-millisecond</td>\n<td>50-100ms</td>\n</tr>\n<tr>\n<td>Corrispondenza</td>\n<td>Parole chiave esatte</td>\n<td>Concettuale</td>\n</tr>\n<tr>\n<td>Tolleranza ai refusi</td>\n<td>Nessuna</td>\n<td>Qualcuna</td>\n</tr>\n<tr>\n<td>Stemming</td>\n<td>Nessuno</td>\n<td>Implicito</td>\n</tr>\n<tr>\n<td>Richiede embedding</td>\n<td>No</td>\n<td>Sì</td>\n</tr>\n<tr>\n<td>Ideale per</td>\n<td>Termini specifici</td>\n<td>Concetti</td>\n</tr>\n</tbody></table>\n<p>Usi FTS5 quando conosce le parole chiave. Usi la ricerca semantica quando vuole\n&quot;memorie su X&quot; dove X è descritto diversamente.</p>\n<h2>Best practice</h2>\n<div class=\"callout callout-ok\"></div><h2>Prossimi passi</h2>\n<ul>\n<li><a href=\"/docs/concepts/semantic-search\">Ricerca semantica</a></li>\n<li><a href=\"/docs/api/memory\">Memory API</a></li>\n<li><a href=\"/docs/guides/memory-best-practices\">Best practice per la memoria</a></li>\n</ul>\n","urls":{"html":"/docs/concepts/fts5-search","text":"/docs/concepts/fts5-search?format=text","json":"/docs/concepts/fts5-search?format=json","llm":"/docs/concepts/fts5-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}