Convertire NDJSON in TSV

Si guardi cosa contiene davvero un record di evento. Un percorso di richiesta con una stringa di query. Uno user agent, che non è altro che virgole e parentesi. Un messaggio d'errore che cita un valore. Un indirizzo postale. Si mandi questo a CSV e una grossa parte di ogni riga finisce tra virgolette, perché il delimitatore appare dentro i dati su quasi ogni riga.

Le tabulazioni quasi mai appaiono dentro quei valori, quindi la maggior parte dei campi viene scritta nuda e il file resta posizionale — la colonna tre è davvero tra il secondo e il terzo carattere di tabulazione. È la proprietà di cui parla il resto di questa pagina, ed è anche la proprietà che una manciata di campi può togliere silenziosamente.

Vale la pena essere precisi su cosa fa lo scrittore, perché tutto l'appeal di un file separato da tab è che gli strumenti che lo leggono possono essere grezzi. Un valore contenente una tabulazione viene avvolto in virgolette doppie. Un valore contenente una virgoletta doppia viene avvolto, con le virgolette interne raddoppiate. Un valore contenente un a capo viene avvolto. Tutto il resto, virgole incluse, viene scritto così com'è.

È la convenzione RFC 4180 con una tabulazione al posto della virgola, e non è la definizione IANA di valori separati da tabulazione, che vieta le tabulazioni dentro i campi invece di sfuggirle. La conseguenza pratica è che `cut -f4` e `awk -F$'\t'` sono corretti finché un messaggio di log non contiene una tabulazione, a quel punto quella riga guadagna un campo e ogni colonna dopo la quarta si sposta di uno, solo su quella riga. Nulla dà errore. Se i propri campi possono portare testo incollato — e i messaggi di log possono — si valida prima di fidarsi di una lettura posizionale, o si usa un lettore che capisce le virgolette.

Le colonne sono l'unione di ogni chiave vista ovunque nel file, nell'ordine in cui ogni chiave è apparsa per prima. È la risposta corretta per una sorgente dove nulla obbliga la seconda riga a portare le chiavi della prima, ed è la cosa singolarmente più importante da capire prima di automatizzare questa conversione.

Significa che l'ordine delle colonne è una proprietà dei dati piuttosto che del formato. Un'esportazione notturna in cui il primo record d'errore capita di arrivare alla riga 12 oggi e alla riga 40.000 domani produce due file le cui colonne sono in ordini diversi. La riga di intestazione è corretta in entrambi. Una pipeline che legge per nome va bene; una pipeline che legge per posizione è sbagliata il secondo giorno e non ne dà alcun segno.

Il rimedio è smettere di lasciare che sia il file a decidere. Si proietta i record a un insieme fisso di chiavi prima di convertire — `jq -c '{ts, level, service, msg}'` dà a ogni riga le stesse quattro chiavi nello stesso ordine, e la conversione ha quindi un unico layout di colonne possibile qualunque cosa contenesse la sorgente.

Questo risolve anche il problema largo e sparso allo stesso tempo. Un'esportazione mista di eventi convertita intera produce una colonna per ogni campo che qualsiasi tipo di evento abbia mai portato, la maggior parte vuote sulla maggior parte delle righe; proiettare prima dà una tabella stretta senza celle vuote. Se non si può proiettare, almeno si verifica: si legge la riga di intestazione nella pipeline e si fallisce rumorosamente se non è quella attesa, invece di lasciare che `cut -f3` restituisca il campo sbagliato per un mese.

I log strutturati si nidificano — un oggetto `request` con un metodo e un percorso, un oggetto `user` con un identificatore, un blocco `context` con un id di traccia. Ogni foglia ottiene una colonna nominata per il suo percorso: `request.method`, `user.id`, `context.trace_id`. Una colonna per ogni valore foglia, senza eccezioni.

Un punto in un nome di colonna è innocuo per `cut` e `awk`, che non guardano mai l'intestazione, e scomodo ovunque altrove: richiede virgolette in SQL, e non è un identificatore legale nella maggior parte dei caricatori. Se il TSV va in una tabella, si rinomina durante il passo di proiezione piuttosto che dopo — `jq -c '{method: .request.method}'` produce il nome di colonna voluto e risparmia un ALTER più tardi.

PostgreSQL è quello che richiede attenzione, perché il suo formato testo predefinito per `COPY` usa escape con backslash invece di virgolette e leggerà un campo quotato letteralmente, virgolette incluse. La forma che corrisponde a ciò che è stato scritto è `\copy events FROM 'out.tsv' WITH (FORMAT csv, DELIMITER E'\t', HEADER true)` — regole CSV, delimitatore tabulazione.

DuckDB lo legge con `read_csv('out.tsv', delim='\t', header=true)` e deduce i tipi da un campione, il che è comodo ed è anche come una colonna di identificatori perde i suoi zeri iniziali; si passa una mappa `types` esplicita per tutto ciò che deve restare testo. `.import --csv` di SQLite richiede il separatore impostato con `.separator "\t"` prima. In tutti e tre il campo vuoto arriva come stringa vuota piuttosto che NULL a meno che non si dica diversamente, il che è il problema della prossima sezione.

Un null JSON e una stringa vuota JSON diventano entrambi nulla tra due tabulazioni, e non c'è modo di distinguerli dopo. Non è che lo scrittore sia stato negligente — un file di testo delimitato non ha un terzo stato dove metterli.

Se questo conta dipende dalla domanda che si sta ponendo. Contare quanti eventi mancavano di un `user_id` è una query diversa da contare quanti ne portavano uno vuoto, e dopo questa conversione entrambe danno la stessa risposta. Se la distinzione è portante, si codifica prima di convertire — `jq -c '.user_id //= "«null»"'` è brutto e non ambiguo — o si manda l'esportazione a Parquet invece, dove null è uno stato reale e la colonna mantiene il suo tipo.

Di solito meno di quanto fosse. Ogni riga della sorgente ripete i nomi delle sue chiavi; il TSV le scrive una volta nell'intestazione e poi solo i valori, quindi un insieme di record stretto spesso si riduce notevolmente. Uno largo e sparso va nella direzione opposta, perché ogni riga deve portare una tabulazione per ogni colonna incluse quelle in cui non ha nulla.

Il tetto gratuito è 100 MB per file e l'intera esportazione viene letta in record prima che le colonne possano essere determinate, quindi la memoria piuttosto che il limite è ciò che si incontra per primo. NDJSON si divide in sicurezza a qualsiasi confine di riga, quindi `split -l 500000` dà file che convertono ciascuno in modo pulito — ma si noti che file divisi convertiti separatamente possono essere in disaccordo sull'ordine delle colonne esattamente per il motivo di cui sopra, un altro argomento per proiettare prima.

Se una persona lo aprirà, lo si manda a CSV o XLSX invece — un foglio di calcolo gestisce un CSV senza che gli si dica quale sia il separatore, e una cartella di lavoro mantiene le colonne identificative come testo. Se va in un data warehouse o va conservato, Parquet è più piccolo, tipizzato e non ha affatto un problema di ordine delle colonne.

TSV si guadagna il suo posto in esattamente una situazione: la destinazione è un programma che divide su un carattere, e si vuole che il file sia leggibile con `head` mentre si costruisce il comando. È una situazione reale e comune. Non è la stessa di "mi serve in Excel", e scegliere TSV per quel motivo è come ci si ritrova con un file che il proprio foglio di calcolo importa in una sola colonna.

Puro JavaScript in questa scheda. Nessun caricamento, nessun download di motore, nessun account, nessuna quota giornaliera — e la scheda Rete durante una conversione è il modo per confermarlo invece di fidarsi di questa frase.

Le esportazioni di eventi di produzione sono il materiale per cui questa coppia esiste, e portano indirizzi IP, identificatori di sessione, percorsi di richiesta e user agent. Darne una a un convertitore ospitato è un trasferimento di dati a una terza parte qualunque cosa quel convertitore prometta. Qui non c'è alcun trasferimento su cui ragionare.