Menguasai File JSONL: Struktur, Kasus Penggunaan, dan Keunggulan Utama

File JSONL menyimpan satu nilai JSON lengkap per baris. Dokumentasi resmi menyebutnya "format teks JSON Lines, juga disebut JSON dengan pembatas baris baru." Aturan tunggal itulah yang membuatnya dapat dialirkan dengan baik, mengapa ia tetap aman saat dibaca sebagian, dan mengapa aplikasi spreadsheet tidak akan bisa membukanya.

Apa itu file JSONL?

JSON Lines adalah format teks untuk rekaman data. Spesifikasinya menggambarkannya sebagai "format yang praktis untuk menyimpan data terstruktur yang dapat diproses satu rekaman sekaligus."

Dokumentasi tersebut menjelaskan secara eksplisit di mana format ini cocok digunakan. Format ini "berfungsi dengan baik dengan alat pemrosesan teks bergaya unix dan pipa shell," dan halaman tersebut menambahkan bahwa "ini adalah format yang sangat bagus untuk file log." Format ini juga digambarkan sebagai "format yang fleksibel untuk mengirimkan pesan di antara proses-proses yang saling bekerja sama."

Perbedaan kontras dengan JSON biasa adalah poin utamanya. Sebuah array JSON yang berisi satu juta rekaman adalah satu nilai tunggal: pembaca harus memproses seluruh data sebelum strukturnya lengkap. Sedangkan file JSONL berisi satu juta rekaman adalah satu juta nilai, dan setiap baris berdiri sendiri.

Ada spesifikasi kedua yang sangat berkaitan erat. Spesifikasi NDJSON menjelaskannya secara langsung: "saat ini tidak ada standar untuk mentransmisikan instans teks JSON dalam protokol aliran." Kasus penggunaan yang dinyatakan adalah "mengirimkan beberapa instans teks JSON melalui protokol aliran seperti TCP atau UNIX Pipes."

Bagaimana struktur file JSONL

Tiga persyaratan utama

Dokumentasi JSON Lines mencantumkan tepat tiga persyaratan. Yang pertama adalah pengodean UTF-8. Persyaratan ini membawa peringatan yang dipinjam dari JSON itu sendiri: "seperti standar JSON, tanda urutan bita (U+FEFF) TIDAK boleh disertakan."

Yang kedua adalah bahwa setiap baris harus berupa nilai JSON yang valid. Halaman tersebut mencatat bahwa "nilai yang paling umum adalah objek atau array, tetapi nilai JSON apa pun diizinkan." Halaman ini kemudian memberikan kasus ekstrem yang sering membingungkan orang: "null adalah nilai yang valid, tetapi baris kosong tidak valid."

Yang ketiga adalah bahwa pemberhentian baris menggunakan \n. Akhiran baris Windows masih tetap berfungsi. Alasan mekanis yang diberikan adalah: "ini berarti \r\n juga didukung karena spasi kosong di sekitarnya secara implisit diabaikan saat mengurai nilai-nilai JSON."

Apa yang tidak boleh muncul di dalam satu baris

Ini adalah batasan yang membuat format ini berfungsi. Spesifikasi NDJSON menyatakannya sebagai persyaratan: "teks JSON TIDAK BOLEH mengandung baris baru atau carriage return."

Nilai JSON biasanya diizinkan untuk mencakup banyak baris dengan indentasi. Dalam file yang dibatasi baris, hal ini tidak bisa dilakukan karena baris baru adalah pemisah rekaman. Setiap rekaman harus ditulis dalam satu baris fisik.

Baris terakhir, dan baris kosong

Dua detail berbeda di antara kedua spesifikasi tersebut, dan keduanya sangat penting ketika sebuah file ditolak.

Perhatikan baris baru di bagian akhir. JSON Lines menyatakan bahwa "menyertakan pemberhentian baris setelah nilai JSON terakhir dalam file sangat direkomendasikan tetapi tidak wajib."

Mengenai baris kosong, kedua spesifikasi ini tidak sependapat. JSON Lines sangat ketat: baris kosong bukanlah nilai yang valid. NDJSON lebih longgar, mengizinkan bahwa "pengurai MAY mengabaikan baris kosong secara diam-diam," sambil mensyaratkan bahwa "perilaku ini MUST didokumentasikan."

Ekstensi dan tipe media

Penamaannya juga terbagi. JSON Lines menyatakan bahwa file "dapat disimpan dengan ekstensi file .jsonl." Mengenai tipe media, dinyatakan bahwa "tipe MIME dapat berupa application/jsonl, tetapi ini belum distandarisasi." NDJSON menyatakan bahwa tipe media "SHOULD berupa application/x-ndjson" dan ekstensinya "SHOULD berupa .ndjson."

Untuk kompresi, JSON Lines merekomendasikan kompresor aliran: "gzip atau bzip2 direkomendasikan untuk menghemat ruang, menghasilkan file .jsonl.gz atau .jsonl.bz2."

Satu konvensi kecil yang perlu diketahui saat Anda membaca pesan kesalahan. Editor teks menyebut baris pertama sebagai "baris 1." Dokumentasi memperluas hal itu: "nilai pertama dalam file JSON Lines juga harus disebut 'nilai 1'."

Kegunaan JSONL

Anda biasanya akan menemui file .jsonl dalam salah satu dari empat situasi berikut.

File log dan aktivitas. Dokumentasi format itu sendiri menyebutkan file log, dan alasannya adalah karena penulis data dapat menambahkan satu baris sekaligus tanpa harus menulis ulang apa pun.

Pemuatan gudang data. Dokumentasi BigQuery dari Google adalah contoh yang baik dari status resmi format ini. Layanan ini mendukung pemuatan "data JSON dibatasi baris baru (ndJSON) dari Cloud Storage," dan pemilih format filenya mencantumkan opsi tersebut sebagai "JSONL (Newline delimited JSON)."

Ekspor API dari rekaman bersarang. Data yang tidak dapat diratakan secara rapi ke dalam kolom akan mempertahankan struktur bersarangnya per baris. Baris pesanan dengan jumlah item yang bervariasi adalah contoh klasiknya.

Dataset pembelajaran mesin. Set pelatihan dan evaluasi biasanya didistribusikan dengan cara ini, karena loop pelatihan membaca rekaman data satu per satu.

Benang merahnya adalah pengaliran. Format ini menjadi pilihan yang jelas ketika file dibuat secara bertahap atau dikonsumsi secara bertahap.

Perbandingan JSONL, JSON, dan CSV

	JSONL	JSON	CSV
Unit file	Satu nilai per baris	Satu nilai untuk seluruh file	Satu baris per baris
Data bersarang	Ya, per rekaman	Ya	Tidak secara bawaan
Menambahkan rekaman	Tambahkan baris	Tulis ulang kontainer	Tambahkan baris
Pembacaan sebagian berguna	Ya	Jarang	Ya
Dapat dibuka di spreadsheet	Tidak	Tidak	Biasanya
Bentuk rekaman bisa berbeda	Ya	Ya	Tidak, kolom bersifat tetap
Dapat dibaca manusia di editor	Ya, masing-masing satu baris panjang	Ya, jika diberi indentasi	Ya

Baris yang paling mengejutkan adalah baris kedua dari bawah. Dua baris dalam file JSONL yang sama dapat membawa kunci yang berbeda. Hal itulah yang membuat format ini fleksibel, dan juga yang menyebabkan impor sederhana menghasilkan kolom yang tidak rata.

Untuk alternatif biner berorientasi kolom, penjelasan Parquet membahas topik yang sama dari sisi penyimpanan. Untuk kasus tabular yang paling sederhana, analisis TSV membahas teks yang dipisahkan oleh tab.

Keunggulan utama

Penulisan hanya-tambah. Rekaman baru berarti baris baru. Tidak ada bagian file sebelumnya yang perlu diubah.

Pembacaan aliran. Konsumen data dapat memproses rekaman pertama bahkan sebelum rekaman ke dua juta ditulis.

Toleransi kegagalan. File yang terpotong masih dapat dibaca hingga baris lengkap terakhir. Sedangkan array JSON yang terpotong biasanya tidak dapat dibaca sama sekali.

Struktur bersarang tetap terjaga. Struktur yang harus diratakan jika menggunakan CSV tetap utuh di dalam setiap rekaman.

Ramah shell. Dokumentasi memuji pemrosesan teks bergaya unix dan pipa shell, karena file yang berorientasi baris bekerja sangat baik dengan alat yang juga berorientasi baris.

Dukungan gudang data. Dokumentasi BigQuery menyatakan aturan yang diterapkannya: "setiap objek JSON harus berada di baris terpisah dalam file."

Di mana JSONL tidak lagi membantu

Format ini menyelesaikan masalah transmisi dan penambahan data. Namun, format ini tidak menyelesaikan pertanyaan apa pun yang Anda miliki tentang isinya.

Kompresi adalah sebuah kompromi nyata, bukan keuntungan tanpa timbal balik. Dokumentasi BigQuery menjelaskan konsekuensinya secara blak-blakan: "jika Anda menggunakan kompresi gzip, BigQuery tidak dapat membaca data secara paralel." Dokumentasi tersebut menambahkan bahwa "memuat data JSON yang dikompresi ke dalam BigQuery lebih lambat daripada memuat data yang tidak dikompresi." Halaman format itu sendiri merekomendasikan gzip untuk menghemat ruang. Kedua hal tersebut benar, dan keduanya saling bertolak belakang.

Format ini juga sangat panjang. Setiap baris mengulang setiap nama kunci, sehingga kumpulan rekaman yang lebar akan berukuran jauh lebih besar daripada data yang sama dalam format kolom.

Dan format ini tidak menjamin konsistensi. Rekaman dengan bentuk yang berbeda diizinkan, yang berarti sebuah kolom bisa tiba-tiba berhenti muncul di tengah-tengah file tanpa membuat file tersebut menjadi tidak valid.

Cara bekerja dengan file JSONL jika Anda bukan seorang insinyur

Ini adalah kesenjangan praktisnya. Alat bisnis mengharapkan baris dan kolom, dan file .jsonl tidak akan terbuka seperti halnya file CSV.

Jalur yang pragmatis adalah langkah konversi. Mintalah kepada siapa pun yang membuat file tersebut untuk memberikan ekstrak CSV atau Excel yang sudah diratakan dari kolom-kolom yang Anda butuhkan. Atau ratakan sendiri menggunakan alat apa pun yang mendukung JSON. Anda akan kehilangan struktur bersarangnya, yang biasanya tidak masalah setelah Anda menentukan kolom mana saja yang akan digunakan dalam analisis.

Dari sana, pekerjaannya adalah analisis biasa. Halaman harga Powerdrill Bloom mencantumkan unggahan untuk Excel, CSV, PDF, dan dokumen, sehingga ekstrak yang telah diratakan bisa langsung dimasukkan. Pertanyaan diajukan dalam bahasa alami, bukan ditulis sebagai kueri. Asisten AI CSV mencakup jalur tersebut, dan konektor data mencakup kasus-kasus di mana data lebih baik ditarik langsung dari sumbernya daripada diekspor.

Perbedaan yang perlu diingat adalah bahwa ini adalah keputusan transmisi yang dibuat di hulu sebelum sampai ke Anda. Mengonversinya setelah file tersebut sampai di meja Anda adalah hal yang normal, bukan sebuah trik sementara.

Kesimpulan

JSONL is a text format with one rule: one complete JSON value per line, and no newlines inside a value. That rule buys appendability, streaming, and partial-read tolerance, which is why logs and warehouse loads default to it.

Apa yang tidak diberikannya adalah sebuah tabel. Begitu file tersebut sampai ke tangan seseorang yang membutuhkan jawaban alih-alih pipa data, langkah selanjutnya yang berguna adalah ekstrak yang diratakan dan sebuah pertanyaan.

Jika di situlah posisi Anda saat ini, coba Powerdrill Bloom dengan file yang telah dikonversi dan mulailah dengan mengubahnya menjadi grafik.

Pertanyaan yang sering diajukan

Untuk apa file JSONL digunakan?

Format ini digunakan untuk aliran rekaman data: file log, ekspor aktivitas, pemuatan gudang data, dan dataset pembelajaran mesin. Dokumentasi format ini secara khusus menyebutkan file log dan pipa shell. Faktor kesamaannya adalah bahwa rekaman data ditulis atau dibaca satu per satu.

Apa perbedaan antara JSONL dan NDJSON?

Keduanya menggambarkan ide yang sama dengan dokumentasi yang berbeda. JSON Lines menggunakan ekstensi .jsonl dan mencatat bahwa application/jsonl belum distandarisasi. NDJSON menentukan .ndjson dan application/x-ndjson, serta mengizinkan pengurai untuk mengabaikan baris kosong.

Apakah saya bisa membuka file JSONL di Excel?

Tidak bisa dengan mengekliknya dua kali, karena setiap baris adalah nilai JSON, bukan baris sel. Pendekatan yang biasa dilakukan adalah meratakan kolom yang Anda butuhkan ke dalam CSV atau Excel terlebih dahulu, atau menggunakan alat yang membaca format tersebut secara langsung.

Mengapa rekaman data tidak boleh mencakup beberapa baris dalam JSONL?

Karena karakter baris baru adalah pemisah rekaman. Spesifikasi NDJSON menyatakan bahwa "teks JSON TIDAK BOLEH mengandung baris baru atau carriage return." Oleh karena itu, JSON yang diformat rapi harus diringkas menjadi satu baris per rekaman.

Apakah baris kosong diizinkan dalam file JSONL?

Kedua spesifikasi tersebut berbeda. JSON Lines menyatakan bahwa "null adalah nilai yang valid, tetapi baris kosong tidak valid." NDJSON mengizinkan pengurai untuk mengabaikan baris kosong secara diam-diam, asalkan perilaku tersebut didokumentasikan.