JSON Toolkit

jq và tệp JSON lớn: vì sao -s nổ bộ nhớ và cách xử lý theo dòng

Kết luận: Tổng hợp hàng trăm MB log JSON bằng jq -s kết thúc trong OOM, trong khi reduce inputs tạo ra cùng thống kê với vài MB RAM. Đo trên mẫu 220 MB và 2 triệu dòng: slurp đạt đỉnh 2,08 GB so với 3,5 MB của bộ reducir streaming. Bài viết giải thích cơ chế tiêu thụ bộ nhớ, xử lý JSONL từng dòng, các sự kiện đường dẫn của --stream và ba bẫy thực tế, kể cả đầu ra rỗng âm thầm của -n --stream.

Nâng caoĐọc khoảng 6 phútXuất bản 2026-11-12Cập nhật 2026-11-12
So sánh bộ nhớ giữa jq streaming và -s trên JSON lớn

jq parse rất nhanh, nhưng gần như mọi cái chết trước một tệp vài trăm MB đều quy về cùng một flag: -s nạp toàn bộ đầu vào vào một mảng khổng lồ duy nhất, và RSS đỉnh dễ dàng đạt vài lần kích thước tệp.

Một tệp, hai truy vấn: ít bộ nhớ hơn 580 lần

Bắt đầu bằng một phép đo. Mẫu là log JSONL 220 MB và 2.000.000 dòng (mỗi dòng một bản ghi request: timestamp, level, path, status, duration_ms, uid). Môi trường: jq 1.7 trên Linux x86_64, RSS đỉnh ghi nhận qua /usr/bin/time -v:

Truy vấn Việc Thời gian RSS đỉnh
jq -s 'group_by(.level) | ...' đếm theo level 10,1s 2,08 GB (~9,5x kích thước tệp)
jq -n 'reduce inputs ...' cùng phép đếm 4,7s 3,5 MB
jq -r 'select(...) | .path' lọc từng dòng 2,6s 3,6 MB

Cùng một thống kê, ít bộ nhớ hơn 580 lần, và còn nhanh hơn. Đây không phải bug của jq — -s theo định nghĩa là «đọc tất cả vào một mảng»; phần lớn mọi người đơn giản không tính chi phí mặc định này. Nguồn bên ngoài cũng khớp: ghi nhận về 2,3 GB JSONL từ cộng đồng Huawei Cloud kể đúng câu chuyện đó — OOM với slurp, rồi bộ giảm streaming hoàn thành trong 47 giây với hơn 30 MB RSS chút xíu. Dratini.tech đo trên 2,5 GB đầu vào thấy jq -s bị OOM killer giết ngay cả trên máy 16 GB+, trong khi pipeline thường hoàn tất trong 48,2s với 84 MB.

Kết luận trước: nếu tệp vượt quá một nửa bộ nhớ khả dụng, -s thậm chí không phải ứng viên. Đo ba thứ trước khi viết bất cứ gì: ls -lh cho kích thước, free -m cho dư địa bộ nhớ, wc -l cho số dòng.

Bộ nhớ thực sự đi đâu

jq -s (slurp) được ghi chép là «đọc mọi đầu vào vào một mảng». Chi phí thực tế vượt xa văn bản: sau khi parse, jq giữ một cây cấu trúc C, và mỗi object, array, string và number đều mang node riêng cùng metadata. 220 MB văn bản của chúng tôi trở thành hơn 2 GB cấu trúc — phình ra khoảng 9,5x. group_by còn sắp xếp và nhóm trong bộ nhớ, khuếch đại đỉnh.

Một tài liệu JSON lớn duy nhất cũng vậy. Gói cùng log vào mảng gốc 300 MB rồi trích xuất bằng filter thường:

Truy vấn Thời gian RSS đỉnh
jq '.[] | select(.level=="ERROR") | .uid' (cả tài liệu) 4,7s 1,85 GB
jq --stream 'select(...)' (sự kiện đường dẫn) 13,4s 3,4 MB

Parse toàn phần vẫn đạt đỉnh quanh 1,8 GB — jq dựng toàn bộ cây trước khi filter chạy. --stream đổi khoảng 3x thời gian chạy lấy bộ nhớ nhỏ hơn 540 lần. Mô hình chi tiết của sự phình này được khai triển trong Bộ nhớ từ đâu ra.

Log JSONL: đọc từng dòng vốn đã là streaming

Nếu «tệp lớn» của bạn thực ra là JSONL — mỗi dòng một object —, hành vi mặc định của jq đã là dòng chảy: mỗi dòng được parse và phát độc lập, và -s không chỉ thừa mà còn có hại:

# đếm theo level: từng dòng, tổng hợp trong shell
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head

# lọc + trích xuất: select trước, dòng không khớp bị vứt ngay
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5

Hai thói quen nên ép mình thực hiện:

  • select ngay đầu pipeline. jq lọc ngay khi một dòng được parse; lọc sau các biến đổi là phí tính toán.
  • -r cho chuỗi thô. Không có nó, đầu ra là chuỗi JSON có ngoặc kép, và uniq -c sẽ đếm "ERROR" và ERROR thành hai giá trị khác nhau.

Với các dòng hỏng, dùng fromjson?: jq -r 'fromjson? | .level' lặng lẽ bỏ qua các dòng không parse được, và một mảnh bị cắt cụt không giết cả pipeline. Bản thân định dạng được trình bày trong Cẩm nang thực hành JSONL; bài này nói về các lệnh xử lý nó.

Tổng hợp toàn cục: reduce inputs giữ trạng thái có chặn

Lọc từng dòng thuộc về shell, nhưng khi tổng hợp phải xảy ra bên trong jq — bộ đếm theo level, thời lượng trung bình theo path —, chìa khóa là reduce với inputs, cho trạng thái có chặn:

# đếm theo level: bộ nhớ theo kích thước kết quả, không phải tệp
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl

# thời lượng trung bình theo path: trạng thái là cặp cố định {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
      | map_values(.total / .count)' app.jsonl

Hai chi tiết:

  • -n nghĩa là jq không được tiêu thụ đầu vào đầu tiên làm giá trị khởi tạo; inputs tự phát từng bản ghi. Quên -n và bản ghi đầu tiên bị nuốt làm trạng thái khởi tạo.
  • Trạng thái của bộ giảm phải có dạng cố định — chỉ bộ đếm và bộ cộng dồn. Ngay khi bạn nhét các dòng khớp vào một mảng trong bộ giảm, bộ nhớ lại chạy theo thể tích dữ liệu và streaming chẳng còn giá trị gì.

Vậy nên có 3,5 MB trong bảng: hai gigabyte đã chảy qua, chỉ còn lại một bảng băm.

Một tài liệu lớn duy nhất: các sự kiện đường dẫn của --stream

Khi đầu vào là một tài liệu gốc khổng lồ duy nhất (một bản export vài trăm MB không ranh giới dòng), dùng --stream. Thay vì giá trị đầy đủ, nó phát chuỗi sự kiện «đường dẫn + giá trị lá»:

# một sự kiện trông như: mảng đường dẫn + vô hướng
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"

Trích xuất từ dòng sự kiện đòi khớp hình dạng đầy đủ của đường dẫn — độ sâu, tên thành viên, vị trí chỉ số —, vì chỉ kiểm tra thành phần cuối sẽ bắt luôn các khóa trùng tên trong object lồng nhau:

# chỉ rows[i].id, bỏ qua meta.id và các đồng danh sâu hơn
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json

Tổng hợp vẫn là reduce inputs dạng cố định (với -n --stream, sự kiện phải được tiêu thụ qua inputs — xem các bẫy). Để tái dựng — biến dòng sự kiện trở lại thành object nguyên vẹn — kết hợp truncate_stream và fromstream. Tổng quan chọn công cụ theo kích thước nằm ở Tệp JSON quá lớn?.

Ba bẫy thực tế

Bẫy một: -n --stream không có inputs không in ra gì, lặng lẽ. Ghi nhận trên chính máy này: jq -n --stream 'select(...)' file.json kết thúc với mã 0, không đầu ra không lỗi — ở chế độ -n, jq không đọc đầu vào, và select của filter không nhận sự kiện nào. Đúng: bỏ -n và dùng --stream trần, hoặc ghép -n --stream với reduce inputs. Loại thất bại «thành công nhưng rỗng» này khó debug nhất; hãy kiểm chứng trên mẫu nhỏ trước khi đi dây pipeline.

Bẫy hai: --stream chỉ phát lá vô hướng; object và array rỗng không có sự kiện giá trị. {"a":{}} chỉ sinh một sự kiện đóng đường dẫn (loại length == 1), và filter trên length == 2 sẽ lặng lẽ nuốt các container rỗng — hãy quyết định rõ ràng chúng có tính vào thống kê của bạn hay không.

Bẫy ba: kết quả một phần sau lỗi parse giữa chừng tệp. Một pipeline streaming có thể đã phát nửa đầu ra trước khi vấp JSON hỏng về cuối. jq 1.7 mặc định thất bại ồn ào — [1,] đã tạo parse error: Expected another array element at line 1, column 4 với mã 5 trong thử nghiệm của chúng tôi — nhưng nếu shell của bạn redirect stdout vào tệp đích, kết quả cụt đã nằm trên đĩa. Tấm khiên kỹ thuật: staging cộng rename — ghi vào tệp tạm và mv đè lên đích chỉ sau khi jq thành công. Muốn kiểm soát tinh hơn, --stream-errors biến lỗi parse thành sự kiện bạn có thể xử lý và chủ động ngắt qua error.

Khi nào không dùng jq: Miller và pipeline lai

jq là ngôn ngữ hàm biến đổi cây, mạnh ở tái cấu trúc sâu. Nhưng khi công việc thoái hóa thành «lọc và đếm gigabyte log phẳng», có những công cụ được cắt may tốt hơn. Benchmark của dratini.tech trên 2,5 GB JSONL (lọc + chọn cột):

Công cụ Thời gian RSS đỉnh
pipeline jq thường 48,2s 84 MB
jq -s OOM (bị giết cả với 16 GB+) —
Miller (mlr --json) 11,4s 18 MB
ripgrep + jq lai 8,1s 32 MB

Quy tắc: lồng sâu, tái cấu trúc, hiện diện khắp nơi trong CI — jq. Thống kê phẳng hàng gigabyte, phân vị p95, JSONL sang TSV — một lệnh mlr --json stats1 thay cả script jq với bộ nhớ không đổi. Và nếu ripgrep có thể loại 90 % dòng thừa trước jq, phương án lai nhanh nhất.

FAQ

Từ kích thước nào jq -s trở nên nguy hiểm?

Ngưỡng thực dụng: ngay khi tệp vượt quá một nửa bộ nhớ khả dụng, hãy hoài nghi. Bộ nhớ sau parse thường gấp 3–10 lần văn bản (9,5x với 220 MB của chúng tôi; ghi nhận bên ngoài cho thấy tệp 4 GB giết máy 16 GB). So ls -lh với free -m trước, và gần ngưỡng thì thay -s bằng reduce inputs.

Vì sao có -n trước reduce inputs?

-n bảo jq đừng tiêu thụ đầu vào đầu tiên làm giá trị khởi tạo của chương trình, để inputs tự phát từng bản ghi. Thiếu -n, bản ghi đầu trở thành trạng thái khởi tạo của reduce và lặng lẽ biến mất khỏi kết quả — mất dữ liệu mà không một lỗi nào.

Chọn giữa --stream và chế độ thường thế nào?

Trước hết nhìn hình dạng tệp. JSONL vốn đã là dòng từng dòng; --stream chẳng giúp gì. Với một tài liệu lớn duy nhất mà bạn chỉ cần vài giá trị lá, --stream đổi khoảng 3x thời gian lấy bộ nhớ nhỏ gấp trăm lần. Nếu tệp vừa bộ nhớ, jq thường đơn giản nhanh hơn.

Xử lý dòng hỏng khi streaming ra sao?

Trong JSONL, fromjson? bỏ qua các dòng không parse được để một dòng bẩn không giết pipeline. Với một tài liệu lớn duy nhất, lỗi parse giữa chừng làm sập cả lượt chạy — hãy phát hành nguyên tử qua tệp staging và rename, hoặc dùng --stream-errors để kiểm soát tường minh.