JSONL Dosyalarında Uzmanlaşma: Yapı, Kullanım Durumları ve Temel Avantajlar

Bir JSONL dosyası, satır başına bir tam JSON değeri barındırır. Resmi dokümantasyon bunu "yeni satırla sınırlandırılmış JSON olarak da adlandırılan JSON Lines metin formatı" olarak adlandırır. Bu tek kural; dosyanın neden kolayca akışa alınabildiğini, neden kısmi okumalardan zarar görmeden çıkabildiğini ve bir e-tablonun bunu neden açamadığını açıklar.

JSONL dosyası nedir?

JSON Lines, kayıtlar için bir metin formatıdır. Teknik özellikler bunu "her seferinde bir kayıt olacak şekilde işlenebilen yapılandırılmış verileri depolamak için kullanışlı bir format" olarak tanımlar.

Dokümantasyon, bu formatın nereye uygun olduğu konusunda oldukça açıktır. Formatın "Unix tarzı metin işleme araçları ve kabuk boru hatları (shell pipelines) ile iyi çalıştığını" belirtir ve sayfa, "günlük (log) dosyaları için harika bir format" olduğunu ekler. Ayrıca "birlikte çalışan süreçler arasında mesaj iletmek için esnek bir format" olarak da tanımlanır.

Düz JSON ile arasındaki fark tam olarak buradadır. Bir milyon kayıttan oluşan bir JSON dizisi tek bir değerdir: Bir okuyucunun, yapının tamamlanması için her şeyi tüketmesi gerekir. Bir milyon kayıttan oluşan bir JSONL dosyası ise bir milyon değerdir ve her satır tek başına ayakta durur.

Yakından ilişkili ikinci bir teknik özellik daha vardır. NDJSON özellikleri bu konuda nettir: "Şu anda bir akış protokolü içinde JSON metni örneklerini taşımak için bir standart yoktur." Belirtilen kullanım senaryosu, "TCP veya UNIX Pipes gibi akış protokolleri aracılığıyla birden fazla JSON metni örneği sunmaktır."

Bir JSONL dosyası nasıl yapılandırılır?

Üç gereksinim

JSON Lines dokümantasyonu tam olarak üç gereksinim listeler. İlki UTF-8 kodlamasıdır. JSON'ın kendisinden ödünç alınan bir uyarıyı barındırır: "JSON standardında olduğu gibi, bir bayt sırası işareti (BOM - U+FEFF) dahil EDİLMEMELİDİR."

İkincisi, her satırın geçerli bir JSON değeri olmasıdır. Sayfada, "en yaygın değerlerin nesneler veya diziler olacağı, ancak herhangi bir JSON değerine izin verildiği" belirtilir. Ardından insanların kafasını karıştıran uç bir örneğe yer verilir: "null geçerli bir değerdir ancak boş bir satır geçerli değildir."

Üçüncüsü, satır sonlandırıcının \n olmasıdır. Windows satır sonları da çalışmaya devam eder. Bunun nedeni mekaniktir: "Bu durum, JSON değerleri ayrıştırılırken çevreleyen boşluklar dolaylı olarak yoksayıldığı için \r\n ifadesinin de desteklendiği anlamına gelir."

Bir satırın içinde ne görünmemelidir?

Bu, formatın çalışmasını sağlayan kısıtlamadır. NDJSON teknik özellikleri bunu bir gereksinim olarak belirtir: "JSON metinleri yeni satırlar veya satır başı karakterleri İÇERMEMELİDİR."

Bir JSON değerinin normalde girintilerle birçok satıra yayılmasına izin verilir. Satırla sınırlandırılmış bir dosyada ise buna izin verilmez, çünkü yeni satır karakteri kayıt ayırıcıdır. Her kaydın tek bir fiziksel satıra yazılması gerekir.

Son satır ve boş satırlar

İki teknik özellik arasında iki detay farklılık gösterir ve bir dosya reddedildiğinde her ikisi de önem taşır.

Sondaki yeni satırı ele alalım. JSON Lines, "bir dosyadaki son JSON değerinden sonra bir satır sonlandırıcı eklenmesinin şiddetle tavsiye edildiğini ancak zorunlu olmadığını" belirtir.

Boş satırlar konusunda iki teknik özellik uyuşmaz. JSON Lines katıdır: Boş bir satır geçerli bir değer değildir. NDJSON ise esnektir ve "ayrıştırıcının boş satırları sessizce yoksayabileceğini" kabul eder, ancak "bu davranışın belgelenmesini" şart koşar.

Uzantılar ve medya türleri

İsimlendirme de ikiye ayrılır. JSON Lines, dosyaların ".jsonl dosya uzantısıyla kaydedilebileceğini" belirtir. Medya türü hakkında ise "MIME türü application/jsonl olabilir, ancak bu henüz standartlaştırılmamıştır" der. NDJSON ise medya türünün "application/x-ndjson OLMASI GEREKTİĞİNİ" ve uzantının ".ndjson OLMASI GEREKTİĞİNİ" belirtir.

Sıkıştırma için JSON Lines, akış sıkıştırıcılarını önerir: "Yerden tasarruf etmek için gzip veya bzip2 önerilir; bu da .jsonl.gz veya .jsonl.bz2 dosyalarıyla sonuçlanır."

Bir hata mesajını okurken küçük bir kuralı bilmekte fayda vardır. Metin editörleri ilk satırı "satır 1" olarak adlandırır. Dokümantasyon bunu genişletir: "Bir JSON Lines dosyasındaki ilk değer de 'değer 1' olarak adlandırılmalıdır."

JSONL ne için kullanılır?

Bir .jsonl dosyasıyla genellikle dört durumdan birinde karşılaşırsınız.

Günlük (log) ve olay dosyaları. Formatın kendi dokümantasyonunda günlük dosyalarından bahsedilir ve bunun nedeni, bir yazıcının hiçbir şeyi yeniden yazmadan her seferinde tek bir satır ekleyebilmesidir.

Veri ambarı yüklemeleri. Google'ın BigQuery dokümantasyonu, formatın resmi konumuna iyi bir örnektir. "Cloud Storage'dan yeni satırla sınırlandırılmış JSON (ndJSON) verilerinin" yüklenmesini destekler ve dosya formatı seçicisi bu seçeneği "JSONL (Newline delimited JSON)" olarak listeler.

İç içe geçmiş kayıtların API dışa aktarımları. Sütunlara düzgün bir şekilde düzleştirilemeyen veriler, satır başına iç içe geçmiş yapısını korur. Değişken sayıda ürün içeren sipariş satırları bunun klasik bir örneğidir.

Makine öğrenimi veri kümeleri. Eğitim ve değerlendirme kümeleri genellikle bu şekilde dağıtılır, çünkü bir eğitim döngüsü kayıtları her seferinde tek bir tane olacak şekilde okur.

Ortak nokta akıştır. Dosya kademeli olarak üretildiğinde veya kademeli olarak tüketildiğinde bariz bir seçenek haline gelir.

JSONL, JSON ve CSV Karşılaştırması

	JSONL	JSON	CSV
Dosyanın birimi	Satır başına bir değer	Tüm dosya için tek bir değer	Satır başına bir satır
İç içe geçmiş veri	Evet, kayıt başına	Evet	Yerel olarak hayır
Kayıt ekleme	Satır ekleme	Kapsayıcıyı yeniden yazma	Satır ekleme
Kısmi okuma kullanışlıdır	Evet	Nadir durumlarda	Evet
E-tabloda açılır	Hayır	Hayır	Genellikle
Kayıtların yapısı farklılık gösterebilir	Evet	Evet	Hayır, sütunlar sabittir
Bir editörde insan tarafından okunabilir	Evet, her biri tek bir uzun satır	Evet, girintilendiğinde	Evet

En çok şaşkınlık yaratan satır sondan bir öncekidir. Aynı JSONL dosyasındaki iki satır farklı anahtarlar taşıyabilir. Formatı esnek kılan tam olarak budur ve doğrudan yapılan bir içe aktarmanın düzensiz sütunlar üretmesine neden olan şey de tam olarak budur.

Sütun odaklı ikili alternatif için Parquet açıklayıcısı depolama tarafında aynı konuyu ele alır. En basit tablosal durum için ise TSV incelemesi sekmeyle ayrılmış metni kapsar.

Temel avantajlar

Yalnızca ekleme yapılabilen yazma. Yeni bir kayıt, yeni bir satır demektir. Dosyanın önceki kısımlarında hiçbir şeyin değişmesi gerekmez.

Akışlı okumalar. Bir tüketici, iki milyonuncu kayıt yazılmadan önce birinci kaydı işleyebilir.

Hata toleransı. Kesintiye uğramış bir dosya, son tamamlanan satıra kadar hala okunabilir durumdadır. Kesintiye uğramış bir JSON dizisi ise genellikle tamamen okunamaz hale gelir.

İç içe geçmiş yapı korunur. Bir CSV dosyasının düzleştirmek zorunda kalacağı yapı, her kaydın içinde bozulmadan kalır.

Kabuk dostu. Dokümantasyon, Unix tarzı metin işlemeyi ve kabuk boru hatlarını (shell pipelines) över; çünkü satır odaklı bir dosya, satır odaklı araçlarla çalışır.

Veri ambarı desteği. BigQuery dokümantasyonu, uyguladığı kuralı belirtir: "Her JSON nesnesi dosyada ayrı bir satırda olmalıdır."

JSONL'in yetersiz kaldığı durumlar

Format, taşıma ve ekleme işlemlerini çözer. Ancak içerik hakkında sahip olduğunuz soruların hiçbirini çözmez.

Sıkıştırma, zahmetsiz bir kazançtan ziyade gerçek bir ödündür. BigQuery dokümantasyonu maliyet konusunda nettir: "Gzip sıkıştırması kullanırsanız, BigQuery verileri paralel olarak okuyamaz." Ayrıca "sıkıştırılmış JSON verilerini BigQuery'ye yüklemenin, sıkıştırılmamış verileri yüklemekten daha yavaş olduğunu" ekler. Formatın kendi sayfası ise yerden tasarruf etmek için gzip'i önerir. Her iki durum da doğrudur ve birbirine zıt yönlere çekerler.

Ayrıca oldukça ayrıntılıdır. Her satır her anahtar adını tekrarlar, bu nedenle geniş bir kayıt kümesi, sütunlu bir formattaki aynı veriden önemli ölçüde daha büyüktür.

Ve tutarlılık hakkında hiçbir şey söylemez. Farklı yapılara sahip kayıtlara izin verilir, bu da bir alanın dosyanın ortasında hiçbir şey geçersiz olmadan sessizce görünmeyi durdurabileceği anlamına gelir.

Mühendis değilseniz bir JSONL dosyasıyla nasıl çalışırsınız?

Pratik boşluk buradadır. İş araçları satırlar ve sütunlar bekler ve bir .jsonl dosyası bir CSV gibi açılmaz.

Pratik yol bir dönüştürme adımıdır. Dosyayı üreten kişiden ihtiyacınız olan alanların düzleştirilmiş bir CSV veya Excel çıktısını isteyin. Veya JSON destekleyen herhangi bir araçla kendiniz düzleştirin. İç içe geçmiş yapıyı kaybedersiniz, ancak analizin hangi alanları kullanacağına karar verdikten sonra bu durum genellikle önem taşımaz.

Buradan sonrası sıradan bir analiz çalışmasıdır. Powerdrill Bloom'un fiyatlandırma sayfası Excel, CSV, PDF ve belgeler için yüklemeleri listeler, bu nedenle düzleştirilmiş bir çıktı doğrudan içeri aktarılabilir. Sorular, sorgu olarak yazılmak yerine doğal dilde sorulur. CSV AI assistant bu yolu kapsar ve data connectors, verilerin dışa aktarılmak yerine kaynağından çekilmesinin daha iyi olduğu durumları kapsar.

Unutulmaması gereken ayrım, bunun sizin üst akışınızda alınan bir taşıma kararı olduğudur. Dosya masanıza ulaştığında bu formattan dönüştürme yapmak geçici bir çözüm değil, normal bir süreçtir.

Sonuç

JSONL tek bir kuralı olan bir metin formatıdır: Satır başına bir tam JSON değeri ve bir değerin içinde yeni satır olmaması. Bu kural; eklenebilirlik, akış ve kısmi okuma toleransı sağlar; günlüklerin ve veri ambarı yüklemelerinin varsayılan olarak bunu seçmesinin nedeni de budur.

Sağlamadığı şey ise bir tablodur. Dosya, bir boru hattından ziyade yanıtlara ihtiyaç duyan birine ulaştığı anda, bir sonraki yararlı adım düzleştirilmiş bir çıktı almak ve bir soru sormaktır.

Eğer bu durumdaysanız, dönüştürülmüş dosya ile Powerdrill Bloom'u deneyin ve işe onu bir grafiğe dönüştürerek başlayın.

Sıkça sorulan sorular

JSONL dosyası ne için kullanılır?

Kayıt akışları için kullanılır: Günlük (log) dosyaları, olay dışa aktarımları, veri ambarı yüklemeleri ve makine öğrenimi veri kümeleri. Formatın dokümantasyonunda özellikle günlük dosyaları ve kabuk boru hatlarından (shell pipelines) bahsedilir. Ortak faktör, kayıtların her seferinde tek bir tane olacak şekilde yazılması veya okunmasıdır.

JSONL ve NDJSON arasındaki fark nedir?

Aynı fikri farklı belgelerle tanımlarlar. JSON Lines, .jsonl uzantısını kullanır ve application/jsonl uzantısının henüz standartlaştırılmadığını belirtir. NDJSON ise .ndjson ve application/x-ndjson uzantılarını belirtir ve ayrıştırıcıların boş satırları yoksaymasına izin verir.

Bir JSONL dosyasını Excel'de açabilir miyim?

Üzerine çift tıklayarak açamazsınız, çünkü her satır bir hücre satırı değil, bir JSON değeridir. Genel yaklaşım, öncelikle ihtiyacınız olan alanları CSV veya Excel formatında düzleştirmek ya da formatı doğrudan okuyan bir araç kullanmaktır.

JSONL'de bir kayıt neden birden fazla satıra yayılamaz?

Çünkü yeni satır karakteri kayıt ayırıcıdır. NDJSON teknik özellikleri, "JSON metinlerinin yeni satırlar veya satır başı karakterleri İÇERMEMELİDİR" der. Bu nedenle, güzel biçimlendirilmiş (pretty-printed) JSON'ın kayıt başına tek bir satıra daraltılması gerekir.

Bir JSONL dosyasında boş satıra izin verilir mi?

İki teknik özellik farklılık gösterir. JSON Lines, "null geçerli bir değerdir ancak boş bir satır geçerli değildir" der. NDJSON ise bu davranışın belgelenmesi koşuluyla, bir ayrıştırıcının boş satırları sessizce yoksaymasına izin verir.