Converter Parquet para CSV

Ir na outra direção é claramente uma conversão: texto vira coluna tipada, e todo mundo espera conferir o resultado. Esta direção parece uma exportação — o dado sai, nada é comprimido, nada é inferido — e essa impressão está errada de um jeito específico e caro.

O Parquet carrega um esquema. Toda coluna tem um tipo declarado, gravado num rodapé, e um motor de consulta lê esse rodapé antes de ler qualquer linha. Um CSV carrega uma linha de cabeçalho com nomes e nada mais. Então a conversão move os valores intactos e descarta tudo que o arquivo sabia sobre eles, e a próxima ferramenta que ler o resultado vai inferir os tipos de novo a partir do texto — de um jeito provavelmente diferente do que o Parquet de fato declarava.

Booleanos chegam como "true" e "false". Números inteiros e decimais são escritos na forma decimal comum. Textos são escritos como estavam, entre aspas só onde o valor contém vírgula, aspas ou quebra de linha. Valores vazios viram campos vazios.

Nada disso é reversível de volta ao esquema original. Uma coluna que o Parquet declarava como inteiro e uma que declarava como decimal ficam parecendo dígitos com um ponto opcional, e uma coluna booleana e uma coluna de texto contendo a palavra "true" ficam indistinguíveis. Se o CSV vai ser carregado em algum lugar com esquema próprio, tire os tipos de coluna do arquivo Parquet primeiro e escreva-os na definição de carga em vez de deixar a próxima ferramenta adivinhar.

Uma coluna de data e hora é escrita como texto no formato ISO 8601, algo como 2024-03-11T09:30:00.000Z. Essa é a melhor resposta disponível num formato sem tipo de data próprio: é inequívoco sobre qual número é o mês, ordena corretamente como texto puro, e todo banco de dados e linguagem interpreta sem precisar de instrução de formato.

Ainda assim é texto. Uma coluna de data no CSV não responde a cálculo de data até que quem lê o arquivo seja instruído de que a coluna é uma data, e uma planilha aberta direto vai aplicar a própria interpretação. Se o destino é um banco de dados, declarar a coluna como data e hora no momento da carga é uma linha e preserva o significado.

O Parquet tem um tipo inteiro de 64 bits, e o JavaScript, que roda a conversão, representa números inteiros com exatidão só até 53 bits. Um valor além desse ponto não pode ser carregado como número sem perder precisão.

Em vez de arredondar, a conversão escreve como texto. Uma referência de pedido ou um identificador longo, portanto, aparece no CSV com todo dígito intacto. A alternativa, arredondar, produziria um arquivo em que um identificador fica errado por um dígito — um erro que parece um identificador válido e sobrevive por vários sistemas antes de alguém perceber.

O Parquet guarda dado aninhado nativamente: uma coluna pode ser uma lista de textos, uma estrutura com membros nomeados, ou um mapa. Uma célula de CSV guarda um valor único e não tem sintaxe para nada além disso.

A conversão escreve esses valores como JSON dentro do campo, então uma coluna de lista chega como um texto entre colchetes numa célula só, entre aspas porque o JSON contém vírgula. Isso é reversível se quem lê o arquivo interpreta o JSON, e é bem incômodo se o destino é uma planilha ou uma tela de importação simples. Se o arquivo tem coluna aninhada e o destino é uma pessoa, achate ou descarte essas colunas numa consulta antes de converter.

Espere várias vezes o tamanho, às vezes bem mais que isso. O Parquet escreve valores na forma binária, comprime cada coluna separadamente, e guarda uma coluna de valores repetidos uma vez só, com pequenas referências apontando para ela. Um CSV não tem nada disso: todo valor é escrito como caractere, em toda linha, sem compressão.

As colunas que mais encolheram na entrada são as que mais crescem na saída. Um código de país repetido ao longo de um milhão de linhas custava quase nada no arquivo Parquet e custa um milhão de cópias no CSV. Vale saber isso antes de tentar mandar o resultado por e-mail.

O CSV é UTF-8 sem marca de ordem de byte e com quebra de linha simples entre as linhas. Isso é correto para script, importador e controle de versão, e é o que faz nome acentuado aparecer bagunçado quando o arquivo é aberto com clique duplo no Windows, porque o Excel recorre à página de código do sistema quando não há marca.

Importar pelo caminho de dados externos e escolher UTF-8 evita isso, e dá a chance de marcar coluna de identificador como texto ao mesmo tempo — o que importa, porque o Excel vai aplicar a própria conversão numérica às colunas cujo tipo foi descartado há pouco. Se o destino é mesmo uma planilha, converter o arquivo Parquet direto para XLSX em vez de CSV elimina a questão da codificação e mantém os tipos.

O leitor materializa toda linha antes de escrever qualquer coisa, então a tabela inteira existe na memória de uma vez. Dezenas de megabytes de Parquet são tranquilas; lembre que é um formato comprimido, então um arquivo modesto pode se expandir para bastante texto, e o teto chega antes do que o tamanho do arquivo sugere.

Para um extrato grande, a ferramenta certa é o DuckDB, que lê o Parquet e escreve um CSV numa instrução só sem segurar nenhum dos dois na memória inteira. Também deixa você selecionar só as colunas que precisa, que costuma ser a resposta melhor mesmo — a maioria dos pedidos de "o dado como CSV" na verdade quer seis colunas dele.

O leitor de Parquet é uma biblioteca carregada sob demanda por esta página, e a escrita é JavaScript comum, então nenhum pedido leva o arquivo a lugar nenhum. Isso importa mais aqui do que na maioria dos pares: um arquivo Parquet costuma ser um artefato do meio de uma plataforma de dados, ou seja, a versão anterior à mascaração e à agregação.

Não há fila, não há conta, e não há limite de linhas além da sua própria memória. A única coisa que decide se a conversão funciona é se a tabela expandida cabe, o que dá para estimar pela contagem de linhas no rodapé.

Se o destinatário tem qualquer ferramental de dados moderno, envie o original. DuckDB, pandas, Polars, R com arrow, Spark e praticamente todo data warehouse leem Parquet direto, preservando os tipos, mantendo o arquivo pequeno e removendo uma etapa inteira em que algo pode dar errado.

Converta para CSV quando o destinatário genuinamente não consegue — um colega de finanças com uma planilha, um pedido de auditoria que nomeia o formato, uma tela de upload com lista fixa. Esses são casos reais e comuns, e esta conversão serve para eles. O que ela não deveria ser é um hábito: todo CSV produzido a partir de um Parquet é uma cópia que esqueceu o que continha.