Converter CSV para NDJSON

Um CSV nomeia suas colunas uma vez, no topo, e toda linha depois disso é posicional — o terceiro campo é a cidade porque o terceiro cabeçalho disse isso. O NDJSON faz o oposto: cada linha é um objeto completo carregando suas próprias chaves, então o registro número setenta mil é tão compreensível sozinho quanto o primeiro.

Essa é a troca que a conversão faz, e não é de graça. Repetir os nomes das chaves em toda linha torna o arquivo maior, às vezes consideravelmente, numa tabela de valores curtos com cabeçalhos longos. O que se ganha é que nenhuma linha depende de nenhuma outra.

O motivo comum de esta conversão ser pedida não é elegância. É ter onze exportações mensais, o sistema acrescentou um campo em abril, e não há como concatenar um arquivo de quatorze colunas com um de quinze. Juntar os CSVs deixa uma linha de cabeçalho no meio dos dados.

O NDJSON não tem esse problema. Registros com conjuntos de chaves diferentes convivem no mesmo arquivo legitimamente, e qualquer consumidor razoável — um motor de consulta, um job de carga, um script — trata uma chave ausente como ausente, não como linha quebrada.

Como um registro termina onde a linha termina, o arquivo pode ser cortado em qualquer ponto de quebra de linha e as duas metades continuam válidas. split -l 100000 produz pedaços carregáveis. head -n 1000 produz uma amostra que dá para de fato testar contra um esquema. Uma carga que falhou pode ser retomada a partir de um número de linha em vez de recomeçar do zero.

Anexar funciona pelo mesmo motivo: novos registros vão para o fim com >> e nada acima precisa ser reescrito. Fazer o equivalente com um CSV exige conferir se o cabeçalho está presente, se a ordem das colunas bate e se a última linha terminava com quebra de linha.

JSON distingue o número 7 da string "7" e um CSV não, então algo precisa decidir, e o que decide é inferência sobre o texto. Valores que se interpretam como números viram números JSON — 1e5 chega na saída como 100000 — enquanto true e false viram booleanos e o resto continua string.

A adivinhação acerta para quantidades, preços e sinalizadores e erra para identificadores. 007 vira 7, e uma vez que é um número no JSON não há como recuperar o zero à esquerda. Se a exportação contém códigos em vez de medidas, a defesa mais barata é torná-los inequívocos na origem: um prefixo, ou uma coluna já exportada como texto.

Uma célula em branco é escrita como null em vez de string vazia. Isso é uma decisão real e vale saber, porque as duas coisas não são iguais para nada que consuma o arquivo: um esquema JSON com "type": "string" rejeita null, e uma carga de banco de dados vai colocar um null onde talvez você esperasse a string vazia que viu na origem.

O que a conversão não consegue fazer é dizer qual das duas a exportação quis dizer. Um CSV tem exatamente um jeito de escrever "nada aqui", usado tanto para "este campo está em branco" quanto para "este campo não se aplica". Se a distinção importa a jusante, ela precisa ser codificada na origem antes de qualquer conversão.

O arquivo é feito para jq -c, que lê um valor por vez sem segurar o arquivo inteiro em memória. jq -r ".cidade" sobre uma exportação convertida imprime uma cidade por linha; jq -s "length" conta registros; um filtro select produz um NDJSON menor que continua sendo entrada válida para tudo mais.

O mesmo vale para qualquer coisa que leia linhas. grep sobre o arquivo bruto funciona e é honesto, porque um registro não pode se espalhar por duas linhas nem ser quebrado no meio de um match. wc -l dá a contagem exata de registros, algo pequeno até você comparar com contar linhas num CSV onde um endereço entre aspas contém uma quebra de linha.

Espere crescimento. Toda linha repete os nomes das chaves, toda string vem entre aspas, e a pontuação de um objeto é adicionada em torno dos valores. Numa tabela de códigos curtos com cabeçalhos descritivos o arquivo pode dobrar; numa tabela de campos de texto longo a diferença é pequena.

A compressão fecha a maior parte da lacuna, já que as chaves repetidas são exatamente o que um compressor faz melhor, e um NDJSON compactado costuma ficar perto de um CSV compactado dos mesmos dados. Se o tamanho em repouso é o que importa de verdade, isso é um sinal para olhar Parquet em vez disso, onde os nomes das colunas ficam guardados uma vez só num rodapé.

NDJSON é uma forma de contêiner, não um contrato. Um destino que ingere linhas JSON ainda vai ter opiniões sobre nomes de campo, formato de data e se um null é permitido numa posição — e nenhuma dessas opiniões é decidida por esta conversão.

As duas que mais pegam as pessoas são data e identificador. Uma data num CSV é texto e continua texto, então qualquer string que o sistema exportador escolheu é o que chega. Identificadores, como acima, podem ter virado números.

Ler o CSV e escrever as linhas JSON são ambos JavaScript puro, carregado por esta página sob demanda. Nenhuma requisição carrega o arquivo, então uma exportação de clientes noturna ou um extrato financeiro pode ser convertido sem virar cópia de mais ninguém.

O plano gratuito para em 100 MB por arquivo, e abaixo disso o teto é memória. A tabela inteira é montada antes de qualquer coisa ser escrita, o que coloca dezenas de megabytes confortavelmente no alcance e o último trecho até 100 MB no ponto em que uma aba do navegador começa a forçar.

Escolha um array JSON simples quando tudo vai ser carregado de uma vez por algo que espera um array — um payload de API, um fixture de teste, um arquivo de configuração. NDJSON é pior que inútil ali, porque a maioria dos interpretadores JSON vai rejeitar de cara na segunda linha.

Mantenha o CSV se o destino é uma planilha ou uma tela de importação que o nomeia. E escolha Parquet quando os mesmos dados forem consultados repetidamente em vez de ingeridos uma vez: guarda os nomes das colunas uma vez, mantém os tipos explicitamente em vez de por inferência, e é uma fração do tamanho em disco.