Busca interna no PrestaShop: por que um produto cadastrado não aparece nos resultados?

O cliente digita o nome de um produto que você vende, recebe uma
lista vazia e procura outra loja. Quando o atendimento reproduz a busca,
alguém encontra o item pelo painel e conclui que “está tudo cadastrado”.
As duas observações podem estar corretas: existir no catálogo não prova
que o produto está disponível para a busca da vitrine.

O diagnóstico exige separar três perguntas: o produto pode aparecer
naquele contexto, os termos estão representados no índice e a consulta
efetivamente corresponde a eles? Só depois faz sentido discutir a
posição do resultado. Este guia propõe uma investigação reproduzível,
com exemplos fictícios, baseada na documentação do PrestaShop 9
consultada em 14/09/2026. Em outras versões ou com módulos de busca,
confirme os recursos disponíveis antes de aplicar comandos.

1.
Reproduza a consulta do cliente, não uma consulta parecida

Escolha um produto e anote seu ID, nome, referência principal,
referências das combinações, idioma e loja. Copie exatamente o termo
pesquisado, inclusive hífen, espaço, acento e código. Registre se o
cliente usou as sugestões enquanto digitava ou abriu a página completa
de resultados.

Faça o teste como visitante e, quando pertinente, com o mesmo grupo
de cliente. Não compare uma pesquisa em português com um cadastro
examinado apenas em inglês. Em multiloja, use o domínio e o contexto
corretos.

Guarde uma evidência simples: consulta, resultado esperado, resultado
observado, URL e horário. “A busca não funciona” é difícil de
investigar; “a consulta LX-204 não encontra o produto 42 na loja 2 em
português, mas luminária encontra” já delimita o problema.

2. Confirme quem responde
pela busca

A caixa de pesquisa pode ser visualmente parte do tema, enquanto os
resultados vêm do mecanismo nativo, de um módulo ou de um serviço
externo. Autocomplete e página de resultados também podem seguir
caminhos diferentes.

No navegador, abra a aba de rede e execute a consulta. Identifique a
requisição que retorna os resultados, seus parâmetros e o componente
responsável. Um retorno HTTP 200 com lista vazia é diferente de um erro
de JavaScript que impede a lista de aparecer.

Se houver um motor externo, verifique seu catálogo sincronizado e
seus registros de processamento. Reconstruir o índice nativo não
comprova que esse outro motor foi atualizado. Registre essa arquitetura
antes de alterar configurações: evita corrigir um componente que o
cliente nem está usando.

3.
Verifique elegibilidade antes de reconstruir o índice

Confira se o produto está ativo, associado à loja correta e com
visibilidade que permita aparecer na pesquisa. O PrestaShop diferencia
as opções de visibilidade do produto; estar acessível por uma URL direta
não basta para provar que ele deva aparecer em todos os locais da
vitrine. Consulte as opções da versão instalada na documentação
de produtos.

Investigue ainda restrições adicionadas por módulos, regras de acesso
e eventuais filtros de disponibilidade. Não trate estoque zero como uma
explicação universal: a operação pode permitir produtos sem estoque, e
uma personalização pode filtrá-los de outro modo.

Se o problema ocorre em apenas um idioma, compare os campos
localizados efetivamente salvos. Se ocorre só em uma loja, examine suas
associações e configurações. Reconstruir tudo antes dessa verificação
pode consumir tempo e reproduzir exatamente o mesmo resultado.

4.
Entenda o índice como uma estrutura separada do cadastro

Na busca nativa, palavras e produtos são relacionados pelas tabelas
de índice. A documentação identifica ps_search_word, com
contexto de loja e idioma, e ps_search_index, com relações
entre palavra, produto e peso. O prefixo real do banco pode ser
diferente de ps_. Estrutura
oficial do índice.

Isso permite uma investigação em etapas: o termo normalizado existe
no contexto correto? Há relação com o produto esperado? O produto passa
pelos filtros da consulta? O resultado chega ao navegador? Não é
necessário começar alterando dados diretamente no banco.

Uma rotina de importação pode gravar os campos sem executar o mesmo
fluxo de atualização usado pelo painel. Se o defeito reaparece após cada
importação, a correção duradoura está no processo de atualização e em
sua observabilidade. Uma reconstrução manual que resolve por algumas
horas é uma evidência, não o encerramento do diagnóstico.

5. Exemplo
completo: nome encontra, referência não

Considere o produto fictício Luminária de mesa
articulada, ID 42, referência LX-204. A equipe
deseja que clientes o encontrem tanto pela descrição quanto pelo código
da embalagem.

Execute a primeira consulta. Se ela encontra o item, você já sabe que
o produto não está ausente de toda pesquisa. Inspecione então o código
efetivamente cadastrado: é referência do produto, de uma combinação ou
apenas texto em uma imagem? A busca não deve ser presumida capaz de ler
uma foto da embalagem.

Depois compare as variantes do código e registre os resultados. Não
remova todos os hífens do catálogo por causa de um único teste. Isso
pode alterar identificadores usados por outras rotinas. Primeiro
descubra se a divergência está no cadastro, na normalização ou na
configuração do motor.

Após a correção escolhida, repita todas as consultas da tabela.
Resolver LX-204 e prejudicar a busca pelo nome não é um resultado
aceitável. Acrescente produtos semelhantes para verificar se o mecanismo
passou a retornar itens irrelevantes.

6. Termos curtos,
palavras ignoradas e aliases

As configurações de busca incluem tamanho mínimo de palavra, lista de
palavras ignoradas, aliases e recursos de correspondência aproximada. Os
pesos dos campos influenciam a relevância. Esses controles têm
finalidades diferentes e devem ser avaliados separadamente. Parâmetros
oficiais de busca.

Para um catálogo técnico, duas letras podem representar uma linha
comercial importante. Para outro, podem gerar muitos resultados pouco
úteis. Faça uma lista de consultas curtas relevantes antes de reduzir
limites globalmente. Compare qualidade dos resultados e custo de
processamento em uma cópia da loja.

Um alias pode ser adequado para um erro recorrente e bem
identificado, como a troca de letras em “luminária”. Não use um
dicionário enorme como substituto para cadastros incompletos. Cada
relação precisa de uma intenção clara e de um teste que demonstre que
ela ajuda o comprador.

Busca aproximada também não é sinônimo de compreensão semântica. Para
códigos técnicos, uma aproximação visualmente pequena pode apontar para
um produto incompatível. Preserve testes por referência exata junto dos
testes de tolerância a erros.

7.
Produto ausente e produto mal posicionado são defeitos diferentes

Se o produto aparece na página cinco, há correspondência, mas talvez
a ordenação não atenda à intenção da consulta. Se não aparece em nenhuma
página, aumentar o peso do nome pode não alcançar a causa.

Monte um conjunto de consultas com resultado esperado: código exato,
nome específico, categoria ampla e termo presente apenas na descrição.
Para cada uma, defina se espera um produto determinado ou um grupo
coerente. Não existe uma ordem única que seja perfeita para todas as
intenções.

Ao ajustar pesos, altere um fator por vez e reteste esse conjunto.
Verifique se a reconstrução do índice é necessária na implementação
instalada para que os pesos usados reflitam a mudança. Não assuma que
salvar uma configuração reprocessou todos os dados existentes.

Evite inserir palavras repetidas nas descrições para forçar posição.
Além de prejudicar a leitura, isso torna o catálogo dependente de um
comportamento específico do mecanismo. Corrija a relevância no lugar
apropriado e mantenha os textos úteis ao comprador.

8. Reindexe com
escopo e verifique a conclusão

No painel, diferencie adicionar itens ausentes de reconstruir todo o
índice. Um produto já indexado, mas com termos antigos, pode exigir uma
atualização diferente da inclusão dos novos. Programe operações mais
amplas fora dos picos e não dispare várias reconstruções
simultâneas.

Nas instalações que disponibilizam o comando documentado para
PrestaShop 9, consulte primeiro a ajuda local:

php bin/console prestashop:search:index --help

Para investigar o exemplo em uma cópia controlada, substitua os IDs
pelos reais:

php bin/console prestashop:search:index --shop-id=2 --product-id=42

Não acrescente --full sem definir o escopo: a opção
remove e reconstrói dados do índice. A disponibilidade e as opções devem
ser confirmadas na versão instalada. Comando
oficial de indexação.

Registre duração, saída e código de término. Depois confirme o
resultado na vitrine. Se usar agendamento, monitore a execução real, não
apenas a existência da tarefa. Proteja URLs de manutenção com token e
não as exponha em capturas públicas.

9. Quando
investigar banco, módulos e apresentação

Se o índice contém os termos esperados, examine o caminho da
consulta. Em ambiente de diagnóstico, correlacione o horário da pesquisa
com logs e requisições. Observe contexto, parâmetros, filtros, ordenação
e paginação.

Se o servidor retorna o produto, mas a interface não o mostra,
investigue o tema, o JavaScript e a renderização. Se autocomplete e
página completa discordam, compare ambos os endpoints. Cache só deve
entrar como hipótese concreta: identifique qual camada armazenou qual
resposta antes de limpar tudo indiscriminadamente.

Quando houver lentidão, profiling pode ajudar a localizar o custo,
mas não explica sozinho por que um produto foi excluído. Diferencie
tempo de execução de correção funcional. Preserve um cenário
reproduzível antes de trocar módulos ou editar código.

10. Critérios para encerrar o
chamado

Considere o problema resolvido quando as consultas aprovadas
retornarem os resultados esperados no contexto correto, a rotina de
atualização mantiver esse comportamento e a equipe conseguir repetir a
verificação.

Registre a causa, a mudança, os testes e como reverter a
configuração. Refaça uma importação ou edição representativa e confirme
que a falha não retorna. Para acompanhar qualidade, uma operação pode
medir pesquisas sem resultado, reformulações e cliques após a busca,
desde que essa coleta esteja implementada; não pressuponha que todas
essas métricas já existam na instalação.

Uma busca confiável depende de cadastro, índice, consulta e
apresentação trabalhando de forma consistente. A AGTI pode ajudar a
localizar a etapa que falha e corrigir o processo que a alimenta. Converse com a equipe levando uma
consulta real e o produto que deveria ser encontrado.