Converter TSV para NDJSON

Índices de busca e repositórios de documentos não aceitam arquivos delimitados. Elasticsearch e OpenSearch fazem ingestão por um endpoint em lote que lê JSON delimitado por linha. A ferramenta de import do MongoDB lê um documento JSON por linha por padrão. O BigQuery tem um formato de carga chamado NEWLINE_DELIMITED_JSON e não aceita nada com formato de array. Nenhum deles vai olhar para um arquivo separado por tabulação.

Isso não é arbitrário. Um repositório de documentos guarda documentos, e um documento tem campos nomeados com tipos, o que uma linha delimitada não tem. A conversão é, portanto, uma mudança de modelo tanto quanto de sintaxe: cada linha deixa de ser uma posição numa tabela e vira um objeto autodescritivo que pode ser indexado, consultado por campo e armazenado ao lado de documentos que não têm nem os mesmos campos.

A saída é um objeto JSON completo por linha e nada mais — sem colchete de abertura, sem vírgulas entre registros, sem colchete de fechamento. Essa ausência é o formato. Ela permite que um carregador leia uma linha, indexe, descarte e siga em frente, sem nunca segurar o arquivo inteiro.

Também significa que o arquivo não é JSON válido como um todo, e um analisador esperando um array vai falhar na segunda linha. Isso não é um defeito; é a propriedade que permite que um arquivo de cem milhões de linhas seja carregado por um processo com um limite de memória pequeno. Se algo rio abaixo rejeitar isso, o que conferir é se esse consumidor queria um array, caso em que a tabela de origem deveria ser convertida para JSON em vez disso.

A linha de cabeçalho fornece os nomes de campo exatamente como escritos. `Título do produto` continua `Título do produto`, espaços inclusos, e `preço (R$)` mantém os parênteses. Nada é renomeado ou normalizado, porque um conversor que silenciosamente reescrevesse seus nomes de campo tornaria os documentos carregados impossíveis de reconciliar com a origem.

Vários destinos são mais exigentes que o JSON. Um ponto num nome de campo é tratado como separador de caminho pelo Elasticsearch e pela notação de ponto do MongoDB, então uma coluna chamada `preco.brl` produz um campo aninhado em vez de plano, e um conflito de mapeamento logo depois. O BigQuery exige que nomes de campo comecem com letra ou sublinhado e contenham só letras, dígitos e sublinhados, e recusa a carga sem isso. Corrigir a linha de cabeçalho na origem antes de converter é uma edição; corrigir um milhão de documentos depois de carregados não é.

JSON tem tipos e um arquivo separado por tabulação não tem, então o analisador infere. Valores que leem como números viram números JSON, `true` e `false` viram booleanos, um campo vazio vira null, e o resto continua string. Para um catálogo, isso significa que preços e contagens de estoque chegam numéricos e ficam agregáveis sem uma sobrescrita de mapeamento, o que geralmente é o desejado.

A inferência erra no mesmo lugar de sempre: identificadores. Um SKU `00123` vira o número 123, um ISBN sem hífens vira um inteiro grande, e um código escrito como `1e5` vira 100000. Num índice de busca isso é pior que o normal, porque um campo numérico não é analisado e não vai bater com uma consulta de termo para a string original. Prefixe ou coloque entre aspas essas colunas no export, ou corrija numa passada de `jq` sobre o arquivo convertido antes de carregar.

A saída é só documentos. Elasticsearch e OpenSearch `_bulk` esperam uma linha de metadado antes de cada documento — um objeto pequeno nomeando a operação e geralmente o índice —, então postar este arquivo direto produz um erro de análise na segunda linha e uma pilha de mensagens confusas depois.

É uma passada só para adicionar: `jq -c '{index:{}}, .'` sobre o arquivo convertido intercala uma linha de ação antes de cada documento, e o endpoint segue dali. Tudo mais na lista desta página não precisa desse passo. `mongoimport --type json` lê o arquivo como está, um job de carga do BigQuery com NEWLINE_DELIMITED_JSON lê como está, e um pipeline do Logstash ou de ingestão lendo linhas lê como está.

As colunas sendo indexadas costumam ser as incômodas: descrições de produto, corpo de artigo, texto de avaliação, campos de anotação. Num arquivo separado por tabulação, esses são exatamente os valores que quebram as coisas — uma tabulação colada acrescenta uma coluna, uma quebra de linha termina a linha cedo demais, e a contagem de linhas do arquivo para de bater com ela mesma entre ferramentas.

Em JSON são conteúdo de string comum. Uma tabulação é escapada como \t, uma quebra de linha como \n, uma aspa é escapada, e nenhuma delas pode afetar a estrutura do documento, porque a estrutura vive na pontuação do objeto, não nos caracteres do dado. Para uma carga de busca, é essa a razão inteira de a conversão ser segura: o texto que você indexa é o texto que estava no campo, não o texto até o primeiro caractere que por acaso era significativo.

Um campo vazio é escrito como `null` em vez de string vazia, e as chaves vêm da linha de cabeçalho em vez das linhas abaixo: uma linha carregando mais campos que o cabeçalho não inventa nomes para o excedente, coloca num array `__parsed_extra` só naquele documento.

Os dois interagem com um mapeamento. O Elasticsearch ignora um null para fins de inferir o tipo de um campo, então uma coluna que é null nos primeiros milhares de documentos e numérica depois pode acabar mapeada a partir do primeiro valor não nulo que ele encontrar — e se esse valor é uma nota de rodapé em vez de um número, cada documento posterior naquele campo falha na indexação. Definir o mapeamento explicitamente antes da carga é a correção, e ler uma amostra do arquivo convertido com `head -n 100` é como você descobre quais campos precisam disso.

Repetir cada nome de campo em cada linha torna o arquivo maior, muitas vezes substancialmente numa tabela larga de valores curtos. Num catálogo cheio de texto, o efeito é atenuado, porque as descrições dominam os bytes e os nomes de campo são ruído ao lado delas.

Também importa menos aqui do que importaria em outro lugar, porque este arquivo é um artefato de transporte, não um armazenamento. Ele existe para ser lido uma vez por um carregador e depois apagado; a cópia durável é o índice ou a tabela que produziu. Compressão remove a maior parte da diferença em trânsito de qualquer jeito, e todo destino nomeado aqui aceita um arquivo gzipado.

Tanto o leitor de tabulação quanto o gravador de JSON são JavaScript comum carregado por esta página, então nenhuma requisição carrega o arquivo. Um catálogo antes do lançamento, um conjunto de dados ainda não publicado ou um extrato contendo texto de cliente não é copiado a terceiros só para mudar de forma.

O teto é 100 MB por arquivo, e cem arquivos por leva. A tabela inteira é montada em memória antes de qualquer coisa ser escrita, o que deixa dezenas de megabytes confortavelmente dentro do alcance e um arquivo perto do limite no ponto em que uma aba de navegador começa a sofrer. Para um export além de 100 MB, um leitor com streaming num script é o instrumento certo — e como o destino é uma carga com streaming, esse script frequentemente é a coisa que você acabaria escrevendo de qualquer jeito.

BigQuery, Redshift e Snowflake leem texto delimitado diretamente e vão carregar um arquivo separado por tabulação mais rápido que documentos JSON, porque não precisam analisar um nome de campo em cada linha. Se o destino é uma tabela de data warehouse com esquema já definido, a conversão não está comprando nada.

Parquet é a resposta melhor de novo quando o mesmo dado vai ser consultado repetidamente em vez de ingerido uma vez, já que guarda os nomes de campo uma vez num rodapé e os valores em colunas tipadas. NDJSON se justifica onde o destino é genuinamente moldado como documento — um índice de busca, um repositório de documentos, um pipeline de ingestão lendo linhas —, que é exatamente o caso desta página.