Converter Parquet para NDJSON

Um arquivo Parquet declara o tipo de cada coluna no seu rodapé. Converta para CSV ou texto separado por tabulação e essa declaração se perde: todo valor vira caractere, e o que ler o arquivo depois infere tipos de novo — geralmente diferente, e sempre sem o benefício do esquema que estava ali do lado.

JSON tem tipos próprios: número continua número, booleano continua booleano, e nulo continua nulo. Isso não é uma diferença pequena quando o destino é um serviço ou uma fila com esquema, porque remove uma categoria inteira de erro de integração.

Este é o limite que vale conhecer antes de construir algo em cima da saída. Parquet guarda lista, struct e mapa nativamente, e essas colunas são escritas no JSON como strings contendo JSON, não como JSON aninhado de verdade. Uma coluna lista chega como "[\"a\",\"b\"]" — um registro correto e completo do valor, mas uma camada de codificação aquém de ser estrutura.

É um passe para consertar: jq -c '.tags |= fromjson' sobre o arquivo transforma esse campo num array de verdade. O que importa é saber disso, porque um campo que parece aninhado numa revisão de código e é uma string em tempo de execução é uma coisa desagradável de descobrir num teste de integração.

JSON não tem tipo de data. Uma coluna de timestamp então é escrita como string ISO 8601 — 2024-03-11T09:30:00.000Z — que toda linguagem, banco de dados e validador de esquema interpreta sem precisar de um formato declarado, e que ordena cronologicamente como texto simples.

A alternativa seria um número epoch, e é pior num registro que uma pessoa possa precisar ler: um campo com 1710149400000 é ininteligível sem saber a época e a unidade.

Parquet tem inteiro de 64 bits, e números JSON, na prática, ficam limitados ao que os leitores em cada ponta conseguem representar exatamente — para a maioria isso são 53 bits. Um valor além disso não pode ser carregado como número sem mudar.

A conversão escreve esses como string. Um valor dentro da faixa segura continua número; um fora dela vira string com cada dígito intacto. Se o destino tem esquema, declare esse campo como string e converta na chegada.

O arquivo é um objeto JSON completo por linha e nada mais — sem colchete de abertura, sem vírgula entre registros, sem colchete de fechamento. Um leitor esperando um array JSON falha na segunda linha, e isso é o formato funcionando como pretendido, não uma falha.

O que a ausência compra é que um consumidor lê uma linha, age sobre ela, descarta e segue em frente, qualquer que seja o tamanho do arquivo. Também torna a saída endereçável por linha: head -n 1000 dá uma amostra válida, split -l produz pedaços carregáveis.

É a forma comum deste trabalho. Uma tabela vive numa plataforma de dados, e algo fora dela — um índice de busca, uma fila de mensagens, um serviço sendo repovoado — fala JSON e nunca ouviu falar de Parquet. NDJSON é o formato que fica entre os dois, e não precisa de estrutura além de uma quebra de linha.

Um laço de shell lendo linhas e postando cada uma basta para um backfill pequeno. A primeira coisa a checar é o nome dos campos: uma plataforma de dados dá nomes moldados pelo pipeline que a produziu, e um serviço costuma querer outra coisa.

Um nulo numa coluna Parquet é escrito como null no JSON, preservando uma distinção que nenhum formato delimitado consegue carregar: nulo e string vazia são valores diferentes, e chegam diferentes.

Isso importa onde o destino tem esquema. Um campo declarado string vai recusar nulo a menos que seja declarado anulável, e um validador avisa em qual registro isso aconteceu, em vez de reportar um erro de análise na linha errada.

A saída é bem maior que o arquivo de origem. Toda linha repete todo nome de campo, toda string vai entre aspas, e nada da compressão, codificação por dicionário ou representação binária que deixava o Parquet pequeno sobrevive em texto.

Isso é aceitável porque este arquivo é um artefato de transporte: existe para ser lido uma vez por um consumidor e depois apagado, e a cópia durável continua sendo o Parquet.

O leitor Parquet é uma biblioteca carregada sob demanda por esta página, e o JSON é escrito ali, então nenhuma requisição carrega o arquivo. Para um extrato tirado do meio de uma plataforma — antes da agregação, antes da mascaragem — isso costuma decidir se um conversor online pode ser usado.

Toda linha é materializada antes de qualquer coisa ser escrita, então a memória é o teto. Para uma tabela grande, DuckDB lê o Parquet e escreve NDJSON numa única instrução sem manter nenhum dos dois na memória inteiro.

Se o consumidor consegue ler Parquet, deixe. Todo data warehouse, todo motor de consulta e a maioria das bibliotecas de dados modernas leem, e passar o original preserva o esquema e mantém a transferência pequena.

Converta quando o consumidor de fato só fala JSON, o que é a maioria dos serviços, filas e índices de busca. É uma divisão real e permanente — sistemas operacionais trocam registros, sistemas analíticos trocam colunas — e esta conversão é a ponte entre eles, não um substituto para nenhum dos dois.