Skip to main content

Busca em texto completo FTS5

advanced 🤖 Compatível com LLM 3 min · 620 palavras Atualizado: 2026-06-27 Português

Como o Synapse usa SQLite FTS5 para busca de memória em texto completo sub-milissegundo.

Ler este artigo como: 📄 Texto simples ⚡ JSON 🤖 Formato LLM
Idioma: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

Busca em texto completo FTS5

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

O que é FTS5?

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

  • Indexa conteúdo textual para busca rápida por palavras-chave
  • Suporta operadores booleanos (AND, OR, NOT)
  • Suporta correspondência de frases com aspas
  • Suporta correspondência por prefixo com *
  • Classifica resultados por relevância

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

Como o Synapse usa FTS5

Quando você faz POST /memory:

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

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

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

Sintaxe de consulta

Busca simples por palavra-chave

?q=docker

Retorna memórias contendo "docker".

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

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

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

Correspondência de frase

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

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

Correspondência por prefixo

?q=docker*

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

Booleano OR

?q=docker+OR+kubernetes

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

Booleano NOT

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

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

Agrupamento

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

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

Exemplos práticos

Encontrar memórias sobre um projeto

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

Encontrar frase exata

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

Excluir memórias de teste

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

Buscar por tecnologia

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

Ranking

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

  • Frequência do termo (com que frequência o termo aparece)
  • Frequência inversa de documentos (termos mais raros recebem classificação maior)
  • Comprimento do documento (documentos mais curtos com o termo recebem classificação maior)
  • Peso da coluna (title > content)

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

Desempenho

Operação Latê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

FTS5 é altamente otimizado para workloads com muita leitura.

Limitações

Stemming

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

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

Tolerância a typos

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

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

Stop words

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

FTS5 vs busca semântica

Aspecto FTS5 Busca semântica
Velocidade Sub-milissegundo 50-100ms
Correspondência Palavras-chave exatas Conceitual
Tolerância a typos Nenhuma Alguma
Stemming Nenhum Implícito
Requer embeddings Não Sim
Melhor para Termos específicos Conceitos

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

Melhores práticas

Próximos passos

← Voltar a Conceitos