Como Adicionar Pesquisa à Sua App: De Filtros Simples a Pesquisa de Texto Completo

Para adicionar pesquisa à sua app, comece pela solução mais simples que funciona: uma caixa de pesquisa que chama uma rota do servidor, que filtra as linhas da base de dados comparando a consulta com algumas colunas, mais filtros para coisas como categoria ou preço. Quando isso não bastar — precisa de ordenação por relevância, radicais de palavras ou muitos registos — mude para a pesquisa de texto completo da sua base de dados, e só passe para um motor de pesquisa alojado se precisar de forte tolerância a erros de escrita ou de resultados instantâneos sobre grandes volumes de dados. Seja qual for a opção, a pesquisa tem de respeitar as permissões: os utilizadores nunca devem encontrar registos que não têm autorização para ver.

O que significa «pesquisa» para a sua app

A pesquisa abrange várias coisas diferentes, e a maioria das apps precisa de mais do que uma:

Pesquisa por palavras-chave: uma caixa de texto — «encontrar anúncios que mencionem "jardim"».
Filtros: escolhas estruturadas — categoria, cidade, intervalo de preço, data, estado.
Ordenação: mais recentes, mais baratos, mais relevantes.
Preenchimento automático: sugestões enquanto se escreve.
Tolerância a erros de escrita: «restuarant» ainda encontra «restaurant».

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

As suas opções

Abordagem	Como funciona	Indicada 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; lenta com listas grandes
Correspondência de padrões na base de dados	Consulta no servidor do tipo «o nome contém o texto», sem distinguir maiúsculas	Apps pequenas a médias, ferramentas de administração	Sem ordenação por relevância; pode ficar lenta em tabelas grandes; sem radicais
Pesquisa de texto completo na base de dados	O Postgres indexa palavras e ordena os resultados	A maioria das apps com muito conteúdo	Fraca com erros de escrita, a não ser que acrescente correspondência aproximada
Correspondência aproximada (trigramas)	O Postgres compara sequências de caracteres para medir semelhança	Nomes, campos curtos, tolerância a erros	Precisa de uma extensão e de um índice; a afinação dá trabalho
Motor de pesquisa alojado	Um serviço separado indexa os seus dados (Algolia, Meilisearch, Typesense, Elasticsearch e outros)	Catálogos grandes, pesquisa instantânea, forte tolerância a erros	Mais um serviço para manter sincronizado, pagar e proteger

Se os seus dados já estiverem no Postgres, a sua pesquisa de texto completo incorporada é um bom meio-termo. Divide o texto em palavras, reduz-as a radicais (para que «correr» encontre «corrida»), ignora palavras comuns e pode ordenar os resultados pela qualidade da correspondência. Com o índice certo, continua rápida em tabelas grandes.

Exemplos de prompts

Um começo simples:

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

Passar para pesquisa de texto completo:

Mude a pesquisa de anúncios para a pesquisa de texto completo do Postgres, sobre o título (com mais peso) e a descrição. Adicione o índice adequado, ordene os resultados por relevância, e mantenha os filtros e a paginação existentes. Não altere nenhum dado existente.

Adicionar tolerância a erros de escrita em nomes:

Adicione correspondência aproximada no nome da empresa para que pequenos erros de escrita ainda encontrem resultados. Use a similaridade por trigramas se estiver disponível, com um índice, e recorra à pesquisa atual se não estiver.

Passo a passo

Liste o que as pessoas procuram. Que campos (título, descrição, etiquetas, nome)? Que filtros? Pergunte a alguns utilizadores reais, se puder.
Comece pelo servidor. Adicione uma rota de API que receba a consulta e os filtros, e devolva uma página de resultados. Não carregue tudo para o navegador.
Aplique as permissões na consulta. Se os utilizadores só veem os seus registos, ou apenas os publicados, essa condição pertence à mesma consulta da pesquisa.
Acrescente paginação desde o início — números de página ou «carregar mais».
Coloque o estado da pesquisa no URL (por exemplo ?q=jardim&city=leeds). Assim as ligações podem ser partilhadas, o botão de voltar funciona, e os motores de pesquisa podem rastrear páginas filtradas se quiser que o façam.
Aplique um atraso (debounce) à pesquisa enquanto escreve. Espere algumas centenas de milissegundos depois de parar de escrever antes de consultar, para não enviar um pedido por cada tecla.
Acrescente índices quando souber quais colunas filtra e pesquisa.
Evolua para a pesquisa de texto completo, depois para a correspondência aproximada, e só então para um motor alojado — apenas quando o passo mais simples falhar com utilizadores reais.
Teste com dados que pareçam reais: centenas ou milhares de linhas, caracteres estranhos, consultas vazias, consultas muito longas, outras línguas se as suportar.

Erros comuns

Carregar a tabela inteira para o navegador. Serve para 50 itens, mas é doloroso para 50 000, e expõe todos os registos — incluindo os que o utilizador não deveria ver.
Pesquisa que ignora as permissões. A pesquisa é uma fuga comum: um registo privado ou um rascunho aparece porque a consulta se esqueceu da condição «só os meus» ou «só os publicados».
Construir SQL a partir de texto introduzido pelo utilizador. Use sempre consultas parametrizadas. Um criador com IA normalmente faz isto, mas verifique se vê strings a serem coladas.
Sem estado vazio. «Sem resultados» com uma sugestão (limpar filtros, verificar a ortografia) evita que as pessoas saiam.
Sem índices. A pesquisa parece bem com dados de teste e fica lenta à medida que os dados reais crescem.
Saltar logo para um serviço de pesquisa. Fica com uma segunda cópia dos dados para sincronizar, para tratar eliminações e para proteger outro conjunto de chaves — muitas vezes sem qualquer ganho visível.
Esquecer o telemóvel. Os filtros têm de caber num telemóvel; uma gaveta de filtros ou um painel recolhível costuma funcionar melhor do que uma barra lateral.

Lista de verificação

Sabe que campos são pesquisados e que filtros existem
A pesquisa corre no servidor e devolve resultados paginados
A consulta aplica as mesmas permissões que o resto da app
O texto do utilizador é passado como parâmetros, nunca colado em SQL
O estado da pesquisa fica no URL
A escrita tem atraso (debounce)
As colunas pesquisadas e filtradas têm índices
Estados vazios, sem resultados e de erro são claros
Testado com volumes de dados realistas e entradas confusas

Adicionar pesquisa com a Mythex

Numa app criada na Mythex, os dados normalmente vivem na base de dados Postgres do próprio projeto, por isso pode começar com os prompts acima: primeiro a correspondência de padrões, depois a pesquisa de texto completo do Postgres quando precisar de ordenação. Se quiser um motor de pesquisa alojado, traga a sua própria conta e chave, guarde-a como segredo do projeto e peça ao agente que indexe e consulte esse serviço a partir do servidor, como descrito em Integrar qualquer API.

A pesquisa está no centro de muitas apps: veja como criar um site de diretório, como criar um portal de emprego e como criar um marketplace para perceber como ela se integra no resto do produto.

Perguntas

Qual é a forma mais fácil de adicionar pesquisa a uma app?

Se os seus dados estiverem numa base de dados, o mais fácil é uma rota no servidor que filtra as linhas com uma correspondência sem distinguir maiúsculas de minúsculas em algumas colunas. Para uma lista pequena que já esteja carregada no navegador, filtrar no próprio navegador é ainda mais simples.

Preciso do Algolia ou do Elasticsearch para pesquisar?

Normalmente não, pelo menos no início. A pesquisa de texto completa do Postgres lida bem com a correspondência de palavras, a ordenação por relevância e de milhares a milhões de linhas. Um motor de pesquisa alojado compensa quando precisa de boa tolerância a erros de escrita, resultados instantâneos ao escrever sobre grandes volumes de dados ou ajuste avançado da relevância.

Porque é que a minha pesquisa não encontra resultados com erros de escrita?

A correspondência básica e a pesquisa de texto completo padrão procuram as palavras tal como foram escritas (ou os seus radicais), por isso um erro de ortografia não encontra nada. Precisa de correspondência aproximada, como a similaridade por trigramas no Postgres ou um motor de pesquisa com tolerância a erros.

A pesquisa deve correr no navegador ou no servidor?

No servidor, para tudo o que vá além de uma pequena lista pública. A pesquisa no servidor escala, respeita as permissões e não envia todo o conjunto de dados a cada visitante.