Trabalhar com arquivos CSV sem quebrá-los

Vírgulas dentro dos valores e como as aspas funcionam

No momento em que um valor contém o delimitador, o formato precisa de um escape, e a convenção é envolver o campo em aspas duplas. Uma aspa dentro de um campo entre aspas é então escrita duas vezes. É por isso que um campo de nome com Smith, John aparece como "Smith, John" e por que um valor com aspas as duplica — não é erro de digitação, é a regra de escape.

Dividir uma linha de CSV pelas vírgulas, portanto, não funciona, por mais tentador que seja. Um analisador correto acompanha se está dentro de um campo entre aspas, e esses campos podem conter legalmente vírgulas, aspas e até quebras de linha. Se um arquivo ganha colunas de repente no meio do caminho, a causa é quase sempre um delimitador sem escape dentro de um valor.

O delimitador nem sempre é vírgula

Em localidades onde a vírgula é o separador decimal, planilhas costumam escrever CSV com ponto e vírgula, então um arquivo que abre perfeitamente em uma máquina cai em uma única coluna em outra. Tabulações também são comuns e são mais seguras justamente porque raramente aparecem dentro dos valores.

Como o delimitador não é declarado em lugar nenhum do arquivo, as ferramentas precisam adivinhá-lo, geralmente testando candidatos e vendo qual produz uma contagem de colunas consistente. Quando uma importação dá errado, checar o delimitador é a coisa mais rápida de descartar — e quando você controla a saída, dados separados por tabulação evitam toda essa classe de problema.

Codificação e a planilha que quer um BOM

Um texto que aparece como é onde deveria haver é é um arquivo UTF-8 lido como uma codificação antiga de um byte. O CSV não carrega declaração de codificação, então o leitor precisa ser informado ou precisa adivinhar, e adivinhar errado embaralha todos os caracteres não ASCII deixando a estrutura intacta — por isso o dano frequentemente sobrevive até dentro do banco de dados.

O culpado de sempre é o Excel: em muitos sistemas ele assume uma página de código antiga a menos que o arquivo comece com uma marca de ordem de bytes UTF-8. Escrever o BOM faz os acentuados abrirem corretamente lá, ao custo de alguns bytes invisíveis no início que alguns analisadores estritos vão devolver como parte do nome da primeira coluna. Saber disso antes economiza meia hora de confusão.

Valores que a planilha reescreve em silêncio

CSV não tem tipos — tudo é texto — então quem lê decide o que as coisas significam, e planilhas são agressivas nisso. Zeros à esquerda somem quando um CEP ou um código de produto é lido como número. Identificadores longos viram notação científica. Cadeias que parecem datas são reformatadas conforme a localidade da máquina, e é assim que o mesmo arquivo produz resultados diferentes em dois escritórios.

O caminho seguro é manter essas colunas como texto no momento da importação, e não consertá-las depois, porque os dígitos originais já se foram quando a conversão acontece. Para tudo em que os caracteres exatos importam — identificadores, telefones, códigos — trate a detecção automática de tipos como algo a desligar, não a corrigir depois.

Levar o CSV para outros formatos

Converter para JSON dá tipos reais e aninhamento, o que torna os dados bem mais fáceis de validar — mas também obriga a resolver explicitamente as ambiguidades acima, então vale fazer cedo em vez de tarde. No sentido inverso, ao gerar inserts SQL a partir de um CSV, a mesma questão de escape volta de forma mais perigosa: aspas dentro dos valores precisam ser escapadas para SQL, não para CSV.

Uma checagem rápida antes de confiar em qualquer CSV:

• Confirme o delimitador — vírgula, ponto e vírgula ou tabulação — antes de analisar.
• Confirme a codificação e adicione um BOM se o arquivo for para o Excel.
• Nunca divida pelo delimitador de forma ingênua; respeite os campos entre aspas.
• Importe colunas de identificadores como texto para preservar zeros à esquerda.
• Confira a contagem de linhas e colunas após a conversão, não apenas as primeiras linhas.