Converter Parquet para JSON

Parquet é o que uma plataforma de dados entrega, e JSON é o que todo o resto consome. É nessa distância que esta conversão vive: um fixture que precisa sentar no repositório ao lado do teste que lê ele, um arquivo semente para uma API simulada local, um corpo para colar numa requisição enquanto você descobre por que um endpoint recusa, ou cinquenta linhas que você quer olhar num visualizador de JSON sem instalar o DuckDB.

Vale notar que os casos interessantes são todos pequenos. O Parquet existe para tornar tabelas muito grandes baratas de consultar, e nada disso sobrevive à viagem — o layout colunar, a compressão, as estatísticas que deixam um leitor pular grupos de linhas inteiros. O que você recebe é um documento de texto, e um documento de texto é o artefato certo para cem linhas e o errado para dez milhões.

O arquivo Parquet é transposto de volta em linhas, e essas linhas são escritas como um vetor JSON de nível superior com indentação de dois espaços e uma quebra de linha no fim. Nome de coluna vira chave de objeto exatamente como o esquema soletra, incluindo qualquer um que não seria um identificador JavaScript válido.

Não há envelope nem metadado. Se o destino espera as linhas sob um nome — `{"rows": […]}` é o formato comum — acrescente você mesmo; `jq '{rows: .}'` faz isso num passo. O tamanho do vetor é a contagem de linhas, então é também a checagem de sanidade mais rápida de que o extrato contém o que disseram que contém.

Esta é a surpresa desta página, e vale ler duas vezes. O Parquet tem tipos aninhados de verdade — LIST, STRUCT e MAP — e o leitor aqui devolve eles como objetos JavaScript, que depois são serializados em texto e colocados no campo como uma string. Uma coluna `tags` com dois valores não vira `["a","b"]` na saída. Vira `"[\"a\",\"b\"]"`, entre aspas, com as aspas internas escapadas.

Nada se perde e tudo fica um passo fora de alcance. `jq '.[0].tags[0]'` devolve um erro dizendo que uma string não tem índice; `jq '.[0].tags | fromjson | .[0]'` devolve o valor. Se o JSON vai para um fixture de teste, o movimento honesto é desembrulhar essas colunas uma vez com `jq 'map(.tags |= fromjson)'` e versionar a versão estruturada, em vez de deixar uma dupla codificação para quem ler o fixture depois descobrir sozinho.

Uma coluna de timestamp no Parquet é um inteiro tipado com uma unidade e uma marcação de fuso horário registrada no rodapé. O JSON não tem tipo de data nenhum, então cada valor é escrito como uma string ISO 8601 — `2026-03-01T08:00:00.000Z` — que é inequívoca, ordena lexicograficamente na ordem certa, e é entendida por `Date.parse`, `datetime.fromisoformat` e qualquer checagem `format: date-time` de esquema JSON.

O que se perde é a declaração. O arquivo não diz mais que a coluna é um timestamp; diz que a coluna é uma string que por acaso parece um. Qualquer coisa adiante precisa ser avisada de novo — um argumento `parse_dates`, um esquema, uma conversão. Para um fixture, isso é ótimo e explícito. Para uma carga, é mais um lugar para errar o fuso horário.

O Parquet tem um tipo inteiro de 64 bits e o número do JavaScript carrega 53 bits de precisão inteira. Em vez de arredondar em silêncio, um valor que não cabe é escrito como uma string entre aspas; um que cabe é escrito como número simples.

A troca é deliberada e é do jeito certo — um número de pedido que volta errado por um é um bug que ninguém encontra até importar, enquanto uma coluna que às vezes é número e às vezes é string ao menos é visível. Isso significa que uma coluna pode mudar de tipo no meio do arquivo, o que vai incomodar um esquema JSON rígido. Se é o seu destino, converta a coluna inteira para texto na consulta que gerou o extrato, e o JSON vai sair consistente.

Um `BYTE_ARRAY` do Parquet sem anotação UTF8 é byte, não texto, e byte não tem representação fiel em JSON. Cada valor desse tipo é escrito como uma string hexadecimal em minúsculas — dois caracteres por byte, sem separador, sem prefixo.

Hexadecimal é reversível e claramente não é texto de leitura, o motivo de escolher isso em vez de tentar decodificar. Também é o dobro do tamanho dos bytes que codifica e a metade do tamanho de nada útil, então se uma coluna binária é grande e você não precisa dela, descarte na consulta em vez de carregar pela conversão. Uma coluna de hash está bem; uma coluna de miniatura embutida não.

Um valor ausente no Parquet vira `null` no JSON, distinto de uma string vazia e distinto de zero. Isso parece banal até comparar com os destinos delimitados, onde nulo e vazio colapsam os dois em nada entre dois separadores, e nenhuma consulta depois consegue diferenciar.

Para um fixture essa diferença é o ponto inteiro. Um teste que confere a ausência de um valor precisa que a ausência seja representável, e o JSON é o único destino de texto aqui que representa isso. É também por isso que uma viagem de ida e volta pelo JSON preserva mais de um arquivo Parquet do que uma viagem pelo CSV, mesmo que nenhum dos dois carregue o esquema.

Bastante, e por três direções ao mesmo tempo. O Parquet guarda cada coluna uma vez com o tipo declarado, depois codifica valores repetidos por dicionário e comprime as páginas; o JSON repete o nome de cada coluna em cada linha, escreve todo número como dígito decimal, e esta saída indenta cada campo na própria linha.

Planeje por uma ordem de grandeza, não uma porcentagem, e mais ainda quando a tabela é larga ou os valores se repetem bastante — uma coluna de status com cinco strings distintas custa quase nada em Parquet e o comprimento inteiro em cada linha em JSON. O documento inteiro também é montado em memória como uma string só antes de poder ser salvo, o teto prático bem antes do limite gratuito de 100 MB. Aplique um `LIMIT` no extrato em vez de converter uma tabela de data warehouse inteira e torcer.

O rodapé que tornava o arquivo autodescritivo não atravessa. Nome de coluna sobrevive como chave e nada mais: não o tipo declarado, não a possibilidade de nulo, não a compressão, não as estatísticas de grupo de linhas, não o metadado chave-valor que um produtor talvez tenha escrito.

Se você tem o DuckDB, `DESCRIBE SELECT * FROM 'file.parquet'` imprime o esquema numa linha de shell e leva dez segundos, e saber quais colunas eram INT64 em vez de DOUBLE explica a maior parte do que parece estranho no JSON depois. Se não tem, converta um punhado de linhas primeiro e leia elas — o inteiro entre aspas, a string ISO e a coluna aninhada escapada dizem, cada um, qual era o tipo de origem.

Nesta aba. Um leitor de Parquet escrito em JavaScript puro é buscado na primeira vez que você usa um destes pares, e depois faz o trabalho localmente; o arquivo em si nunca é enviado a lugar nenhum, e a aba de rede durante uma conversão mostra o leitor chegando e nada saindo.

Essa distinção importa mais para este formato do que para a maioria, porque Parquet é um artefato de data warehouse. Arquivo com esta extensão é extrato de tabela de produção — cliente, pedido, evento, folha de pagamento — e chega através de uma equipe de dados que precisaria reportar um envio. Aqui não há nada para reportar.