solrfal para TYPO3: Indexação de arquivos com Apache Solr

Por que a busca padrão do TYPO3 capitula diante de grandes acervos de documentos

Assim que uma instalação TYPO3 passa a gerenciar algumas centenas de PDFs, a busca nativa esbarra em dois limites: ela só encontra conteúdos em campos do banco de dados, não em arquivos, e sua lógica de ranqueamento ignora os sinais de relevância de que redatores precisam. O solrfal fecha exatamente essa lacuna ao conectar o File Abstraction Layer (FAL) do TYPO3 diretamente ao Apache Solr, tornando cada arquivo pesquisável junto com seus metadados. A extensão se destina a organizações que tratam documentos como o núcleo do seu trabalho de conhecimento: órgãos públicos com formulários, editoras com literatura técnica, universidades com material didático.

Cenários típicos de uso

Em uma universidade técnica com cerca de 40.000 estudantes, o regulamento acadêmico está distribuído em 180 arquivos PDF entre doze faculdades. Sem o solrfal, um aluno da USP ou da UFRJ só encontra o trecho sobre inscrição em provas se um redator tiver cadastrado o texto também como meta-descrição. Com o solrfal, o Apache Tika indexa cada página, e a consulta devolve o parágrafo correto com a citação.

Um segundo cenário é conhecido por órgãos públicos federais que publicam leis, diretrizes e formulários em um CMS TYPO3. Os documentos mudam com frequência, e as permissões de acesso estão vinculadas a unidades organizacionais. O solrfal sincroniza automaticamente a associação de fe_groups dos arquivos no índice Solr, de modo que um servidor de uma coordenação específica só vê resultados para os quais tem permissão de leitura.

O terceiro caso aparece em editoras especializadas: uma editora com 12.000 artigos de revista em PDF quer tornar o acervo pesquisável por uma busca facetada por ano, autor e seção. O solrfal extrai os metadados, preenche os campos Solr e fornece a base para uma faceta que extensões TYPO3 clássicas como ke_search não conseguem mais atender nessa escala.

Arquitetura técnica sob Apache Tika e EXT:solr

O solrfal é uma extensão da extensão principal EXT:solr, da dkd Internet Service, e exige obrigatoriamente um Apache Solr Server em execução, tipicamente na versão 8 ou 9. A extração de texto propriamente dita é feita pelo Apache Tika, seja como serviço embutido no contêiner Solr, seja como servidor Tika autônomo. O solrfal se conecta ao ciclo de vida do FAL via TYPO3 Event API: cada arquivo enviado, movido ou removido dispara um job de indexação, processado de forma assíncrona pelo scheduler do TYPO3.

A configuração do solrfal é feita via TypoScript e Extension Configuration. O schema Solr pode ser ajustado via Managed Schema API, de modo que campos adicionais como tipo de documento, departamento ou idioma podem ser incluídos sem reiniciar o Solr. O ajuste de relevância acontece por meio de boosting queries e function queries, definidas na configuração de consultas da EXT:solr. O solrfal herda todas as features multilíngues da EXT:solr, incluindo analyzers para português, alemão, inglês, francês e outros idiomas padrão.

Problemas frequentes e soluções

O primeiro problema costuma surgir na indexação inicial: o Apache Tika quebra com PDFs corrompidos ou criptografados, gerando um OutOfMemoryError que derruba todo o indexador. A extensão marca o arquivo como defeituoso e não o ignora automaticamente na próxima execução. Analisamos os logs do Tika, separamos os arquivos realmente defeituosos dos apenas criptografados e configuramos um pre-check que descarta arquivos problemáticos antes que cheguem ao indexador.

O segundo tema recorrente é relevância. Equipes relatam que a busca encontra todos os documentos, mas os resultados irrelevantes aparecem no topo. O motivo quase sempre está no peso padrão dos campos: o solrfal indexa todo o conteúdo do arquivo em um único campo, sem distinguir título, cabeçalhos e corpo. Uma solução limpa exige um schema ajustado com campos separados para título, metadados e corpo, além de regras de boosting que priorizem correspondências no título.

O terceiro problema afeta performance em acervos grandes. A partir de cerca de 50.000 arquivos indexados, o scheduler vira gargalo porque o solrfal processa cada job individualmente. A solução é indexação em lote combinada com um worker dedicado que roda paralelamente às tarefas normais do scheduler e prioriza os jobs do solrfal. Vale também uma indexação diferencial, que em cada execução reprocessa apenas arquivos novos ou alterados, reduzindo significativamente o esforço de manutenção em acervos estáveis.

Um quarto tema, mais raro, aparece em instalações multilíngues: o solrfal indexa arquivos de forma independente do idioma em um índice comum, de modo que um estudo em francês aparece na lista de resultados em português se o termo de busca for internacional. Uma separação de idiomas limpa exige múltiplos cores Solr ou uma faceta de idioma adicional, que pode ser controlada por site-root via configuração da EXT:solr.

Migração e compatibilidade de versões

O solrfal segue o ciclo de releases da EXT:solr, que atualmente suporta TYPO3 v12 e v13. O salto do TYPO3 v9 para v12 é o caminho de migração mais comum e quase sempre implica também um salto do Solr 6 para o Solr 9. Com isso, mudam o formato do schema, a Managed Schema API e algumas classes de analyzer, exigindo um reindex completo. Regras de boosting existentes precisam ser validadas contra o novo comportamento do query parser, já que o Solr 9 avalia certos operadores padrão de forma diferente do Solr 6.

Quem migra de ke_search ou de uma busca puramente baseada em banco de dados precisa considerar que o solrfal exige um Solr Server próprio, o que amplia os requisitos de hospedagem. A Gosign acompanha essas migrações há anos e assume, se necessário, a troca para um setup Solr baseado em contêineres, que se integra a pipelines de deploy existentes.

Também é importante notar que a carga de manutenção do solrfal não deve ser subestimada: o próprio Solr recebe atualizações de segurança regulares, e o schema precisa ser validado contra novas classes de analyzer a cada upgrade maior. Um projeto que opta pelo solrfal assume a responsabilidade por um stack de busca próprio e deve considerar isso no sizing inicial e no planejamento dos recursos operacionais.