O que é um arquivo CSV?

CSV é um formato de texto puro que abre em qualquer editor. Ele é usado para mover dados entre programas.

A extensão é .csv e o nome por extenso é Comma-Separated Values. Os dois importam menos do que aquilo que o arquivo consegue carregar, e é disso que trata o resto desta página.

Ele remonta a 1972. A especificação é RFC 4180.

A um formato que se manteve legível por tanto tempo dá para confiar algo que você quer de volta daqui a dez anos.

Ela está publicada por inteiro, então dá para implementá-la a partir do documento em vez de por observação — é por isso que o formato aparece em tantos programas e por isso que arquivos escritos há vinte anos ainda abrem. Especificação publicada não é o mesmo que livre de royalties: quando o formato embrulha um codec, o licenciamento das patentes é uma questão à parte, que a norma não resolve.

CSV guarda o conteúdo exatamente. Salvar de novo não muda nada, então dá para abrir, editar e salvar quantas vezes você quiser sem acumular estrago — e é isso que faz dele um formato de trabalho e não de entrega.

CSV não tem sintaxe de comentário. Tudo que explica precisa morar fora do arquivo, e é bom saber disso antes de escolhê-lo para algo que uma pessoa vai editar na mão.

Microsoft Excel, LibreOffice Calc e pandas leem esse formato, e a maioria dos programas do mesmo tipo também.

Quando um arquivo não abre, o formato raramente é o problema — mais comum é o programa ser mais antigo que ele. Converter para algo mais antigo é o caminho confiável, e é para isso que serve o resto deste site.

Nenhum navegador lê o formato.

Esse é de longe o motivo mais comum para convertê-lo: não que o formato seja ruim, mas que o lugar onde você quer mostrar o arquivo não consegue lê-lo.

CSV foi feito para ser aberto e alterado. Mantenha o arquivo nesse formato enquanto o trabalho estiver em andamento e exporte a partir dele sempre que precisar de uma cópia pronta.

As reclamações que se repetem: os tipos das colunas são adivinhados na importação em vez de declarados.

Nada disso é motivo para evitar o formato. São as coisas que vale conhecer antes que uma delas te pegue de surpresa, o que é uma afirmação diferente e mais útil.

Um arquivo CSV guarda linhas e colunas como texto. Ele não carrega fórmulas, cores, largura de coluna, filtros, células mescladas, abas ou regras de validação. Também não declara que uma coluna representa dinheiro, data, quantidade ou identificador. Essa simplicidade explica por que o formato funciona como ponto de encontro entre planilhas, bancos de dados, sistemas administrativos e ferramentas de análise que não compartilham o mesmo formato interno.

A consequência aparece quando o arquivo é aberto. O programa que recebe o CSV precisa decidir onde estão as colunas e como interpretar cada valor. Uma linha como `Ana,12,05` pode ter três campos separados por vírgulas ou conter um número decimal escrito com vírgula, dependendo do separador adotado. O arquivo não guarda uma configuração regional que resolva a dúvida. Quem produz e quem lê precisam concordar sobre a convenção.

Embora o nome signifique valores separados por vírgulas, muitos arquivos com extensão `.csv` usam ponto e vírgula. Isso é comum quando a vírgula já serve como separador decimal, mas não é uma regra universal do português do Brasil. O Excel considera as configurações regionais e o separador de listas do sistema ao abrir ou salvar CSV. Outro programa, outra máquina ou uma configuração personalizada pode continuar usando vírgula.

Por isso não é seguro concluir que todo CSV brasileiro usa ponto e vírgula. Uma exportação bancária pode vir com ponto e vírgula, uma API pode fornecer vírgulas e um sistema antigo pode gerar tabulações ou barras verticais. Se o arquivo abrir inteiro em uma única coluna, o primeiro diagnóstico não deve ser “o CSV está corrompido”, mas “o leitor escolheu o separador errado”. Conferir duas ou três linhas em um editor de texto costuma revelar a resposta.

Ao ler CSV, Quinvert pode detectar automaticamente o separador. O controle também permite escolher vírgula, ponto e vírgula, tabulação ou barra vertical. A escolha manual é útil quando as linhas têm uma única coluna, quando os dados contêm vários caracteres candidatos ou quando uma exportação irregular não oferece amostra suficiente para uma detecção confiável.

A primeira linha é tratada como cabeçalho e fornece o nome das colunas. Linhas completamente vazias são ignoradas. Se o arquivo não produzir coluna alguma, a leitura é recusada em vez de gerar uma tabela vazia que pareceria uma conversão bem-sucedida. Em arquivos reais, vale conferir se o cabeçalho tem exatamente a mesma quantidade de campos das demais linhas: uma coluna sem nome ou um separador solto pode deslocar os dados sem tornar o texto obviamente ilegível.

O RFC 4180 registra a convenção mais conhecida para campos que contêm vírgulas, aspas ou quebras de linha. O campo inteiro fica entre aspas duplas, e cada aspa dupla que faça parte do conteúdo é escrita duas vezes. Assim, o endereço `Rua das Flores, 120` pode ocupar uma única coluna mesmo em um arquivo separado por vírgulas, e uma observação pode conter mais de uma linha sem criar registros novos.

Um exemplo completo seria `"Silva, Costa e Cia.","O cliente escreveu ""entregar pela manhã""."`. A primeira vírgula pertence ao nome da empresa, e as aspas duplicadas pertencem ao comentário. Separar a linha com uma operação ingênua como `split(",")` destruiria os dois campos. Quinvert usa um parser de CSV que interpreta essas regras; ainda assim, nenhuma biblioteca consegue adivinhar a intenção quando o arquivo de origem deixou uma aspa aberta ou misturou convenções incompatíveis.

CSV não possui tipos, mas Quinvert aplica tipagem dinâmica durante a leitura. Valores reconhecidos como números são convertidos em números antes de serem escritos no formato de destino. Isso é conveniente para uma coluna de quantidade, idade ou preço que será enviada a JSON, XLSX, SQL ou Parquet. O teste da conversão confirma, por exemplo, que `36` em uma coluna de idade chega ao JSON como número, e não como a string `"36"`.

Para identificadores, o mesmo comportamento exige cuidado. Um CEP escrito apenas como `01310100` pode virar `1310100`; códigos de produto como `00047` podem virar `47`. Colocar o campo entre aspas de CSV não deve ser tratado como garantia de preservação, porque as aspas delimitam o campo, mas não declaram seu tipo. CEP com hífen, CPF com pontuação e códigos com prefixo alfabético não têm aparência de número e tendem a permanecer texto, mas a saída ainda deve ser conferida antes de substituir o original.

Uma célula contendo `19,90` não informa sozinha se representa dezenove reais e noventa centavos ou dois campos. Num CSV separado por ponto e vírgula, ela pode ser preservada como um único valor textual. Num arquivo separado por vírgulas, precisa estar entre aspas para continuar em uma coluna. Mesmo assim, o formato não declara que aquela string usa a convenção decimal brasileira.

Esse detalhe pesa em relatórios financeiros, tabelas de preço e medições. Um sistema que espera ponto decimal pode manter `19,90` como texto em vez de convertê-lo para o número `19.9`. Trocar vírgula por ponto automaticamente também seria perigoso: a mesma coluna pode conter códigos, versões ou texto livre. Quando o destino precisa de valores numéricos, a interpretação regional deve ser uma decisão explícita do sistema que conhece os dados, não um palpite escondido dentro da conversão.

A extensão `.csv` não declara de forma confiável a codificação usada pelo arquivo. Em dados brasileiros, o problema aparece cedo: `João`, `São Luís`, `Açúcar` e `endereço` deixam evidente quando UTF-8 foi lido como uma página de código antiga. Se o texto já aparece como `João` antes da conversão, reorganizar as colunas não recupera os bytes originais. A exportação precisa ser aberta com a codificação correta ou produzida novamente pelo sistema de origem.

Quinvert lê o arquivo como texto no navegador e escreve as saídas textuais em UTF-8. Quando o destino é CSV, o resultado usa vírgula como separador e quebra de linha `LF`. Portanto, um CSV de entrada separado por ponto e vírgula pode gerar outro arquivo separado por vírgula depois de passar pela conversão. Isso é intencional: a opção de separador controla a leitura da origem; o escritor de CSV tem uma saída estável em vez de copiar uma convenção que talvez tenha sido apenas detectada.

O cabeçalho não é decoração. Ele vira o conjunto de chaves em uma conversão para JSON e os nomes das colunas nos demais destinos tabulares. `nome completo`, `NomeCompleto` e `nome_completo` são três chaves diferentes. Espaços extras também contam. Se duas colunas usam o mesmo título, um destino baseado em objetos não tem como representar as duas com a mesma chave sem criar uma regra adicional.

Antes de converter uma exportação de clientes, confira se a primeira linha possui nomes únicos, estáveis e compreensíveis fora do sistema que a criou. `coluna_7` pode fazer sentido para o exportador e ser inútil no banco de dados que receberá o resultado. Também vale procurar cabeçalhos vazios e delimitadores sobrando no fim da linha. Corrigir o cabeçalho na origem preserva a única informação que relaciona cada posição ao significado do campo.

Salvar uma planilha como CSV reduz uma aba a uma grade de valores. Fórmulas deixam de existir como fórmulas e passam a ser apenas o resultado exportado pelo programa que criou o arquivo. Formatação de moeda, máscaras de CPF, zeros exibidos por um formato de célula, comentários, links, gráficos e abas adicionais não têm representação no CSV. Se um zero existia somente na aparência da célula, ele pode nem chegar ao arquivo.

Isso torna CSV adequado para intercâmbio de registros, não para arquivar uma pasta de trabalho completa. Uma lista com colunas `pedido`, `data`, `valor` e `status` viaja bem quando os valores são autossuficientes. Uma planilha em que a cor da linha indica aprovação, uma fórmula calcula o saldo e uma aba escondida fornece os parâmetros perde parte essencial do significado. Para esse caso, XLSX ou ODS é uma origem mais fiel.

A matriz de dados permite usar CSV como origem para TSV, JSON, NDJSON, XLSX, SQL e Parquet. A leitura acontece no caminho de conversão executado no navegador. O arquivo é transformado primeiro em valores JavaScript e depois escrito pelo módulo apropriado ao destino. Essa etapa intermediária explica tanto a compatibilidade entre vários formatos quanto a tipagem dinâmica que pode alterar identificadores numéricos.

Cada destino resolve um problema diferente. TSV lê a tabela e a escreve novamente com tabulações entre os campos. JSON representa cada linha como um objeto formado pelo cabeçalho. NDJSON deixa um registro por linha. XLSX cria uma pasta de trabalho que programas de planilha entendem. SQL produz comandos de inserção, e Parquet armazena a tabela em formato binário orientado a colunas. Nenhum desses destinos consegue reconstruir tipos, fórmulas ou relações que nunca foram registradas no CSV.

Na direção contrária, JSON e NDJSON podem conter objetos dentro de objetos, enquanto CSV só possui linhas e colunas planas. Quinvert achata propriedades aninhadas em nomes com pontos. Um objeto como `{"cliente":{"cidade":"Recife"}}` pode produzir uma coluna `cliente.cidade`. Os testes também confirmam que uma resposta de API formada por um único array pode ser transformada diretamente em linhas e que uma coluna introduzida por registros posteriores entra no cabeçalho.

Esse achatamento é útil, mas não é reversível em todos os casos. Uma chave que já contém ponto pode ficar parecida com um caminho criado pelo conversor, arrays não cabem naturalmente em uma célula e estruturas profundas perdem a diferença entre níveis e registros relacionados. Antes de escolher CSV como destino de JSON, verifique se os dados realmente descrevem uma tabela. Quando a hierarquia tem significado, JSON ou NDJSON é um destino mais honesto.

CSV pode ser processado linha por linha por programas especializados, mas essa não é a estratégia desta conversão. Quinvert lê o texto e monta a estrutura intermediária antes de escrever o resultado. O consumo de memória cresce com o tamanho do arquivo e também com o destino: produzir JSON, XLSX ou Parquet exige manter dados e estruturas adicionais durante parte do trabalho.

Por isso o fato de um CSV ser texto não significa que qualquer tamanho será confortável em uma aba. Uma exportação que cabe com folga no disco pode pressionar a memória do navegador depois de ser transformada em milhares de objetos. Para volumes que já causam lentidão ao abrir, prefira uma ferramenta de linha de comando, um processo por streaming ou a importação direta no banco de dados. O original deve permanecer guardado até a contagem de linhas e algumas amostras da saída serem conferidas.

Comece abrindo uma cópia em um editor de texto. Identifique o separador, confira o cabeçalho e procure campos entre aspas. Escolha uma linha com nome acentuado, uma com valor vazio, uma com vírgula dentro do texto e outra com identificador iniciado por zero. Esses casos expõem quase todos os erros de codificação, separação e tipagem antes que o arquivo seja usado em produção.

Depois da conversão, compare a quantidade de registros e inspecione novamente as mesmas linhas. Verifique especialmente CEP, telefone, CPF, CNPJ, código de produto, número de conta e chaves longas. Não substitua a única cópia da origem por uma saída ainda não validada. CSV é previsível quando a convenção está clara; os problemas aparecem justamente quando um programa teve de adivinhar algo que o arquivo não sabia declarar.