Convertir TSV en NDJSON

Les index de recherche et les magasins de documents ne prennent pas de fichiers délimités. Elasticsearch et OpenSearch ingèrent via un endpoint bulk qui lit du JSON délimité par saut de ligne. mongoimport lit un document JSON par ligne par défaut. BigQuery a un format de chargement appelé NEWLINE_DELIMITED_JSON et n’accepte rien qui ressemble à un tableau. Aucun ne regardera un TSV.

Ce n’est pas arbitraire. Un magasin de documents contient des documents, et un document a des champs nommés et typés, ce qu’une ligne délimitée n’a pas. La conversion est donc un changement de modèle autant qu’un changement de syntaxe : chaque ligne cesse d’être une position dans une table et devient un objet qui se décrit lui-même et peut être indexé, interrogé par champ, stocké à côté de documents qui n’ont pas du tout les mêmes champs.

La sortie est un objet JSON complet par ligne et rien d’autre — pas de crochet ouvrant, pas de virgule entre les enregistrements, pas de crochet fermant. Cette absence est le format. Elle permet à un chargeur de lire une ligne, l’indexer, la jeter et passer à la suivante, sans jamais tenir le fichier entier.

Cela signifie aussi que le fichier n’est pas du JSON valide pris comme un tout, et qu’un analyseur attendant un tableau échouera à la deuxième ligne. Ce n’est pas un défaut ; c’est la propriété qui permet à un fichier de cent millions de lignes d’être chargé par un processus avec peu de mémoire. Si quelque chose en aval le refuse, vérifiez si ce consommateur voulait un tableau — auquel cas la table source devrait être convertie en JSON à la place.

La ligne d’en-tête fournit les noms de champs tels qu’écrits. « Titre du produit » reste « Titre du produit », espaces compris, et « prix (USD) » garde ses parenthèses. Rien n’est renommé ni normalisé, parce qu’un convertisseur qui réécrirait silencieusement vos noms de champs rendrait les documents chargés impossibles à réconcilier avec la source.

Plusieurs destinations sont plus difficiles que JSON. Un point dans un nom de champ est traité comme séparateur de chemin par Elasticsearch et par la notation pointée de MongoDB, donc une colonne « prix.usd » produit un champ imbriqué plutôt qu’à plat et un conflit de mapping peu après. BigQuery exige que les noms de champs commencent par une lettre ou un souligné et ne contiennent que des lettres, des chiffres et des soulignés, et rejettera le chargement sinon. Corriger la ligne d’en-tête dans la source avant la conversion tient en une édition ; corriger un million de documents après chargement ne tient pas.

JSON a des types et un TSV n’en a pas, donc l’analyseur infère. Les valeurs qui se lisent comme nombres deviennent des nombres JSON, `true` et `false` deviennent des booléens, un champ vide devient null, et tout le reste reste une chaîne. Pour un catalogue cela signifie que les prix et les stocks arrivent numériques et sont requêtables sans surcharge de mapping, ce qui est en général ce que vous voulez.

L’inférence est fausse au même endroit où elle l’est toujours : les identifiants. Un SKU « 00123 » devient le nombre 123, un ISBN sans tirets devient un grand entier, et un code écrit « 1e5 » devient 100000. Dans un index de recherche c’est pire que d’ordinaire, parce qu’un champ numérique n’est pas analysé et ne correspondra pas à une recherche de terme sur la chaîne d’origine. Préfixez ou entrez ces colonnes dans l’export, ou corrigez-les dans une passe jq sur le fichier converti avant le chargement.

La sortie est des documents uniquement. Les endpoints `_bulk` d’Elasticsearch et d’OpenSearch attendent une ligne de métadonnées avant chaque document — un petit objet nommant l’opération et habituellement l’index — donc poster ce fichier directement produit une erreur d’analyse à la deuxième ligne et un empilement de messages confus après.

C’est une seule passe pour les ajouter : `jq -c '{index:{}}, .'` sur le fichier converti intercale une ligne d’action avant chaque document, et l’endpoint prend le relais. Tout le reste sur la liste de cette page n’a pas besoin d’une telle étape. `mongoimport --type json` lit le fichier tel quel, un job de chargement BigQuery avec NEWLINE_DELIMITED_JSON le lit tel quel, et un pipeline Logstash ou d’ingest lisant des lignes le lit tel quel.

Les colonnes indexées sont en général les colonnes malaisées : descriptions produit, corps d’articles, avis, champs d’annotation. Dans un TSV ce sont précisément les valeurs qui cassent les choses — une tabulation collée ajoute une colonne, un saut de ligne termine la ligne trop tôt, et le compte de lignes du fichier cesse de s’accorder entre outils.

En JSON ce sont des contenus de chaîne ordinaires. Une tabulation est échappée en \t, un saut de ligne en \n, un guillemet est échappé, et aucun ne peut affecter la structure du document, parce que la structure vit dans la ponctuation de l’objet plutôt que dans les caractères des données. Pour un chargement de recherche c’est toute la raison pour laquelle la conversion est sûre : le texte que vous indexez est le texte qui était dans le champ, pas le texte jusqu’au premier caractère qui se trouvait être significatif.

Un champ vide est écrit `null` plutôt que comme chaîne vide, et les clés viennent de la ligne d’en-tête plutôt que des lignes en dessous : une ligne portant plus de champs que l’en-tête n’invente pas de noms pour le surplus, elle les place dans un tableau `__parsed_extra` sur ce seul document.

Les deux interagissent avec un mapping. Elasticsearch ignore un null pour inférer un type de champ, donc une colonne qui est null sur les premiers milliers de documents et numérique ensuite peut finir mappée d’après la première valeur non nulle qu’il voit — et si cette valeur est une note de bas de page plutôt qu’un nombre, chaque document ultérieur dans ce champ échouera à l’indexation. Définir le mapping explicitement avant le chargement est la correction, et lire un échantillon du fichier converti avec `head -n 100` est comment on trouve quels champs en ont besoin.

Répéter chaque nom de champ à chaque ligne rend le fichier plus gros, souvent substantiellement sur une table large aux valeurs courtes. Sur un catalogue à fort contenu textuel l’effet est atténué, parce que les descriptions dominent les octets et les noms de champs sont du bruit à côté.

Cela compte aussi moins qu’ailleurs, parce que ce fichier est un artefact de transport plutôt qu’un stockage. Il existe pour être lu une fois par un chargeur puis supprimé ; la copie durable est l’index ou la table qu’il a produit. La compression retire la plupart de la différence en transit de toute façon, et chaque destination nommée ici accepte un fichier gzippé.

Les deux moitiés tournent sur cette page : l’analyseur de TSV est du JavaScript ordinaire et l’écriture NDJSON est du JavaScript ordinaire. Aucune requête ne transporte le fichier. Un catalogue avant lancement, un jeu de données non publié ou un extrait contenant du texte client n’est copié chez un tiers pour changer de forme.

Le plafond est 100 Mo par fichier, et cent fichiers par dépôt. La table entière est tenue en mémoire avant que quoi que ce soit soit écrit, ce qui met quelques dizaines de mégaoctets confortablement à portée et un fichier proche du plafond au point où un onglet de navigateur peinera. Pour un export au-delà de 100 Mo, un lecteur en flux dans un script est le bon instrument — et comme la destination est un chargement en flux, ce script est souvent ce que vous alliez finir par écrire.

BigQuery, Redshift et Snowflake lisent tous du texte délimité directement et chargeront un TSV plus vite que des documents JSON, parce qu’ils n’ont pas à analyser un nom de champ sur chaque ligne. Si la destination est une table d’entrepôt avec un schéma déjà défini, la conversion n’apporte rien.

Parquet est la meilleure réponse à nouveau quand les mêmes données seront interrogées de manière répétée plutôt qu’ingérées une fois, puisqu’il stocke les noms de champ une fois dans un pied de page et les valeurs en colonnes typées. NDJSON gagne sa place là où la destination est réellement en forme de document — un index de recherche, un magasin de documents, un pipeline d’ingest lisant des lignes — ce qui est exactement le cas de cette page.