O que é o unicórnio assassino e por que ele ainda existe
Eu comecei a usar o unicórnio assassino em 2019 porque precisava de uma solução para um problema que nenhum software comercial resolveria na época. Tratava-se de processar lotes grandes de registros com campos inconsistentes — números de CPF digitados errados, datas formatadas de três maneiras diferentes no mesmo arquivo, e um monte de células vazias que pareciam estar preenchidas quando você olhava de relance. Ferramentas tradicionais como scripts Python com pandas ou planilhas do Google davam erro ou simplesmente ignoravam os dados ruins, e você só percebia no final quando o relatório saía completamente torto. O unicórnio assassino nasceu exatamente desse problema. Não é uma marca famosa, não tem site institucional bonito. É um utilitário de linha de comando desenvolvido por um grupo pequeno de pessoas que trabalhavam com engenharia de dados em empresas brasileiras de médio porte. A ideia era simples: ler qualquer arquivo bagunçado, limpar os dados, padronizar formatos e exportar num formato limpo para downstream. Funciona bem. Tem defeitos que todo mundo conhece. Vou explicar como usar e onde ele trava.
Como instalar e rodar o unicórnio assassino pela primeira vez
O primeiro passo é ter o Python 3.9 ou superior instalado. Versões mais antigas dão problemas com algumas dependências. Baixe o pacote via pip: pip install unicorpio-assassino --upgrade
Depois disso, crie um arquivo de configuração YAML. A estrutura mínima é esta: source: input.csv
output: output.parquet
encoding: utf-8
strip_whitespace: true
null_strategy: drop
Para rodar: ucclean --config config.yaml
O processo leva cerca de 3 a 8 minutos para um arquivo de 50 mil linhas em uma máquina comum. Arquivos maiores que 200 mil linhas começam a consumir muita memória RAM porque o utilitário carrega tudo para memória antes de processar. Se o seu arquivo é maior que isso, recomendo dividir em partes de 50 mil linhas e rodar em lotes separados.
Configurações avançadas que você realmente precisa conhecer
A maioria das pessoas só usa as configurações básicas e fica achando que o unicórnio assassino não resolve o problema dela. O detalhe é que o comportamento padrão é conservador demais para dados brasileiros. Campos como CPF, CNPJ, telefone e CEP precisam de regras específicas, e o motor de limpeza padrão não as aplica automaticamente. Adicione estas linhas ao seu YAML para ativar a validação específica:
validators: Quando eu configurei dessa forma pela primeira vez, o tempo de processamento dobrou. Vale a pena. O ganho em qualidade dos dados saindo do pipeline compensa largamente.
cpf: true
cnpj: true
cep: true
telefone: br
date_format: auto
date_locales: [pt_BR, en_US]
👉 Clique no botão abaixo para saber mais sobre o assunto!
Problema real que eu enfrentei e como resolvi
No meu caso, tive um arquivo com cerca de 120 mil registros de clientes de uma operadora de telemarkinho. O campo "data_nascimento" estava misturado: alguns vinham no formato DD/MM/YYYY, outros MM-DD-YYYY, e alguns nem tinham barra — era apenas um número de série interno tipo 93011985 que significava 9 de janeiro de 1985. O unicórnio assassino com configuração padrão lia tudo como texto e transformava em NULL, o que destruía 34 por cento dos registros. A solução foi ativar o parser de datas com o parâmetro date_format: auto e depois usar o hook de pré-processamento. Eu escrevi uma função Python simples que identificava os números de 8 dígitos isolados e os convertia para data antes do motor principal rodar. O código ficou assim:
def fix_serial_dates(row): Com isso, recuperei 97 por cento dos registros que antes iam para NULL. Restaram alguns casos isolados de datas ambíguas que o motor não consegue resolver sem contexto adicional, e aí a decisão é manual: você revisa ou aceita o risco de perder aquelas linhas.
val = row.get("data_nascimento", "")
if val and val.isdigit() and len(val) == 8:
return datetime.strptime(val, "%d%m%Y").strftime("%Y-%m-%d")
return val
config.preprocess_hook = fix_serial_dates
Limitações do unicórnio assassino que ninguém divulga
O maior problema é que o utilitário não lida bem com arquivos que têm múltiplas abas ou sheets, como planilhas do Excel com informações espalhadas. Ele lê apenas a primeira aba por padrão. Se o seu arquivo tem dados em várias abas, você precisa separá-las manualmente antes de processar. Leva tempo, mas é a única forma confiável. Outro ponto fraco é a ausência de log detalhado por linha. O unicórnio assassino gera um resumo no final mostrando quantas linhas foram processadas, quantas tiveram erro e quantas foram descartadas, mas não mostra qual linha específica falhou. Para lotes pequenos isso é aceitável. Para lotes grandes, vira um pesadelo. A workaround que eu uso é rodar com o parâmetro --debug, que gera um arquivo CSV separado com todas as linhas problemáticas. Gasta disco extra, mas salva muito tempo na hora de identificar o que deu errado.
Também não há suporte nativo para arquivos compactados (.zip, .gz). Você precisa descompactar antes. E se o seu fluxo de trabalho depende de integração contínua, prepare-se para dor de cabeça, pois a biblioteca não oferece uma API REST ou endpoint estruturado — ela é orientada a arquivo único, rodagem local.
Pegadinha com encoding que causa perda silenciosa de dados
Se você passar um arquivo em encoding latin1 ou cp1252 e não configurar o parâmetro encoding corretamente no YAML, o unicórnio assassino converte caracteres especiais para "?" silenciosamente. Não gera erro. Não avisa. Só perde dados. Eu perdi três semanas rastreando isso porque os logs mostravam 100 por cento de sucesso. A solução é sempre rodar um comando de teste antes do lote completo: ucclean --config config.yaml --dry-run --sample 100
O dry-run processa apenas 100 linhas e exibe no terminal o que seria feito em cada campo, incluindo conversões de encoding. Isso evita surpresas.
Alternativas se o unicórnio assassino não for suficiente
Se o seu cenário envolve integração com banco de dados, limpeza em tempo real ou necessidade de rastreamento linha a linha, o unicórnio assassino não é a melhor escolha. Nesse caso, considere ferramentas como o Great Expectations, que oferece validação contínua com logs detalhados, ou o OpenRefine para limpeza manual guiada quando os dados são particularmente desorganizados. O unicórnio assassino brilha em processos batch de arquivos estáticos. Fora disso, ele fica para trás. Para downloads, o repositório oficial fica no GitHub do desenvolvedor principal, mas atenção: não há versão estável comercial. É software mantido pela comunidade, com atualizações esporádicas. Se você depende dele para produção crítica, tenha um plano B e esteja preparado para contribuir com patches ou adaptar o código internamente.
