JSON Toolkit

jq dan berkas JSON besar: mengapa -s meledakkan memori dan cara memproses secara streaming

Intinya: Agregasi ratusan MB log JSON dengan jq -s berakhir di OOM, sementara reduce inputs menghasilkan statistik yang sama hanya dengan beberapa MB RAM. Diukur pada sampel 220 MB dan 2 juta baris: slurp memuncak di 2,08 GB dibanding 3,5 MB untuk reducer streaming. Artikel ini menjelaskan mekanisme konsumsi memori, pemrosesan JSONL baris demi baris, peristiwa path dari --stream, dan tiga jebakan nyata, termasuk keluaran kosong senyap dari -n --stream.

Lanjutan±6 menit bacaDiterbitkan 2026-11-12Diperbarui 2026-11-12
Perbandingan memori antara jq streaming dan -s pada JSON besar

jq mengurai dengan cepat, tetapi hampir setiap kematian di depan berkas beberapa ratus MB bermuara ke flag yang sama: -s memuat seluruh input ke satu array raksasa, dan RSS puncak dengan mudah mencapai beberapa kali ukuran berkas.

Satu berkas, dua kueri: memori 580 kali lebih sedikit

Mari mulai dari pengukuran. Sampelnya adalah log JSONL 220 MB dengan 2.000.000 baris (satu rekaman request per baris: timestamp, level, path, status, duration_ms, uid). Lingkungan: jq 1.7 di Linux x86_64, RSS puncak direkam via /usr/bin/time -v:

Kueri Tugas Durasi RSS puncak
jq -s 'group_by(.level) | ...' penghitungan per level 10,1s 2,08 GB (~9,5x ukuran berkas)
jq -n 'reduce inputs ...' penghitungan yang sama 4,7s 3,5 MB
jq -r 'select(...) | .path' filter baris demi baris 2,6s 3,6 MB

Statistik yang sama, memori 580 kali lebih sedikit, bahkan lebih cepat. Ini bukan bug jq — -s menurut definisi berarti «baca semuanya ke dalam array»; kebanyakan orang sekadar tidak menghitung biaya bawaan ini. Sumber pihak ketiga sepakat: laporan pengalaman 2,3 GB JSONL dari komunitas Huawei Cloud menceritakan kisah yang persis sama — OOM dengan slurp, lalu reducer streaming selesai dalam 47 detik dengan RSS sedikit di atas 30 MB. Dratini.tech mengukur pada input 2,5 GB sebuah jq -s yang dibunuh OOM killer bahkan di mesin 16 GB+, sementara pipeline biasa selesai dalam 48,2s dengan 84 MB.

Kesimpulan di depan: jika berkas melampaui setengah memori yang tersedia, -s bahkan bukan kandidat. Ukur tiga hal sebelum menulis apa pun: ls -lh untuk ukuran, free -m untuk sisa memori, wc -l untuk jumlah baris.

Ke mana memori sebenarnya pergi

jq -s (slurp) terdokumentasi sebagai «baca semua input ke dalam array». Biaya riilnya jauh melampaui teksnya: setelah penguraian, jq memegang pohon struktur C, dan setiap objek, array, string, serta angka membawa simpulnya sendiri lengkap dengan metadata. 220 MB teks kami menjadi sedikit di atas 2 GB struktur — menggembung sekitar 9,5x. group_by tambah lagi mengurutkan dan mengelompokkan di memori, memperbesar puncak.

Satu dokumen JSON besar berperilaku sama. Membungkus log yang sama ke array akar 300 MB lalu mengekstrak dengan filter biasa:

Kueri Durasi RSS puncak
jq '.[] | select(.level=="ERROR") | .uid' (seluruh dokumen) 4,7s 1,85 GB
jq --stream 'select(...)' (peristiwa path) 13,4s 3,4 MB

Penguraian penuh tetap memuncak sekitar 1,8 GB — jq membangun seluruh pohon sebelum filter dieksekusi. --stream menukar sekitar 3x waktu eksekusi dengan memori 540 kali lebih kecil. Model rinci dari pembengkakan ini diurai lebih lanjut di Dari mana memori berasal.

Log JSONL: pembacaan baris demi baris sudah merupakan streaming

Jika «berkas besar» Anda sebenarnya JSONL — satu objek per baris —, perilaku bawaan jq sudah merupakan aliran: setiap baris diurai dan dipancarkan secara independen, dan -s bukan hanya tidak perlu, tapi merugikan:

# penghitungan per level: baris demi baris, agregasi di shell
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head

# filter + ekstraksi: select dulu, baris yang tidak cocok langsung dibuang
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5

Dua kebiasaan yang perlu dipaksakan:

  • select paling depan di pipeline. jq menyaring begitu satu baris diurai; menyaring setelah transformasi berarti memboroskan komputasi.
  • -r untuk string mentah. Tanpa itu, keluarannya adalah string JSON berpakai tanda kutip, dan uniq -c akan menghitung "ERROR" dan ERROR sebagai dua nilai berbeda.

Untuk baris yang rusak gunakan fromjson?: jq -r 'fromjson? | .level' melewatkan baris yang tak terurai secara senyap, dan fragmen yang terpotong tidak membunuh seluruh pipeline. Formatnya sendiri dibahas di Buku panduan praktis JSONL; artikel ini membahas perintah yang memprosesnya.

Agregasi global: reduce inputs menjaga status tetap terbatas

Penyaringan baris demi baris adalah urusan shell, tetapi ketika agregasi harus terjadi di dalam jq — penghitung per level, durasi rata-rata per path —, kuncinya adalah reduce dengan inputs, untuk status yang terbatas:

# penghitungan per level: memori mengikuti ukuran hasil, bukan berkas
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl

# durasi rata-rata per path: statusnya pasangan tetap {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
      | map_values(.total / .count)' app.jsonl

Dua detail:

  • -n berarti jq tidak boleh mengonsumsi input pertama sebagai nilai awal; inputs sendiri yang memancarkan setiap rekaman. Lupa -n dan rekaman pertama ditelan sebagai status awal.
  • Status reducer harus berbentuk tetap — hanya penghitung dan akumulator. Begitu Anda memasukkan baris yang cocok ke dalam array di dalam reducer, memori kembali tumbuh mengikuti volume data dan streaming tidak berarti apa-apa lagi.

Itulah asal 3,5 MB di tabel: dua gigabyte telah lewat, yang tersisa hanya tabel hash.

Satu dokumen besar: peristiwa path dari --stream

Ketika inputnya adalah satu dokumen akar raksasa (ekspor beberapa ratus MB tanpa batas baris), gunakan --stream. Alih-alih nilai utuh, ia memancarkan urutan peristiwa «path + nilai daun»:

# satu peristiwa tampak seperti: array path + skalar
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"

Mengekstrak dari aliran peristiwa menuntut pencocokan bentuk path secara utuh — kedalaman, nama anggota, posisi indeks —, karena memeriksa hanya komponen terakhir akan menangkap juga kunci sama nama di objek bersarang:

# hanya rows[i].id, mengabaikan meta.id dan si kembar yang lebih dalam
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json

Agregasi tetap reduce inputs berbentuk tetap (dengan -n --stream, peristiwa harus dikonsumsi lewat inputs — lihat jebakan). Untuk rekonstruksi — mengubah aliran peristiwa kembali menjadi objek utuh — gabungkan truncate_stream dan fromstream. Gambaran pemilihan alat berdasarkan ukuran ada di Berkas JSON terlalu besar?.

Tiga jebakan nyata

Jebakan satu: -n --stream tanpa inputs tidak menghasilkan apa pun, dalam diam. Terbukti di mesin ini: jq -n --stream 'select(...)' file.json berakhir dengan kode 0, tanpa keluaran maupun kesalahan — dalam mode -n, jq tidak membaca input, dan select pada filter tidak menerima satu peristiwa pun. Yang benar: buang -n dan pakai --stream polos, atau pasangkan -n --stream dengan reduce inputs. Kelas kegagalan «sukses tapi kosong» ini paling sulit di-debug; validasikan pada sampel kecil sebelum menggawangi sebuah pipeline.

Jebakan dua: --stream hanya memancarkan daun skalar; objek dan array kosong tidak punya peristiwa nilai. {"a":{}} hanya menghasilkan peristiwa penutupan path (tipe length == 1), dan filter pada length == 2 akan menelan kontainer kosong dalam diam — putuskan secara eksplisit apakah mereka dihitung dalam statistik Anda.

Jebakan tiga: hasil parsial setelah galat penguraian di tengah berkas. Pipeline streaming bisa saja sudah memancarkan separuh keluarannya sebelum tersandung JSON rusak menjelang akhir. jq 1.7 secara bawaan gagal dengan keras — [1,] menghasilkan parse error: Expected another array element at line 1, column 4 dengan kode 5 dalam pengujian kami — tetapi jika shell Anda mengalihkan stdout ke berkas tujuan, hasil yang terpotong sudah ada di disk. Tameng rekayasa: staging plus rename — tulis ke berkas sementara dan pindah menimpa target hanya setelah jq sukses. Untuk kendali lebih halus, --stream-errors mengubah galat penguraian menjadi peristiwa yang bisa Anda tangani dan hentikan secara eksplisit lewat error.

Kapan tidak memakai jq: Miller dan pipeline hibrida

jq adalah bahasa fungsional untuk transformasi pohon, kuat dalam penataan ulang yang dalam. Namun begitu tugas terdegradasi menjadi «menyaring dan menghitung gigabyte log datar», ada alat yang lebih pas. Benchmark dratini.tech pada 2,5 GB JSONL (filter + pemilihan kolom):

Alat Durasi RSS puncak
pipeline jq biasa 48,2s 84 MB
jq -s OOM (terbunuh bahkan dengan 16 GB+) —
Miller (mlr --json) 11,4s 18 MB
ripgrep + jq hibrida 8,1s 32 MB

Aturannya: sarang dalam, penataan ulang, kehadiran di mana-mana di CI — jq. Statistik datar multi-gigabyte, persentil p95, JSONL ke TSV — satu mlr --json stats1 menggantikan skrip jq dengan memori konstan. Dan jika ripgrep bisa menyisihkan 90 % baris tak berguna sebelum jq, jalur hibrida yang tercepat.

FAQ

Mulai ukuran berapa jq -s menjadi berbahaya?

Ambang praktis: begitu berkas melampaui setengah memori yang tersedia, bersiap waspada. Memori setelah penguraian biasanya 3 sampai 10 kali teksnya (9,5x pada 220 MB kami; laporan pihak ketiga menunjukkan berkas 4 GB membunuh mesin 16 GB). Bandingkan dulu ls -lh dengan free -m, dan mendekati batas gantilah -s dengan reduce inputs.

Mengapa -n di depan reduce inputs?

-n menyuruh jq untuk tidak mengonsumsi input pertama sebagai nilai awal program, agar inputs sendiri yang memancarkan setiap rekaman. Tanpa -n, rekaman pertama menjadi status awal reduce dan hilang dalam diam dari hasil — kehilangan data tanpa satu pun galat.

Bagaimana memilih antara --stream dan mode biasa?

Lihat dulu bentuk berkasnya. JSONL sudah merupakan aliran baris demi baris; --stream tidak berguna. Untuk satu dokumen besar yang Anda inginkan hanya beberapa nilai daun, --stream menukar sekitar 3x waktu dengan memori ratusan kali lebih kecil. Jika berkas muat di memori, jq biasa memang lebih cepat.

Apa yang dilakukan terhadap baris rusak saat streaming?

Dalam JSONL, fromjson? melewatkan baris yang tak terurai agar satu baris kotor tidak membunuh pipeline. Pada satu dokumen besar, galat penguraian di tengah berkas membuat seluruh eksekusi gagal — publikasikan secara atomik lewat berkas staging dan rename, atau pakai --stream-errors untuk kendali eksplisit.