PT EN
Voltar ao site

Limpar dados de um contexto (purge)

Reprocessar uma base do zero — nova estratégia de fragmentação, nova rodada de extração — costumava significar apagar índices na mão, caçar registros remanescentes e torcer para não derrubar nada do sistema. Com Limpar dados, você esvazia todo o conteúdo de um contexto com um clique auditado: documentos, legislação, trechos, jurisprudência e entidades somem do grafo e da busca, o contexto continua cadastrado e pronto para nova ingestão, e as bases do sistema ficam intocáveis por construção.

Não confunda com Excluir contexto, que remove o próprio contexto da configuração. Limpar só esvazia o conteúdo — o contexto permanece.

A operação é destrutiva e irreversível: o conteúdo apagado só volta por nova ingestão. O registro do contexto continua na base de sistema datta; apenas o conteúdo é apagado, no Neo4j e nos índices de busca do contexto (datta_{contexto}_*).

Passo a passo

  1. Acesse SistemaContextos.
  2. Na linha do contexto, clique em Limpar dados (ícone âmbar).
  3. No diálogo de confirmação, informe o motivo — ele fica registrado em auditoria — e confirme em Sim, limpar tudo.
  4. Acompanhe o progresso pelos avisos na própria tela; erros aparecem com mensagem em português.

Requer a permissão CONTEXT_PURGE (sensível; concedida por padrão apenas ao perfil ADMIN — veja roles e permissões).

O que a limpeza faz

A plataforma orquestra a limpeza do grafo e da busca em paralelo, e cascateia para os processos de negócio antes de apagar a base:

  • Grafo: apaga todo o conteúdo da base de grafo do contexto (documentos, trechos, entidades, relações), em transações fatiadas para dar conta de bases grandes.
  • Busca: remove os índices de busca do contexto (padrão datta_{contexto}_*).
  • Processos BPM: antes de apagar a base, as instâncias de processo BPM cujo contexto efetivo é o domínio limpo são excluídas junto. Instâncias ativas são canceladas primeiro — triagens em voo são interrompidas e as instâncias filhas de atividade de chamada cascateiam. A baseline de auto-início do contexto também é limpa, para que processos reingeridos voltem a ganhar instância. Sem essa cascata, o monitor de BPM ficaria com execuções órfãs apontando para processos que não existem mais — o mesmo raciocínio da limpeza de trechos na exclusão de um processo individual.
  • Pronto para reingestão: após a limpeza, o reenvio dos documentos recria tudo com segurança — reprocessar a mesma base não gera duplicatas, porque a gravação no grafo é idempotente e os documentos de busca têm identificador determinístico.

A cascata para o BPM é best-effort: se o motor de processos estiver indisponível, a limpeza prossegue e o resultado informa a falha (bpmn.status=falhou). Nesse caso, limpe as instâncias órfãs depois com o runbook instâncias BPM órfãs. O evento de auditoria da cascata é BPMN.INSTANCIA.EXCLUIDA_POR_CONTEXTO.

Proteções embutidas

  • Bases do sistema jamais são tocadas: a plataforma recusa limpar as bases internas (neo4j, system, datta, datta-*) e qualquer domínio que não esteja explicitamente mapeado a uma base de contexto — não há retorno à base padrão, ou seja, não existe caminho para um wipe acidental do sistema. Do lado da busca, os padrões datta-* e system também são recusados.
  • Permissão sensível + motivo: só quem tem CONTEXT_PURGE executa, e o motivo fica na trilha de auditoria.
  • Somente pelo aplicativo: a mutação exige a marca de origem do próprio DATTA (o cabeçalho X-Requested-With, injetado automaticamente pelo cliente da aplicação) — chamadas fora do app são bloqueadas.

Exemplo prático — reprocessar com nova estratégia de fragmentação

O time mudou a forma de fragmentar documentos e quer reprocessar o contexto "Processos" inteiro:

  1. Em SistemaContextos, clique em Limpar dados na linha do contexto "Processos".
  2. Motivo: "Reprocessamento com nova estratégia de chunking — chamado 4211".
  3. Confirme em Sim, limpar tudo e aguarde a conclusão.
  4. Reenvie os documentos pela tela de Upload — o contexto é repovoado do zero, com a nova fragmentação, sem duplicatas.

Limitações conhecidas

  • Auditoria em log, não em evento estruturado: hoje a limpeza registra CONTEXT.PURGED nos logs da plataforma, com autor e motivo. A emissão de um evento estruturado para o serviço de auditoria, como acontece em outras mutações, ainda está pendente.
  • Telemetria dedicada: a operação de limpeza ainda não tem span e métrica próprios.

Diagnóstico

  • 403 CSRF_BLOCKED: a chamada não passou pelo cliente da aplicação (sem X-Requested-With). Use o botão na interface, não uma chamada externa crua.
  • 403 por permissão: o usuário não tem CONTEXT_PURGE (apenas ADMIN por padrão).
  • "Contexto ... nao esta mapeado a um database Neo4j — purge recusado.": o domínio não está registrado com uma base de grafo própria — revise o cadastro em gerenciar contextos.

As rotas envolvidas na limpeza (orquestração, grafo, busca e cascata BPM) estão na referência de API.