Resumo: CSV parece o formato de dados mais simples possível, e é exatamente por isso que pequenas inconsistências — uma vírgula perdida dentro de um campo de texto sem aspas, um delimitador incompatível, um BOM escondido — fazem uma importação falhar ou desalinham silenciosamente as colunas. Combine este guia com Encoding Converter, Duplicate Finder, Remove Extra Spaces e Character Counter.
As regras reais do CSV estão definidas na RFC 4180, embora na prática a maioria dos CSVs reais as sigam apenas vagamente — que é exatamente a fonte da maioria dos problemas de importação.
Onde as importações CSV realmente falham
O problema central: uma vírgula é ao mesmo tempo o delimitador de coluna e um caractere que pode legitimamente aparecer dentro de um campo de texto (um endereço, uma descrição de produto com "Pequeno, Médio, Grande" dentro). A resposta da RFC 4180 é o uso de aspas — um campo contendo uma vírgula deve ser envolvido em aspas duplas, e uma aspa dupla literal dentro de um campo entre aspas é escapada duplicando-a (""). Software que exporta CSV sem seguir essa regra produz arquivos onde uma única vírgula sem aspas desloca silenciosamente cada coluna seguinte em uma posição.
Delimitadores não são universais
Separado por vírgula é a suposição padrão, mas muitos arquivos reais usam ponto e vírgula em vez disso — particularmente comum em localidades onde a vírgula já é o separador decimal para números, o que torna ambíguo reutilizá-la como delimitador de coluna. Um CSV que abre como uma única coluna não dividida em uma planilha muitas vezes está simplesmente usando o delimitador errado para a suposição daquela ferramenta, não realmente quebrado.
Codificação e o BOM invisível
Uma marca de ordem de byte (BOM) UTF-8 — três bytes invisíveis bem no início de um arquivo — é adicionada por algumas ferramentas (notavelmente o Excel na exportação) para sinalizar a codificação, mas nem todo parser a remove automaticamente. Se deixada, ela pode se anexar invisivelmente ao nome do cabeçalho da primeira coluna, então uma busca por uma coluna literalmente chamada name falha porque o cabeçalho real é name com um caractere invisível antes — um bug genuinamente difícil de perceber a olho nu.
Um fluxo de limpeza pré-importação
- Abra o arquivo bruto como texto simples primeiro (não em uma planilha, que interpreta automaticamente e pode esconder a estrutura real) para verificar o delimitador e uso de aspas reais.
- Verifique os primeiros bytes em busca de um BOM se as buscas por nome de coluna falharem misteriosamente.
- Procure especificamente por vírgulas sem aspas dentro do que deveriam ser campos de texto únicos — a causa mais comum de desalinhamento de colunas.
- Verifique uma quebra de linha final ou uma linha vazia final, que algumas ferramentas de importação contam como um registro final quebrado.
- Execute Duplicate Finder em uma coluna-chave (como um ID ou e-mail) antes de importar se registros duplicados causariam problemas posteriormente.
Erros comuns a evitar
- Presumir que todo CSV usa vírgulas — arquivos delimitados por ponto e vírgula são comuns e parecem idênticos até você tentar dividir no caractere errado.
- Editar CSV em um app de planilha, que reformata silenciosamente datas, remove zeros à esquerda, e pode recodificar texto de formas que não correspondem ao original.
- Não verificar um BOM inicial quando buscas baseadas em cabeçalho falham sem razão visível.
- Ignorar vírgulas sem aspas dentro de campos de texto livre até a importação produzir colunas visivelmente deslocadas.
A maioria das falhas de importação CSV não é realmente sobre os dados — é sobre as suposições de um parser (delimitador, codificação, uso de aspas) não correspondendo ao que o arquivo realmente contém.