JSONL-bestanden beheersen: structuur, use cases en belangrijkste voordelen

Een JSONL-bestand bevat één volledige JSON-waarde per regel. De officiële documentatie noemt het "het JSON Lines-tekstformaat, ook wel newline-delimited JSON genoemd." Die ene regel is de reden waarom het goed streamt, waarom het gedeeltelijke leesbewerkingen overleeft en waarom een spreadsheet het niet opent.

Wat is een JSONL-bestand?

JSON Lines is een tekstformaat voor records. De specificatie beschrijft het als "een handig formaat voor het opslaan van gestructureerde gegevens die record voor record kunnen worden verwerkt."

De documentatie is expliciet over waar het past. Het "werkt goed met unix-achtige tekstverwerkingstools en shell-pipelines," en de pagina voegt daaraan toe dat "het een geweldig formaat is voor logbestanden." Het wordt ook beschreven als "een flexibel formaat voor het doorgeven van berichten tussen samenwerkende processen."

Het contrast met gewone JSON is waar het om draait. Een JSON-array van een miljoen records is één waarde: een lezer moet het hele ding verwerken voordat de structuur compleet is. Een JSONL-bestand van een miljoen records bestaat uit een miljoen waarden, en elke regel staat op zichzelf.

Er is een tweede, nauw verwante specificatie. De NDJSON-specificatie is er direct over: "er is momenteel geen standaard voor het transporteren van instanties van JSON-tekst binnen een streamprotocol." De vermelde use-case is "het leveren van meerdere instanties van JSON-tekst via streamingprotocollen zoals TCP of UNIX Pipes."

Hoe een JSONL-bestand is gestructureerd

De drie vereisten

De JSON Lines-documentatie noemt er precies drie. De eerste is UTF-8-codering. Deze bevat een waarschuwing die is overgenomen van JSON zelf: "net als bij de JSON-standaard mag er GEEN byte order mark (U+FEFF) worden opgenomen."

De tweede is dat elke regel een geldige JSON-waarde is. De pagina merkt op dat "de meest voorkomende waarden objecten of arrays zullen zijn, maar elke JSON-waarde is toegestaan." Vervolgens wordt het grensgeval genoemd waar mensen over struikelen: "null is een geldige waarde, maar een lege regel niet."

De derde is dat het regeleinde \n is. Windows-regeleinden werken nog steeds. De opgegeven reden is mechanisch: "dit betekent dat \r\n ook wordt ondersteund, omdat omringende witruimte impliciet wordt genegeerd bij het parsen van JSON-waarden."

Wat niet in een regel mag voorkomen

Dit is de beperking die ervoor zorgt dat het formaat werkt. De NDJSON-specificatie stelt dit als een vereiste: "de JSON-teksten MOGEN GEEN regeleinden of carriage returns bevatten."

Een JSON-waarde mag normaal gesproken over meerdere regels met inspringing worden verdeeld. In een regel-gescheiden bestand kan dat niet, omdat het regeleinde de recordscheider is. Elk record moet op één fysieke regel worden geschreven.

De laatste regel en lege regels

Twee details verschillen tussen de twee specificaties, en beide zijn van belang wanneer een bestand wordt geweigerd.

Neem het afsluitende regeleinde. JSON Lines zegt dat "het opnemen van een regeleinde na de laatste JSON-waarde in een bestand ten zeerste wordt aanbevolen, maar niet verplicht is."

Over lege regels zijn de twee specificaties het niet eens. JSON Lines is streng: een lege regel is geen geldige waarde. NDJSON is soepeler en staat toe dat "de parser lege regels stilzwijgend MAG negeren," terwijl wordt vereist dat "dit gedrag MOET worden gedocumenteerd."

Extensies en mediatypen

Ook de naamgeving verschilt. JSON Lines zegt dat bestanden "kunnen worden opgeslagen met de bestandsextensie .jsonl." Over het mediatype zegt het dat het "MIME-type application/jsonl kan zijn, maar dit is nog niet gestandaardiseerd." NDJSON zegt dat het mediatype "application/x-ndjson ZOU MOETEN zijn" en de extensie ".ndjson ZOU MOETEN zijn."

Voor compressie, JSON Lines raadt stream-compressoren aan: "gzip of bzip2 worden aanbevolen om ruimte te besparen, wat resulteert in .jsonl.gz- of .jsonl.bz2-bestanden."

Eén kleine conventie is handig om te weten wanneer u een foutmelding leest. Teksteditors noemen de eerste regel "regel 1." De documentatie breidt dat uit: "de eerste waarde in een JSON Lines-bestand zou ook 'waarde 1' genoemd moeten worden."

Waar JSONL voor wordt gebruikt

U zult een .jsonl-bestand doorgaans in een van de volgende vier situaties tegenkomen.

Log- en gebeurtenisbestanden. De eigen documentatie van het formaat noemt logbestanden, en de reden is dat een schrijver regel voor regel kan toevoegen zonder iets te hoeven herschrijven.

Warehouse-ladingen. De BigQuery-documentatie van Google is een goed voorbeeld van de officiële status van het formaat. Het ondersteunt het laden van "newline-delimited JSON (ndJSON)-gegevens uit Cloud Storage," en de bestandsformaatkiezer vermeldt de optie als "JSONL (Newline delimited JSON)."

API-exports van geneste records. Gegevens die niet netjes in kolommen kunnen worden platgeslagen, behouden hun nesting per regel. Bestelregels met variabele aantallen artikelen zijn het klassieke voorbeeld.

Machine learning-datasets. Trainings- en evaluatiesets worden vaak op deze manier gedistribueerd, omdat een trainingsloop records één voor één leest.

De rode draad is streaming. Het wordt de voor de hand liggende keuze wanneer het bestand incrementeel wordt geproduceerd of incrementeel wordt geconsumeerd.

JSONL vs. JSON vs. CSV

	JSONL	JSON	CSV
Eenheid van het bestand	Eén waarde per regel	Eén waarde voor het hele bestand	Eén rij per regel
Geneste gegevens	Ja, per record	Ja	Niet standaard
Record toevoegen	Regel toevoegen	Container herschrijven	Rij toevoegen
Gedeeltelijk lezen is nuttig	Ja	Zelden	Ja
Opent in een spreadsheet	Nee	Nee	Meestal
Records kunnen qua vorm verschillen	Ja	Ja	Nee, kolommen liggen vast
Menselijk leesbaar in een editor	Ja, elk één lange regel	Ja, mits ingesprongen	Ja

De rij die voor de meeste verrassing zorgt, is de voorlaatste. Twee regels in hetzelfde JSONL-bestand kunnen verschillende sleutels bevatten. Dat is precies wat het formaat flexibel maakt, en precies wat ervoor zorgt dat een naïeve import onregelmatige kolommen oplevert.

Voor het kolomgeoriënteerde binaire alternatief behandelt de Parquet-uitleg hetzelfde gebied vanuit het opslagperspectief. Voor het eenvoudigste tabelscenario behandelt de TSV-analyse door tabs gescheiden tekst.

Belangrijkste voordelen

Append-only schrijven. Een nieuw record is een nieuwe regel. Er hoeft niets eerder in het bestand te worden gewijzigd.

Streaming lezen. Een consument kan record één verwerken voordat record twee miljoen is geschreven.

Fouttolerantie. Een afgebroken bestand is nog steeds leesbaar tot aan de laatste volledige regel. Een afgebroken JSON-array is meestal helemaal onleesbaar.

Nesting blijft behouden. Structuur die een CSV zou moeten platslaan, blijft intact binnen elk record.

Shell-vriendelijk. De documentatie schrijft dit toe aan unix-achtige tekstverwerking en shell-pipelines, omdat een regelgeoriënteerd bestand werkt met regelgeoriënteerde tools.

Warehouse-ondersteuning. De documentatie van BigQuery vermeldt de regel die het afdwingt: "elk JSON-object moet op een aparte regel in het bestand staan."

Waar JSONL ophoudt met helpen

Het format lost transport en toevoegen op. Het lost geen van de vragen op die u heeft over de inhoud.

Compressie is een echte afweging in plaats van een gratis voordeel. De documentatie van BigQuery is onomwonden over de kosten: "als u gzip-compressie gebruikt, kan BigQuery de gegevens niet parallel lezen." Er wordt aan toegevoegd dat "het laden van gecomprimeerde JSON-gegevens in BigQuery trager is dan het laden van ongecomprimeerde gegevens." De eigen pagina van het formaat raadt gzip aan om ruimte te besparen. Beide zijn waar, en ze trekken in tegenovergestelde richtingen.

Het is ook omslachtig. Elke regel herhaalt elke sleutelnaam, dus een brede recordset is aanzienlijk groter dan dezelfde gegevens in een kolomgeoriënteerd formaat.

En het zegt niets over consistentie. Records met verschillende vormen zijn toegestaan, wat betekent dat een veld halverwege een bestand geruisloos kan verdwijnen zonder dat er iets ongeldig is.

Hoe u met een JSONL-bestand werkt als u geen engineer bent

Dit is de praktische kloof. Bedrijfstools verwachten rijen en kolommen, en een .jsonl-bestand opent niet zoals een CSV dat doet.

De pragmatische route is een conversiestap. Vraag degene die het bestand heeft gemaakt om een platgeslagen CSV- of Excel-extract van de velden die u nodig heeft. Of sla het zelf plat met een JSON-compatibele tool. U verliest de nesting, wat meestal niet uitmaakt zodra u heeft besloten welke velden de analyse gebruikt.

Vanaf daar is het werk gewone analyse. De prijzenpagina van Powerdrill Bloom vermeldt uploads voor Excel, CSV, PDF en documenten, dus een platgeslagen extract kan er direct in. Vragen worden gesteld in natuurlijke taal in plaats van geschreven als query's. De CSV AI assistant behandelt dat traject, en data connectors behandelen de gevallen waarin de gegevens beter uit de bron kunnen worden opgehaald dan geëxporteerd.

Het onderscheid dat de moeite waard is om te onthouden, is dat dit een transportbeslissing is die stroomopwaarts van u is genomen. Het converteren ervan zodra het bestand op uw bureau belandt, is normaal, geen noodoplossing.

Conclusie

JSONL is een tekstformaat met één regel: één volledige JSON-waarde per regel, en geen regeleinden binnen een waarde. Die regel levert toevoegbaarheid, streaming en tolerantie voor gedeeltelijk lezen op, wat de reden is waarom logbestanden en warehouse-ladingen er standaard gebruik van maken.

Wat het niet oplevert, is een tabel. Op het moment dat het bestand iemand bereikt die antwoorden nodig heeft in plaats van een pipeline, is de nuttige volgende stap een platgeslagen extract en een vraag.

Als dat is waar u zich bevindt, probeer dan Powerdrill Bloom met het geconverteerde bestand en begin met het omzetten ervan in een grafiek.

Veelgestelde vragen

Waar wordt een JSONL-bestand voor gebruikt?

Het wordt gebruikt voor recordstreams: logbestanden, export van gebeurtenissen, warehouse-ladingen en machine learning-datasets. De documentatie van het formaat noemt specifiek logbestanden en shell-pipelines. De gemeenschappelijke factor is dat records één voor één worden geschreven of gelezen.

Wat is het verschil tussen JSONL en NDJSON?

Ze beschrijven hetzelfde idee met ander papierwerk. JSON Lines gebruikt de extensie .jsonl en merkt op dat application/jsonl nog niet gestandaardiseerd is. NDJSON specificeert .ndjson en application/x-ndjson, en staat parsers toe om lege regels te negeren.

Kan ik een JSONL-bestand openen in Excel?

Niet door erop te dubbelklikken, omdat elke regel een JSON-waarde is in plaats van een rij cellen. De gebruikelijke aanpak is om eerst de velden die u nodig heeft plat te slaan naar CSV of Excel, of een tool te gebruiken die het formaat rechtstreeks leest.

Waarom kan een record in JSONL niet over meerdere regels worden verdeeld?

Omdat het regeleinde het scheidingsteken voor records is. De NDJSON-specificatie stelt dat "de JSON-teksten GEEN regeleinden of carriage returns MOGEN bevatten." Prachtig opgemaakte (pretty-printed) JSON moet daarom worden samengevouwen tot één regel per record.

Is een lege regel toegestaan in een JSONL-bestand?

De twee specificaties verschillen. JSON Lines stelt dat "null een geldige waarde is, maar een lege regel niet." NDJSON staat een parser toe om lege regels stilzwijgend te negeren, mits dat gedrag gedocumenteerd is.