Converter CSV para Parquet

Tudo que um CSV sabe sobre si mesmo é uma linha de cabeçalho com nomes de coluna. Ele não diz que `valor` é decimal, que `ativo` é booleano, nem que `codigo_cliente` nunca deve ser tratado como número para conta. Cada ferramenta que lê o arquivo tem que adivinhar de novo, e cada uma adivinha de um jeito ligeiramente diferente — é por isso que o mesmo extrato carrega três formas diferentes em três lugares diferentes.

Um arquivo Parquet termina com um rodapé que guarda o esquema, o número de linhas e metadados por coluna. Um motor de consulta lê o rodapé primeiro — poucos kilobytes no fim do arquivo — e sabe o nome e o tipo de cada coluna antes de tocar em qualquer linha de dado. Essa é uma propriedade estrutural, não uma conveniência: é o que torna o formato seguro para entregar a alguém que não estava presente quando o arquivo foi gerado.

Os valores são gravados na forma binária em vez de texto decimal, então um número que ocupava onze caracteres no CSV passa a ocupar poucos bytes. Cada coluna é comprimida separadamente pelo escritor, com o algoritmo padrão dele — este site não escolhe o codec, então não é possível prometer qual é.

Numa tabela de cinquenta mil linhas e seis colunas — identificador, código de produto, cidade, quantidade, preço e uma sinalização — o Parquet gerado ficou em 301 KB, contra cerca de 1,8 MB do mesmo dado como texto separado por tabulação. É uma redução de mais ou menos seis vezes, razoável para dado operacional com códigos e categorias repetidos. Uma tabela dominada por texto livre e único vai render bem menos, porque a compressão tem menos repetição para explorar.

O tipo é inferido a partir dos valores, já que a origem não declara nada. Cada coluna é lida por inteiro: se tudo são booleanos vira BOOLEAN, se tudo são números inteiros dentro da faixa de 32 bits vira INT32, números que não são todos inteiros ou que passam desse limite viram DOUBLE, e qualquer outra coisa vira texto. Valores vazios não entram na conta, então uma coluna numérica com lacunas continua numérica.

Um único valor fora do padrão faz a coluna inteira virar texto, e isso é proposital. Se o tipo fosse tirado só da primeira linha, uma coluna que começa com números viraria inteira e todo valor não numérico mais adiante seria transformado silenciosamente em vazio — um arquivo que carrega sem reclamar e apagou linhas sem avisar. Uma coluna de texto é visível e pode ser convertida numa única expressão depois, sem perder nada.

A conversão lê o CSV com inferência de tipo, então `007` já virou o número 7 no momento em que o gravador escolhe o tipo da coluna, e o INT32 resultante é um registro fiel de um valor que já estava errado antes. O Parquet costuma levar a culpa por isso e não merece: a perda acontece na etapa de interpretar o texto, a mesma etapa que qualquer outro leitor de CSV faz.

As colunas em risco são as em que fazer conta não faz sentido nenhum — CEP, código de peça, telefone, número de conta, qualquer coisa com zero à esquerda. Se o extrato está sob seu controle, exporte essas colunas entre aspas ou com um prefixo e elas chegam intactas como texto. Se não está, confira a coluna no resultado antes de gravar o arquivo em algum lugar definitivo.

Um CSV não tem como representar uma estrutura aninhada, e se o extrato veio de uma exportação com colunas assim, cada nível vira uma coluna própria com o caminho pontuado como nome — `endereco.cidade`, `endereco.cep`. Isso vale tanto para o CSV de origem quanto para o Parquet gerado a partir dele, então o comportamento não muda entre os dois formatos.

Vale conferir os nomes de coluna no resultado antes de usar em produção, porque um esquema com pontos no nome se comporta de forma diferente em algumas ferramentas de consulta — a maioria trata sem problema, mas vale saber que o ponto ali é literal, não um separador de esquema.

Não precisa de configuração nenhuma. O DuckDB lê o arquivo direto numa cláusula FROM, o pandas lê numa chamada só, e o Spark trata como formato de tabela nativo. O arquivo começa e termina com os quatro bytes PAR1, que é como cada um desses programas reconhece o formato antes de ler o rodapé.

A primeira coisa a olhar depois de carregar é o esquema inferido, não as dez primeiras linhas. Uma coluna que você esperava ser numérica e chegou como texto está contando algo verdadeiro sobre o CSV, e é bem mais barato descobrir isso agora do que depois que o arquivo já foi cruzado com outros três e copiado para um data warehouse.

A tabela inteira fica na memória: o CSV é lido em linhas, as linhas são transpostas em colunas, e as colunas são gravadas. Dezenas de megabytes convertem sem drama, e centenas de megabytes é onde a aba do navegador começa a sofrer — um limite real, não um limite de plano, já que não há upload nem cobrança nenhuma envolvida.

Para um extrato realmente grande, o instrumento certo é o DuckDB, que lê o CSV do disco e grava o Parquet numa instrução só, sem nunca carregar o arquivo inteiro na memória. Esta página serve para o arquivo que cabe, o que é a maioria dos casos, e para quando instalar algo não é uma opção.

As duas metades rodam nesta página: o interpretador de CSV e o gravador de Parquet são bibliotecas carregadas sob demanda, e nenhum pedido leva o arquivo para fora. Um CSV a caminho de uma plataforma de dados é, muitas vezes, o artefato menos tratado de todo o fluxo — o despejo bruto antes dos cruzamentos e da mascaração — e subir esse arquivo para um conversor é exatamente a etapa que uma política de proteção de dados existe para evitar.

Também tira uma camada da conversa: não há fila, não há limite máximo de linhas e não há conta, então a única pergunta é se o arquivo cabe na memória, e isso dá para responder só olhando o tamanho dele.

Parquet é um destino ruim para qualquer coisa que uma pessoa vai ler diretamente. É binário, não é editável, e um colega sem a ferramenta certa não consegue abrir de jeito nenhum. Se o arquivo vai para uma pessoa em vez de um motor de consulta, mande o CSV ou uma planilha.

Também é o alvo errado para uma carga que acontece uma vez e depois é descartada: o custo de gravar não compensa se o arquivo nunca mais for consultado, e um carregador que lê texto delimitado direto é mais rápido de ponta a ponta nesse caso. Escolha Parquet quando o mesmo dado vai ser lido repetidas vezes, filtrado, cruzado e mantido por um bom tempo — é aí que as colunas tipadas e o esquema no rodapé começam a compensar.