Roteiro de busca em um corpus de documentos: pipeline de indexação, permissões e reindexação

Objetivo

Oferecer busca sobre um corpus que vive em um sistema de registro, com resultados que respeitam as permissões e com um índice que nunca fica atrás da origem por mais do que um limite declarado.

Pré-requisitos

Uma definição de documento (id, title, body, metadata, owner, visibility, updated_at), os idiomas envolvidos e um limite de atualização (freshness) que o produto aceite.

Passos

1. Restrições: a origem continua sendo a fonte autoritativa e o índice é derivado e reconstruível; um usuário nunca deve ver um trecho de um documento que não pode abrir; consultar a cada tecla digitada é uma decisão de produto, não um comportamento padrão.
2. Componentes: um indexador alimentado por eventos de mudança (um outbox) ou por polling de updated_at; um armazenamento de índice, começando pelo índice de texto completo do próprio banco de dados e migrando para um motor dedicado quando recursos de ranking ou a escala exigirem; um serviço de consulta que interpreta a entrada, aplica filtros de permissão, faz o ranking e o destaque dos termos; um reconciliador que compara a origem com o índice.
3. Modelo de dados: search_doc(doc_id, version, text fields, acl_keys[], updated_at, indexed_at); as chaves de ACL (id do dono, ids de grupos, public) são campos indexados, de modo que a filtragem ocorre dentro do motor e não depois do ranking. No PostgreSQL, a documentação afirma que os índices GIN são o tipo de índice preferido para busca de texto, guardando uma entrada por lexema com uma lista comprimida de posições.
4. Gestão do índice: versione o índice (docs_v3) e troque um alias após uma reconstrução completa; mantenha o indexador idempotente (upsert por doc_id, ignorando versões mais antigas que a já indexada); trate exclusões como eventos explícitos, nunca pela ausência do documento.
5. Ranking: comece com a relevância padrão do motor, mais um peso para o título e um termo de recência; registre a consulta, os ids dos resultados e a posição do clique, para que uma mudança posterior no ranking possa ser avaliada com base nesse registro.
6. Modos de falha: eventos de mudança perdidos (o reconciliador compara contagens e o maior updated_at por faixa e reindexa a diferença); mudanças de permissão não propagadas (trate edições de ACL como atualizações de documento); consultas muito longas ou com muitos curingas (limite o tamanho e proíba curingas no início do termo); reindexação sob carga (use throttling e leia de uma réplica); trechos que expõem campos que o documento visível oculta (indexe apenas o que pode ser exibido).
7. Medição: atraso do índice (updated_at da origem menos indexed_at), latência das consultas, taxa de consultas sem resultado, proporção de consultas com clique entre os primeiros resultados, divergência encontrada pelo reconciliador e duração da reindexação completa.
8. Não no início: busca semântica ou vetorial, sinônimos e correção ortográfica, ranking personalizado, autocompletar, busca entre idiomas.

Resultado esperado

Um documento editado na origem aparece dentro do limite de atualização, desaparece quando é excluído ou ocultado, e reconstruir tudo do zero é uma operação de rotina, não um incidente.

Limites e base de verificação

Projeto proposto, sem medições. A qualidade da relevância não é tratada além de registrar dados suficientes para avaliá-la depois; o limite de atualização é uma entrada do produto, não uma propriedade do projeto.