Opanowanie plików JSONL: struktura, przypadki użycia i kluczowe zalety

Plik JSONL zawiera jedną pełną wartość JSON w każdym wierszu. Oficjalna dokumentacja nazywa go „formatem tekstowym JSON Lines, zwanym również JSON rozdzielanym nowym wierszem”. Ta jedna reguła wyjaśnia, dlaczego dobrze sprawdza się w strumieniowaniu, dlaczego radzi sobie z częściowym odczytem i dlaczego arkusz kalkulacyjny go nie otworzy.

Czym jest plik JSONL?

JSON Lines to format tekstowy przeznaczony do przechowywania rekordów. Specyfikacja opisuje go jako „wygodny format do przechowywania danych strukturyzowanych, które mogą być przetwarzane po jednym rekordzie na raz”.

Dokumentacja jasno określa jego zastosowanie. „Dobrze współpracuje z narzędziami do przetwarzania tekstu w stylu systemu Unix oraz potokami powłoki”, a na stronie dodano, że „to świetny format dla plików dziennika”. Jest również opisywany jako „elastyczny format do przekazywania komunikatów między współpracującymi procesami”.

Kluczowa jest tu różnica w stosunku do zwykłego JSON. Tablica JSON zawierająca milion rekordów to jedna wartość: czytnik musi przetworzyć całość, zanim struktura będzie kompletna. Plik JSONL z milionem rekordów to milion wartości, a każdy wiersz stanowi niezależną całość.

Istnieje druga, ściśle powiązana specyfikacja. Specyfikacja NDJSON mówi o tym wprost: „obecnie nie ma standardu przesyłania instancji tekstu JSON w ramach protokołu strumieniowego”. Jako jej zastosowanie wskazano „dostarczanie wielu instancji tekstu JSON za pośrednictwem protokołów strumieniowych, takich jak TCP lub potoki UNIX”.

Jak zbudowany jest plik JSONL

Trzy wymagania

Dokumentacja JSON Lines wymienia dokładnie trzy. Pierwszym z nich jest kodowanie UTF-8. Wiąże się ono z zastrzeżeniem zapożyczonym z samego standardu JSON: „podobnie jak w standardzie JSON, znacznik kolejności bajtów (BOM, U+FEFF) NIE może być dołączany”.

Drugim jest to, że każdy wiersz musi być prawidłową wartością JSON. Na stronie zaznaczono, że „najczęstszymi wartościami będą obiekty lub tablice, ale dozwolona jest dowolna wartość JSON”. Następnie podano przypadek graniczny, który często sprawia problemy: „null jest prawidłową wartością, ale pusta linia już nie”.

Trzecim jest to, że znakiem końca wiersza jest \n. Końce wierszy systemu Windows również działają. Podany powód ma charakter techniczny: „oznacza to, że \r\n jest również obsługiwane, ponieważ otaczające białe znaki są niejawnie ignorowane podczas analizowania wartości JSON”.

Co nie może pojawić się wewnątrz wiersza

To właśnie to ograniczenie sprawia, że ten format działa. Specyfikacja NDJSON określa to jako wymóg: „teksty JSON NIE MOGĄ zawierać znaków nowego wiersza ani powrotu karetki”.

Zwykle wartość JSON może zajmować wiele wierszy dzięki wcięciom. W pliku rozdzielanym nowym wierszem jest to niemożliwe, ponieważ znak nowego wiersza służy jako separator rekordów. Każdy rekord musi być zapisany w jednej fizycznej linii.

Ostatni wiersz i puste linie

Dwie specyfikacje różnią się dwoma szczegółami i oba mają znaczenie, gdy plik zostanie odrzucony.

Weźmy na przykład końcowy znak nowego wiersza. JSON Lines podaje, że „dołączenie znaku końca wiersza po ostatniej wartości JSON w pliku jest zdecydowanie zalecane, ale nie wymagane”.

W kwestii pustych linii obie specyfikacje się różnią. JSON Lines jest rygorystyczny: pusta linia nie jest prawidłową wartością. NDJSON jest bardziej liberalny, dopuszczając, że „parser MOŻE po cichu ignorować puste linie”, wymagając jednocześnie, aby „takie zachowanie MUSIAŁO być udokumentowane”.

Rozszerzenia i typy mediów

Nazewnictwo również się różni. JSON Lines podaje, że pliki „mogą być zapisywane z rozszerzeniem .jsonl”. W przypadku typu mediów stwierdza, że „typ MIME może mieć postać application/jsonl, ale nie jest to jeszcze ustandaryzowane”. NDJSON wskazuje, że typem mediów „POWINIEN być application/x-ndjson”, a rozszerzeniem „POWINNO być .ndjson”.

W przypadku kompresji JSON Lines zaleca kompresory strumieniowe: „w celu zaoszczędzenia miejsca zaleca się stosowanie gzip lub bzip2, co daje pliki .jsonl.gz lub .jsonl.bz2”.

Podczas czytania komunikatów o błędach warto znać pewną drobną konwencję. Edytory tekstu nazywają pierwszy wiersz „linią 1”. Dokumentacja idzie o krok dalej: „pierwsza wartość w pliku JSON Lines powinna być również nazywana 'wartością 1'”.

Do czego służy JSONL

Z plikiem .jsonl najczęściej spotkasz się w jednej z czterech sytuacji.

Pliki dzienników i zdarzeń. Sama dokumentacja formatu wskazuje na pliki dziennika, a powodem jest to, że program zapisujący może dodawać po jednym wierszu na raz bez konieczności ponownego zapisywania czegokolwiek.

Zasilanie hurtowni danych. Dokumentacja usługi BigQuery firmy Google jest dobrym przykładem oficjalnego statusu tego formatu. Obsługuje ona ładowanie „danych JSON rozdzielanych nowym wierszem (ndJSON) z Cloud Storage”, a w oknie wyboru formatu pliku opcja ta widnieje jako „JSONL (Newline delimited JSON)”.

Eksporty zagnieżdżonych rekordów z API. Dane, których nie da się łatwo spłaszczyć do postaci kolumn, zachowują swoją strukturę zagnieżdżoną w każdym wierszu. Klasycznym przykładem są pozycje zamówień o zmiennej liczbie elementów.

Zbiory danych do uczenia maszynowego. Zbiory treningowe i testowe są powszechnie dystrybuowane w ten sposób, ponieważ pętla ucząca odczytuje rekordy pojedynczo.

Wspólnym mianownikiem jest strumieniowanie. Staje się ono oczywistym wyborem, gdy plik jest tworzony lub przetwarzany przyrostowo.

JSONL kontra JSON kontra CSV

	JSONL	JSON	CSV
Jednostka pliku	Jedna wartość na wiersz	Jedna wartość dla całego pliku	Jeden wiersz na linię
Dane zagnieżdżone	Tak, dla każdego rekordu	Tak	Brak natywnej obsługi
Dodawanie rekordu	Dodanie wiersza	Przepisanie całego kontenera	Dodanie wiersza
Przydatność częściowego odczytu	Tak	Rzadko	Tak
Otwieranie w arkuszu kalkulacyjnym	Nie	Nie	Zazwyczaj
Rekordy mogą mieć różną strukturę	Tak	Tak	Nie, kolumny są stałe
Czytelność dla człowieka w edytorze	Tak, każdy jako jedna długa linia	Tak, przy zastosowaniu wcięć	Tak

Wierszem, który budzi największe zaskoczenie, jest przedostatni. Dwa wiersze w tym samym pliku JSONL mogą zawierać różne klucze. To właśnie ta cecha zapewnia elastyczność formatu i jednocześnie sprawia, że zwykły import może skutkować nieregularnymi kolumnami.

Jeśli chodzi o binarną alternatywę zorientowaną kolumnowo, przewodnik po Parquet omawia te same zagadnienia od strony przechowywania danych. W najprostszym przypadku tabelarycznym, analiza TSV opisuje tekst rozdzielany tabulatorami.

Główne zalety

Zapis wyłącznie przez dołączanie. Nowy rekord to nowy wiersz. Nic, co zostało zapisane wcześniej w pliku, nie musi ulec zmianie.

Odczyt strumieniowy. Odbiorca może przetworzyć pierwszy rekord, zanim dwumilionowy rekord zostanie w ogóle zapisany.

Odporność na błędy. Przerwany plik nadal można odczytać aż do ostatniego kompletnego wiersza. Przerwana tablica JSON jest zazwyczaj całkowicie nieczytelna.

Zachowanie zagnieżdżeń. Struktura, którą w formacie CSV trzeba by spłaszczyć, pozostaje nienaruszona wewnątrz każdego rekordu.

Przyjazny dla powłoki systemowej. Dokumentacja przypisuje to przetwarzaniu tekstu w stylu systemu Unix i potokom powłoki, ponieważ plik zorientowany liniowo doskonale współpracuje z narzędziami operującymi na wierszach.

Wsparcie dla hurtowni danych. Dokumentacja usługi BigQuery określa zasadę, którą egzekwuje: „każdy obiekt JSON musi znajdować się w osobnym wierszu pliku”.

Gdzie JSONL przestaje pomagać

Format ten rozwiązuje kwestie przesyłania i dołączania danych. Nie odpowiada jednak na żadne pytania dotyczące samej zawartości.

Kompresja wiąże się z realnym kompromisem, a nie z darmowym zyskiem. Dokumentacja usługi BigQuery bez ogródek mówi o kosztach: „jeśli używasz kompresji gzip, BigQuery nie może odczytywać danych równolegle”. Dodaje również, że „ładowanie skompresowanych danych JSON do BigQuery jest wolniejsze niż ładowanie danych nieskompresowanych”. Z kolei oficjalna strona formatu zaleca gzip w celu zaoszczędzenia miejsca. Oba te stwierdzenia są prawdziwe i prowadzą do sprzecznych wniosków.

Format ten jest również bardzo gadatliwy. Każdy wiersz powtarza każdą nazwę klucza, przez co szeroki zestaw rekordów jest znacznie większy niż te same dane zapisane w formacie kolumnowym.

Nie gwarantuje on również spójności. Dozwolone są rekordy o różnych strukturach, co oznacza, że jakieś pole może po cichu przestać pojawiać się w połowie pliku, nie powodując przy tym żadnego błędu walidacji.

Jak pracować z plikiem JSONL, jeśli nie jesteś inżynierem

Na tym polega praktyczna trudność. Narzędzia biznesowe oczekują wierszy i kolumn, a pliku .jsonl nie da się otworzyć tak prosto jak pliku CSV.

Praktycznym rozwiązaniem jest etap konwersji. Poproś osobę, która wygenerowała plik, o spłaszczony plik CSV lub wyciąg do programu Excel zawierający potrzebne pola. Możesz też spłaszczyć go samodzielnie za pomocą dowolnego narzędzia obsługującego format JSON. Stracisz wtedy zagnieżdżenia, co zazwyczaj nie ma znaczenia, gdy już zdecydujesz, które pola będą potrzebne do analizy.

Od tego momentu praca sprowadza się do zwykłej analizy. Strona z cennikiem Powerdrill Bloom wymienia możliwość przesyłania plików Excel, CSV, PDF oraz dokumentów, więc spłaszczony wyciąg można zaimportować bezpośrednio. Pytania zadaje się w języku naturalnym, a nie w formie pisanych zapytań. Asystent AI dla plików CSV obsługuje tę ścieżkę, a konektory danych sprawdzają się w przypadkach, gdy dane lepiej pobierać bezpośrednio ze źródła niż eksportować.

Warto pamiętać o tym, że wybór tego formatu to decyzja dotycząca transportu danych, podjęta na wcześniejszym etapie. Konwersja na inny format, gdy plik trafi już na Twoje biurko, jest czymś zupełnie normalnym, a nie rozwiązaniem tymczasowym.

Podsumowanie

JSONL to format tekstowy opierający się na jednej zasadzie: jedna pełna wartość JSON na wiersz i brak znaków nowego wiersza wewnątrz wartości. Reguła ta zapewnia możliwość łatwego dołączania danych, strumieniowania oraz odporność na częściowy odczyt, dlatego logi i zasilanie hurtowni danych domyślnie z niego korzystają.

Nie otrzymujemy jednak w ten sposób tabeli. W momencie, gdy plik trafia do kogoś, kto potrzebuje odpowiedzi, a nie potoku danych, najlepszym kolejnym krokiem jest przygotowanie spłaszczonego wyciągu i zadanie pytania.

Jeśli właśnie w takiej sytuacji się znajdujesz, wypróbuj Powerdrill Bloom z przekonwertowanym plikiem i zacznij od przekształcenia go w wykres.

Najczęściej zadawane pytania

Do czego służy plik JSONL?

Służy do obsługi strumieni rekordów: plików dziennika, eksportu zdarzeń, zasilania hurtowni danych oraz zbiorów danych do uczenia maszynowego. Dokumentacja formatu wskazuje w szczególności na pliki dziennika i potoki powłoki. Wspólnym mianownikiem jest to, że rekordy są zapisywane lub odczytywane pojedynczo.

Jaka jest różnica między JSONL a NDJSON?

Opisują tę samą koncepcję w nieco inny sposób. JSON Lines korzysta z rozszerzenia .jsonl i wskazuje, że typ application/jsonl nie jest jeszcze ustandaryzowany. NDJSON określa rozszerzenie .ndjson oraz typ application/x-ndjson, a także pozwala parserom na ignorowanie pustych linii.

Czy mogę otworzyć plik JSONL w programie Excel?

Nie poprzez dwukrotne kliknięcie, ponieważ każdy wiersz to wartość JSON, a nie rząd komórek. Zwykle najpierw spłaszcza się potrzebne pola do formatu CSV lub Excel, bądź też korzysta się z narzędzia, które bezpośrednio odczytuje ten format.

Dlaczego rekord w formacie JSONL nie może zajmować wielu wierszy?

Ponieważ znak nowego wiersza służy jako separator rekordów. Specyfikacja NDJSON określa, że „teksty JSON NIE MOGĄ zawierać znaków nowego wiersza ani powrotu karetki”. Sformatowany, czytelny dla człowieka kod JSON (pretty-printed) musi więc zostać skompresowany do jednego wiersza na rekord.

Czy pusta linia jest dozwolona w pliku JSONL?

Obie specyfikacje różnią się w tej kwestii. JSON Lines stwierdza, że „null jest prawidłową wartością, ale pusta linia już nie”. NDJSON pozwala parserowi po cichu ignorować puste linie, pod warunkiem, że takie zachowanie zostanie udokumentowane.