{"title":"Busca em texto completo FTS5","slug":"fts5-search","category":"concepts","summary":"Como o Synapse usa SQLite FTS5 para busca de memória em texto completo sub-milissegundo.","audience":["human","llm"],"tags":["concept","search","fts5","fulltext"],"difficulty":"advanced","updated":"2026-06-27","word_count":620,"read_minutes":3,"lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Busca em texto completo FTS5\n\nO Synapse usa FTS5 (Full-Text Search 5) para busca de memória rápida e flexível.\nEsta página explica como funciona e como usá-lo de forma eficaz.\n\n## O que é FTS5?\n\nFTS5 é uma extensão do SQLite (também disponível no PostgreSQL via extensões)\nque oferece capacidades de busca em texto completo. Ele:\n\n- Indexa conteúdo textual para busca rápida por palavras-chave\n- Suporta operadores booleanos (AND, OR, NOT)\n- Suporta correspondência de frases com aspas\n- Suporta correspondência por prefixo com `*`\n- Classifica resultados por relevância\n\nO Synapse usa FTS5 para indexar todo o conteúdo das memórias, permitindo busca\nsub-milissegundo entre milhares de memórias.\n\n## Como o Synapse usa FTS5\n\nQuando você faz `POST /memory`:\n\n1. O conteúdo da memória é armazenado na tabela `memories`\n2. O conteúdo também é inserido na tabela virtual FTS5\n3. FTS5 automaticamente tokeniza e indexa o conteúdo\n\nQuando você faz `GET /memory/search?q=...`:\n\n1. O Synapse faz parse da consulta usando a sintaxe FTS5\n2. Executa um `MATCH` contra o índice FTS5\n3. Filtra por `mind_id` (isolamento de tenant)\n4. Retorna resultados classificados\n\n## Sintaxe de consulta\n\n### Busca simples por palavra-chave\n\n```\n?q=docker\n```\n\nRetorna memórias contendo \"docker\".\n\n### Múltiplas palavras-chave (AND implícito)\n\n```\n?q=docker+swarm\n?q=docker%20swarm\n```\n\nRetorna memórias contendo TANTO \"docker\" QUANTO \"swarm\".\n\n### Correspondência de frase\n\n```\n?q=\"docker+swarm\"\n?q=%22docker%20swarm%22\n```\n\nRetorna memórias contendo a frase exata \"docker swarm\".\n\n### Correspondência por prefixo\n\n```\n?q=docker*\n```\n\nRetorna memórias contendo palavras que começam com \"docker\" (ex.: \"dockers\",\n\"dockerfile\", \"dockerize\").\n\n### Booleano OR\n\n```\n?q=docker+OR+kubernetes\n```\n\nRetorna memórias contendo \"docker\" OU \"kubernetes\".\n\n### Booleano NOT\n\n```\n?q=docker+-swarm\n?q=docker+NOT+swarm\n```\n\nRetorna memórias contendo \"docker\" mas NÃO \"swarm\".\n\n### Agrupamento\n\n```\n?q=(docker+OR+kubernetes)+-test\n```\n\nRetorna memórias contendo \"docker\" ou \"kubernetes\", mas não \"test\".\n\n## Exemplos práticos\n\n### Encontrar memórias sobre um projeto\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=synapse+deployment\"\n```\n\n### Encontrar frase exata\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22\"\n```\n\n### Excluir memórias de teste\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=production+-test\"\n```\n\n### Buscar por 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## Ranking\n\nFTS5 classifica resultados por relevância usando o algoritmo BM25. Fatores:\n\n- Frequência do termo (com que frequência o termo aparece)\n- Frequência inversa de documentos (termos mais raros recebem classificação maior)\n- Comprimento do documento (documentos mais curtos com o termo recebem classificação maior)\n- Peso da coluna (title > content)\n\nOs resultados são retornados em ordem de classificação (mais relevantes primeiro).\n\n## Desempenho\n\n| Operação | Latência |\n|----------|----------|\n| Busca em 100 memórias | < 5ms |\n| Busca em 1.000 memórias | < 10ms |\n| Busca em 10.000 memórias | < 25ms |\n| Busca em 100.000 memórias | < 100ms |\n\nFTS5 é altamente otimizado para workloads com muita leitura.\n\n## Limitações\n\n### Stemming\n\nFTS5 não faz stemming por padrão. \"running\" e \"run\" são termos diferentes.\n\n**Solução alternativa:** Use correspondência por prefixo: `?q=run*`\n\n### Tolerância a typos\n\nFTS5 não suporta correspondência fuzzy. Um typo não retornará resultados.\n\n**Solução alternativa:** Use busca semântica (`/memory/semantic-search`) para\ncorrespondência conceitual.\n\n### Stop words\n\nPalavras comuns (the, a, an, is) são indexadas mas podem não ser úteis para\nbusca. FTS5 lida com isso automaticamente.\n\n## FTS5 vs busca semântica\n\n| Aspecto | FTS5 | Busca semântica |\n|---------|------|-----------------|\n| Velocidade | Sub-milissegundo | 50-100ms |\n| Correspondência | Palavras-chave exatas | Conceitual |\n| Tolerância a typos | Nenhuma | Alguma |\n| Stemming | Nenhum | Implícito |\n| Requer embeddings | Não | Sim |\n| Melhor para | Termos específicos | Conceitos |\n\nUse FTS5 quando você conhece as palavras-chave. Use busca semântica quando você\nquer \"memórias sobre X\" onde X é descrito de outra forma.\n\n## Melhores práticas\n\n> [!TIP]\n> - **Use termos específicos** — \"docker swarm\" supera \"container orchestration\"\n> - **Aspas para frases** — `\"docker swarm\"` garante correspondência de frase\n> - **Use prefixo para variações** — `deploy*` captura \"deploy\", \"deployment\", \"deploying\"\n> - **Exclua ruído** — `-test` filtra memórias de teste\n> - **Combine com tags** — `?q=docker&tag=production` estreita os resultados\n\n## Próximos passos\n\n- [Busca semântica](/docs/concepts/semantic-search)\n- [API de Memória](/docs/api/memory)\n- [Melhores práticas de memória](/docs/guides/memory-best-practices)\n","content_html":"

Busca em texto completo FTS5

\n

O Synapse usa FTS5 (Full-Text Search 5) para busca de memória rápida e flexível.\nEsta página explica como funciona e como usá-lo de forma eficaz.

\n

O que é FTS5?

\n

FTS5 é uma extensão do SQLite (também disponível no PostgreSQL via extensões)\nque oferece capacidades de busca em texto completo. Ele:

\n\n

O Synapse usa FTS5 para indexar todo o conteúdo das memórias, permitindo busca\nsub-milissegundo entre milhares de memórias.

\n

Como o Synapse usa FTS5

\n

Quando você faz POST /memory:

\n
    \n
  1. O conteúdo da memória é armazenado na tabela memories
    2. \n
  2. O conteúdo também é inserido na tabela virtual FTS5
    3. \n
  3. FTS5 automaticamente tokeniza e indexa o conteúdo
    4. \n
\n

Quando você faz GET /memory/search?q=...:

\n
    \n
  1. O Synapse faz parse da consulta usando a sintaxe FTS5
    2. \n
  2. Executa um MATCH contra o índice FTS5
    3. \n
  3. Filtra por mind_id (isolamento de tenant)
    4. \n
  4. Retorna resultados classificados
    5. \n
\n

Sintaxe de consulta

\n

Busca simples por palavra-chave

\n
?q=docker

Retorna memórias contendo "docker".

\n

Múltiplas palavras-chave (AND implícito)

\n
?q=docker+swarm\n?q=docker%20swarm

Retorna memórias contendo TANTO "docker" QUANTO "swarm".

\n

Correspondência de frase

\n
?q="docker+swarm"\n?q=%22docker%20swarm%22

Retorna memórias contendo a frase exata "docker swarm".

\n

Correspondência por prefixo

\n
?q=docker*

Retorna memórias contendo palavras que começam com "docker" (ex.: "dockers",\n"dockerfile", "dockerize").

\n

Booleano OR

\n
?q=docker+OR+kubernetes

Retorna memórias contendo "docker" OU "kubernetes".

\n

Booleano NOT

\n
?q=docker+-swarm\n?q=docker+NOT+swarm

Retorna memórias contendo "docker" mas NÃO "swarm".

\n

Agrupamento

\n
?q=(docker+OR+kubernetes)+-test

Retorna memórias contendo "docker" ou "kubernetes", mas não "test".

\n

Exemplos práticos

\n

Encontrar memórias sobre um projeto

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

Encontrar frase exata

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

Excluir memórias de teste

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

Buscar por tecnologia

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

Ranking

\n

FTS5 classifica resultados por relevância usando o algoritmo BM25. Fatores:

\n\n

Os resultados são retornados em ordem de classificação (mais relevantes primeiro).

\n

Desempenho

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperaçãoLatência
Busca em 100 memórias< 5ms
Busca em 1.000 memórias< 10ms
Busca em 10.000 memórias< 25ms
Busca em 100.000 memórias< 100ms
\n

FTS5 é altamente otimizado para workloads com muita leitura.

\n

Limitações

\n

Stemming

\n

FTS5 não faz stemming por padrão. "running" e "run" são termos diferentes.

\n

Solução alternativa: Use correspondência por prefixo: ?q=run*

\n

Tolerância a typos

\n

FTS5 não suporta correspondência fuzzy. Um typo não retornará resultados.

\n

Solução alternativa: Use busca semântica (/memory/semantic-search) para\ncorrespondência conceitual.

\n

Stop words

\n

Palavras comuns (the, a, an, is) são indexadas mas podem não ser úteis para\nbusca. FTS5 lida com isso automaticamente.

\n

FTS5 vs busca semântica

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
AspectoFTS5Busca semântica
VelocidadeSub-milissegundo50-100ms
CorrespondênciaPalavras-chave exatasConceitual
Tolerância a typosNenhumaAlguma
StemmingNenhumImplícito
Requer embeddingsNãoSim
Melhor paraTermos específicosConceitos
\n

Use FTS5 quando você conhece as palavras-chave. Use busca semântica quando você\nquer "memórias sobre X" onde X é descrito de outra forma.

\n

Melhores práticas

\n

Próximos passos

\n\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"]}