Converter JSON para Parquet

Um arquivo Parquet carrega um esquema no rodapé: cada coluna tem um nome e exatamente um tipo, e cada linha obedece a isso. É o que permite a um motor de consulta dizer a forma de um arquivo de dois gigabytes sem ler uma linha sequer, e é a propriedade para a qual o formato existe.

Um array JSON não oferece garantia nenhuma disso. Os registros são objetos, cada um livre para ter as chaves que quiser, e nada no formato impede que o registro quarenta traga um texto num campo em que os trinta e nove anteriores traziam número. A conversão precisa fabricar o esquema que o arquivo nunca teve, e todo caso incômodo desta página vem dessa frase.

O Parquet não tem lugar para colocar um objeto dentro de uma célula, então o registro é achatado antes de ser transposto: um objeto cliente contendo cidade vira uma coluna chamada cliente.cidade, carregando o tipo que tinha no JSON. É o mesmo achatamento que os gravadores de CSV, TSV, SQL e XLSX deste site fazem, de propósito — um mesmo extrato aninhado dá os mesmos nomes de coluna independente de qual dos cinco formatos você escolher.

Vale pensar no caso de array, porque ele achata por posição, não por nome. Um array de etiquetas com dois valores vira duas colunas, etiquetas.0 e etiquetas.1, e a lista de colunas é a união de todo o arquivo — então um campo que costuma ter dois itens e ocasionalmente quarenta produz quarenta colunas, quase todas vazias na maior parte das linhas. Onde uma lista é de tamanho genuinamente variável, juntar os itens numa string única antes de converter dá um esquema mais fácil de consultar.

Onde cada registro é um objeto plano — um registro de eventos, um extrato de pedidos, uma tabela que uma API devolveu página por página — a conversão faz exatamente o que se espera, num passo só. As chaves viram colunas na ordem em que apareceram primeiro, os valores viram dado de coluna tipado, e o resultado é um arquivo que o DuckDB consulta sem preparação nenhuma.

Isso cobre boa parte dos extratos JSON reais. Eventos de análise, linhas de faturamento, envios de formulário e a maioria dos endpoints de listagem paginada são planos por natureza, porque os sistemas que os produzem estão escrevendo linhas. Um registro que aninha ainda converte — só chega mais largo, com uma coluna com ponto por folha da árvore.

Registros que discordam sobre quais chaves têm são reconciliados juntando todas elas. Um campo presente no primeiro registro e ausente no seguinte produz uma coluna com valor vazio na segunda linha, e um campo que só aparece nos últimos dez registros de um milhão ainda assim vira coluna.

Essa reconciliação lê o array inteiro antes de escrever qualquer coisa, o custo honesto de não amostrar. O benefício é que um campo raro nunca é descartado silenciosamente. Tire o esquema de uma conversão do extrato inteiro, nunca de uma amostra pequena que você testou primeiro — uma amostra de dez registros dá menos colunas do que o arquivo completo.

O JSON tem tipos de verdade, uma vantagem genuína sobre converter a partir de planilha ou CSV: um número chega como número e um booleano como booleano, sem nada inferido a partir de caractere. Booleanos viram BOOLEAN, números inteiros dentro da faixa de 32 bits viram INT32, o resto numérico vira DOUBLE, e texto continua texto.

O caso de colisão é quando os registros discordam. Um campo que é número na maioria dos registros e texto em alguns poucos — um identificador que alguns sistemas colocam entre aspas e outros não — faz a coluna inteira virar texto, com os valores numéricos escritos como texto junto. Isso é proposital: pegar o tipo do primeiro registro e zerar o resto produziria um arquivo que carrega sem reclamar e apagou valores silenciosamente.

O Parquet tem um tipo inteiro de 64 bits e esta conversão não o escreve. Os valores passam pela representação numérica do JavaScript, que carrega precisão inteira exata até 53 bits, então um valor além da faixa de 32 bits é gravado como DOUBLE em vez de reivindicar uma exatidão que já não tem.

Para identificador isso importa, e o ajuste é lá na origem. Um export de JSON que escreve referência de pedido como texto mantém o valor exato através desta conversão e chega como coluna de texto, que é o que um identificador deveria ser mesmo. Um export que escreve como número puro já perdeu precisão além de dezesseis dígitos antes de qualquer conversor tocar no arquivo.

Num teste com dezenas de milhares de registros de pedido, seis campos cada, o Parquet resultante ficou numa fração pequena do tamanho do mesmo dado como JSON compacto, e numa fração ainda menor do JSON formatado com indentação, que é como a maioria dos exports realmente chega.

A diferença não vem só da compressão. Todo registro JSON repete o nome de cada chave; num arquivo colunar o nome aparece uma vez só, no rodapé. Valores repetidos comprimem forte quando ficam juntos, então colunas de cidade e código de produto custam quase nada aqui. Espere uma economia grande em dado operacional deste tipo, e bem menor em registros dominados por texto livre e único.

Um extrato JSON costuma vir como um objeto com uma chave só guardando o array — data, results, records. Esse envelope de chave única é aberto automaticamente e o array de dentro é o que é convertido, porque é a forma que quase todo endpoint paginado devolve.

Duas chaves é onde isso para. Um arquivo no formato `{"meta": {...}, "data": [...]}` não tem um array óbvio para preferir, então o objeto inteiro vira uma linha só, e os registros são achatados por índice dentro dela: data.0.id, data.1.id, e assim por diante. O sintoma é fácil de reconhecer depois que se conhece: um Parquet de uma linha e vários milhares de colunas. Corte o arquivo até sobrar só o array antes de converter.

O DuckDB lê o arquivo direto numa cláusula FROM, o pandas numa chamada só, e o Spark trata como formato de tabela nativo. O arquivo começa e termina com os quatro bytes PAR1, o jeito de cada um desses programas reconhecer o formato.

A primeira coisa a olhar é o esquema, não as dez primeiras linhas. Duas perguntas respondem quase tudo: alguma coluna está tipada como texto quando você esperava número, e a quantidade de colunas é a que você esperava. A primeira conta qual registro discordou de tipo; a segunda conta se um campo aninhado ou um array de tamanho variável alargou o arquivo mais do que o previsto.

No navegador. O gravador de Parquet é JavaScript comum carregado sob demanda por esta página — sem WebAssembly e sem servidor — então nenhum pedido leva o extrato para lugar nenhum, e não há conta, fila nem nível de plano. O limite do plano gratuito aceita até 100 MB.

O teto real é a memória, não esse número, porque o array inteiro é interpretado, transposto em colunas e escrito, então todo o conjunto de dados existe de uma vez na memória do navegador. Dezenas de megabytes convertem sem drama; centenas de megabytes é onde a aba começa a sofrer. Passado esse ponto, um leitor de fluxo contínuo num script é o instrumento certo.