Como Adicionar Busca ao Seu App: De Filtros Simples a Busca Full-Text

Para adicionar busca ao seu app, comece com o mais simples que funciona: uma caixa de busca que chama uma rota no servidor, a qual filtra as linhas do banco comparando a consulta com algumas colunas, mais filtros para coisas como categoria ou preço. Quando isso não bastar — você precisa de ranqueamento por relevância, radicalização de palavras ou muitos registros —, troque para a busca full-text do seu banco de dados, e só passe para um mecanismo de busca hospedado se precisar de forte tolerância a erros de digitação ou resultados instantâneos sobre dados muito grandes. Qualquer que seja a escolha, a busca precisa respeitar as permissões: os usuários nunca devem encontrar registros que não têm permissão de ver.

O que "busca" significa para o seu app

Busca cobre algumas coisas diferentes, e a maioria dos apps precisa de mais de uma:

Busca por palavra-chave: uma caixa de texto — "encontrar anúncios que mencionem 'jardim'".
Filtros: escolhas estruturadas — categoria, cidade, faixa de preço, data, status.
Ordenação: mais recentes, mais baratos, mais relevantes.
Autocompletar: sugestões enquanto a pessoa digita.
Tolerância a erros de digitação: "restuarant" ainda encontra "restaurant".

Para um diretório, um portal de vagas ou uma loja, os filtros costumam importar mais do que a caixa de texto. Decida quais desses você realmente precisa antes de escolher a ferramenta.

Suas opções

Abordagem	Como funciona	Ideal para	Limites
Filtrar no navegador	Carregar a lista e filtrá-la em JavaScript	Listas públicas pequenas (algumas centenas de itens)	Envia todos os dados a cada visitante; lento com listas grandes
Correspondência de padrão no banco	Consulta no servidor do tipo "o nome contém o texto", sem diferenciar maiúsculas	Apps pequenos a médios, ferramentas administrativas	Sem ranqueamento; pode ficar lento em tabelas grandes; sem radicalização
Busca full-text no banco	O Postgres indexa palavras e ranqueia as correspondências	A maioria dos apps com muito conteúdo	Fraca com erros de digitação, a menos que você adicione correspondência aproximada
Correspondência aproximada (trigramas)	O Postgres compara sequências de caracteres por semelhança	Nomes, campos curtos, tolerância a erros de digitação	Precisa de uma extensão e de um índice; a calibragem exige cuidado
Mecanismo de busca hospedado	Um serviço separado indexa seus dados (Algolia, Meilisearch, Typesense, Elasticsearch e outros)	Catálogos grandes, busca instantânea, forte tolerância a erros	Mais um serviço para manter sincronizado, pagar e proteger

Se os seus dados já estão no Postgres, a busca full-text nativa dele é um ótimo meio-termo. Ela quebra o texto em palavras, reduz essas palavras aos radicais (para que "correndo" encontre "correr"), ignora palavras comuns e pode ranquear os resultados pelo quão bem correspondem. Com o índice certo, continua rápida em tabelas grandes.

Exemplos de prompts

Um começo simples:

Adicione uma caixa de busca e filtros à página de anúncios. A busca deve comparar a consulta com título e descrição, sem diferenciar maiúsculas de minúsculas. Filtros: categoria (lista suspensa), cidade (lista suspensa) e preço máximo. Faça a busca no servidor com uma rota de API paginada, 20 resultados por página. Mantenha a busca e os filtros na URL para que os resultados possam ser compartilhados e o botão voltar funcione. Mostre um estado vazio amigável quando nada corresponder.

Atualizando para busca full-text:

Troque a busca de anúncios para a busca full-text do Postgres em título (com peso maior) e descrição. Adicione o índice correto, ranqueie os resultados por relevância e mantenha os filtros e a paginação existentes. Não altere nenhum dado atual.

Adicionando tolerância a erros de digitação para nomes:

Adicione correspondência aproximada no nome do negócio para que pequenos erros de digitação ainda encontrem resultados. Use similaridade por trigramas, se disponível, com um índice, e volte para a busca atual caso contrário.

Passo a passo

Liste o que as pessoas buscam. Quais campos (título, descrição, tags, nome)? Quais filtros? Converse com alguns usuários reais, se puder.
Comece no servidor. Adicione uma rota de API que recebe a consulta e os filtros e devolve uma página de resultados. Não carregue tudo no navegador.
Aplique as permissões na consulta. Se os usuários só veem os próprios registros, ou só os publicados, essa condição pertence à mesma consulta da busca.
Adicione paginação desde o início — números de página ou "carregar mais".
Coloque o estado da busca na URL (por exemplo ?q=jardim&city=leeds). Links compartilháveis, botão voltar funcionando, e mecanismos de busca podem rastrear páginas filtradas se você quiser que isso aconteça.
Aplique debounce na busca enquanto digita. Espere algumas centenas de milissegundos depois que a digitação para antes de consultar, para não enviar uma requisição a cada tecla.
Adicione índices quando souber em quais colunas filtra e pesquisa.
Evolua para busca full-text, depois correspondência aproximada, depois um mecanismo hospedado — só quando o passo anterior falhar com usuários reais.
Teste com dados que pareçam reais: centenas ou milhares de linhas, caracteres estranhos, consultas vazias, consultas muito longas, outros idiomas, se você oferecer suporte a eles.

Erros comuns

Carregar a tabela inteira no navegador. Funciona para 50 itens, é doloroso para 50 mil, e expõe todos os registros — inclusive os que o usuário não deveria ver.
Busca que ignora as permissões. A busca é um vazamento comum: um registro privado ou um rascunho aparece porque a consulta esqueceu a condição "só os meus" ou "só os publicados".
Montar SQL com a entrada bruta do usuário. Sempre use consultas parametrizadas. Um construtor de IA normalmente faz isso, mas confira se você vê strings sendo concatenadas.
Nenhum estado vazio. "Nenhum resultado" com uma sugestão (limpar filtros, conferir a grafia) evita que as pessoas saiam.
Sem índices. A busca parece boa com dados de teste e vai ficando lenta conforme os dados reais crescem.
Ir direto para um serviço de busca. Aí você passa a manter uma segunda cópia dos dados sincronizada, lidar com exclusões e proteger outro conjunto de chaves — muitas vezes sem ganho visível.
Esquecer o celular. Os filtros precisam caber em um telefone; uma gaveta de filtros ou um painel recolhível geralmente funciona melhor do que uma barra lateral.

Checklist

Você sabe quais campos são pesquisados e quais filtros existem
A busca roda no servidor e devolve resultados paginados
A consulta aplica as mesmas permissões do restante do app
A entrada do usuário é passada como parâmetros, nunca concatenada no SQL
O estado da busca fica na URL
A digitação tem debounce
As colunas pesquisadas e filtradas têm índice
Estados vazio, sem resultados e de erro são claros
Testado com volumes de dados realistas e entradas bagunçadas

Adicionando busca com o Mythex

Em um app criado no Mythex, os dados normalmente ficam no banco Postgres próprio do projeto, então você pode começar com os prompts acima: primeiro a correspondência de padrão, depois a busca full-text do Postgres quando precisar de ranqueamento. Se quiser um mecanismo de busca hospedado, use sua própria conta e chave, guarde-a como segredo do projeto e peça ao agente para indexar e consultar pelo servidor, como descrito em Integrar qualquer API.

A busca é o centro de muitos apps: veja como criar um site de diretório, como criar um portal de vagas e como criar um marketplace para entender como ela se encaixa no restante do produto.

Perguntas

Qual é a forma mais fácil de adicionar busca a um app?

Se os seus dados estão em um banco de dados, uma rota no servidor que filtra as linhas com uma comparação sem diferenciar maiúsculas de minúsculas em algumas colunas é o ponto de partida mais fácil. Para uma lista pequena que já está carregada no navegador, filtrar no próprio navegador é ainda mais simples.

Preciso do Algolia ou do Elasticsearch para busca?

Normalmente, não no começo. A busca full-text do Postgres lida bem com correspondência de palavras, ranqueamento e de milhares a milhões de linhas. Um mecanismo de busca hospedado vale a pena quando você precisa de forte tolerância a erros de digitação, resultados instantâneos enquanto a pessoa digita sobre grandes volumes de dados ou ajuste avançado de relevância.

Por que minha busca não encontra resultados com erros de digitação?

A correspondência básica e a busca full-text padrão procuram as palavras como foram digitadas (ou seus radicais), então um erro de grafia não encontra nada. Você precisa de correspondência aproximada, como a similaridade por trigramas no Postgres ou um mecanismo de busca com tolerância a erros de digitação.

A busca deve rodar no navegador ou no servidor?

No servidor, para qualquer coisa além de uma pequena lista pública. A busca no servidor escala, respeita as permissões e não envia todos os seus dados a cada visitante.