JSON Toolkit

jq та великі JSON-файли: чому -s вибухає пам'яттю і як писати в потоці

Головне: Агрегація сотень МБ JSON-логів через jq -s завершується OOM, тоді як reduce inputs дає ту саму статистику за кілька МБ RAM. Виміряно на вибірці 220 МБ і 2 мільйонів рядків: slurp кульмінує на 2,08 ГБ проти 3,5 МБ у потокового редуктора. Стаття пояснює механізм споживання пам'яті, построкову обробку JSONL, події шляхів --stream і три реальні пастки, зокрема тихий порожній вихід -n --stream.

Просунутий~6 хв читанняОпубліковано 2026-11-12Оновлено 2026-11-12
Порівняння пам'яті між потоковим jq та -s на великих JSON

jq парсить швидко, але майже кожна смерть на файлі кілька сотень МБ зводиться до того самого флага: -s завантажує весь вхід в один гігантський масив, а піковий RSS легко досягає кратності розміру файлу.

Один файл, два запити: у 580 разів менше пам'яті

Почнімо з вимірювання. Вибірка — JSONL-лог на 220 МБ і 2 000 000 рядків (запис запиту на рядок: timestamp, level, path, status, duration_ms, uid). Середовище: jq 1.7 на Linux x86_64, піковий RSS зафіксовано через /usr/bin/time -v:

Запит Задача Час Піковий RSS
jq -s 'group_by(.level) | ...' підрахунок за level 10,1с 2,08 ГБ (~9,5x розміру файлу)
jq -n 'reduce inputs ...' той самий підрахунок 4,7с 3,5 МБ
jq -r 'select(...) | .path' фільтр рядок за рядком 2,6с 3,6 МБ

Та сама статистика, у 580 разів менше пам'яті, і ще й швидше. Це не баг jq — -s за визначенням означає «прочитати все в масив»; більшість людей просто не оцінюють цей типовий витрат. Сторонні джерела сходяться: звіт про 2,3 ГБ JSONL зі спільноти Huawei Cloud розповідає точнісінько ту саму історію — OOM зі slurp, далі потоковий редуктор, що завершується за 47 секунд трохи понад 30 МБ RSS. Dratini.tech виміряла на 2,5 ГБ входу jq -s, убитий OOM-кілером навіть на машині з 16 ГБ+, тоді як звичайний пайплайн завершувався за 48,2с при 84 МБ.

Висновок наперед: якщо файл перевищує половину доступної пам'яті, -s навіть не кандидат. Виміряйте три речі, перш ніж щось писати: ls -lh для розміру, free -m для запасу пам'яті, wc -l для кількості рядків.

Куди насправді іде пам'ять

jq -s (slurp) задокументовано як «прочитати всі входи в масив». Реальний витрат далеко перевершує текст: після парсингу jq тримає дерево C-структур, і кожен об'єкт, масив, рядок і число несуть власний вузол із метаданими. Наші 220 МБ тексту стали трохи більш ніж 2 ГБ структур — роздування близько 9,5x. group_by додатково сортує й групує в пам'яті, посилюючи пік.

Один великий JSON-документ поводиться так само. Запакувавши той самий лог у кореневий масив на 300 МБ і витягаючи звичайним фільтром:

Запит Час Піковий RSS
jq '.[] | select(.level=="ERROR") | .uid' (цілий документ) 4,7с 1,85 ГБ
jq --stream 'select(...)' (події шляхів) 13,4с 3,4 МБ

Повний парсинг кульмінує досі близько 1,8 ГБ — jq будує все дерево, перш ніж фільтр виконається. --stream обмінює приблизно 3x час виконання на пам'ять у 540 разів меншу. Детальну модель цього роздування розгорнуто в Звідки береться пам'ять.

JSONL-логи: построкове читання — це вже потік

Якщо ваш «великий файл» насправді JSONL — один об'єкт на рядок —, типова поведінка jq вже є потоком: кожен рядок парситься й випромінюється незалежно, а -s не лише непотрібне, а й шкідливе:

# підрахунок за level: рядок за рядком, агрегація в шеллі
jq -r '.level' app.jsonl | sort | uniq -c | sort -rn | head

# фільтр + екстракція: select спершу, рядки без збігу одразу викинуті
jq -r 'select(.level=="ERROR") | .path' app.jsonl | sort | uniq -c | sort -rn | head -5

Дві звички, які варто нав'язати:

  • select на самому початку пайплайну. jq фільтрує щойно рядок спарсено; фільтрувати після перетворень — марнувати обчислення.
  • -r для сирих рядків. Без нього вихід — JSON-рядок у лапках, і uniq -c порахує "ERROR" і ERROR як два різні значення.

Для пошкоджених рядків використовуйте fromjson?: jq -r 'fromjson? | .level' тихо пропускає рядки, що не парсяться, а обірваний фрагмент не вбиває весь пайплайн. Сам формат описано в Практичний довідник JSONL; ця стаття — про команди, що його обробляють.

Глобальна агрегація: reduce inputs тримає стан обмеженим

Построкова фільтрація належить шеллу, але коли агрегація мусить відбутися в самому jq — лічильники за level, середня тривалість за path —, ключем є reduce з inputs, для обмеженого стану:

# підрахунок за level: пам'ять слідує за розміром результату, не файлу
jq -n 'reduce inputs as $x ({}; .[$x.level] = ((.[$x.level] // 0) + 1))' app.jsonl

# середня тривалість за path: стан — фіксована пара {count, total}
jq -n 'reduce inputs as $x ({}; .[$x.path].count += 1 | .[$x.path].total += $x.duration_ms)
      | map_values(.total / .count)' app.jsonl

Два деталі:

  • -n означає, що jq не має споживати перший вхід як початкове значення; inputs саме випромінює кожен запис. Забудете -n — і перший запис проковтнуто як початковий стан.
  • Стан редуктора мусить мати фіксовану форму — лише лічильники та акумулятори. Щойно ви заштовхаєте збіжні рядки в масив усередині редуктора, пам'ять знову мчить за об'ємом даних, і потік вже нічого не вартий.

Звідси 3,5 МБ у таблиці: пройшло два гігабайти, лишився лиш хеш-масив.

Один величезний документ: події шляхів --stream

Коли вхід — єдиний величезний кореневий документ (експорт кілька сотень МБ без меж рядків), використовуйте --stream. Замість повних значень він випромінює послідовність подій «шлях + листове значення»:

# подія виглядає так: масив шляху + скаляр
$ echo '{"rows":[{"id":"a"},{"id":"b"}],"meta":{"id":"top"}}' | jq -c --stream .
["rows",0,"id"]
"a"
["rows",1,"id"]
"b"
["meta","id"]
"top"

Витягування з потоку подій вимагає зіставлення повної форми шляху — глибини, імен полів, позицій індексів —, бо перевірка лише останнього компонента зачепить і однойменні ключі у вкладених об'єктах:

# лише rows[i].id, ігноруючи meta.id та глибших тезок
jq --stream 'select(length == 2 and .[0][0] == "rows" and .[0][-1] == "id") | .[1]' huge.json

Агрегація лишається reduce inputs фіксованої форми (за -n --stream події слід споживати через inputs — див. пастки). Для реконструкції — перетворення потоку подій назад на цілі об'єкти — поєднуйте truncate_stream і fromstream. Огляд вибору інструментів за розміром — у JSON-файл завеликий?.

Три реальні пастки

Пастка перша: -n --stream без inputs не виводить нічого, тихо. Зафіксовано на цій машині: jq -n --stream 'select(...)' file.json завершується кодом 0, без виводу й без помилки — у режимі -n jq не читає вхід, і select фільтра не отримує жодної події. Правильно: приберіть -n і використайте голе --stream, або спарте -n --stream з reduce inputs. Цей клас збоїв «успіх, але порожньо» найважче дебажити; валідуйте на малій вибірці, раніше ніж сплетете пайплайн.

Пастка друга: --stream випромінює лише скалярні листи; порожні об'єкти й масиви не мають події значення. {"a":{}} дає лише подію закриття шляху (типу length == 1), а фільтр по length == 2 тихо проковтне порожні контейнери — вирішіть явно, чи рахуються вони у вашій статистиці.

Пастка третя: частковий результат після помилки парсингу посеред файлу. Потоковий пайплайн може вже вивести половину виходу, перш ніж спіткнеться об зламаний JSON ближче до кінця. jq 1.7 падає гучно — [1,] видало parse error: Expected another array element at line 1, column 4 з кодом 5 у нашому тесті — але якщо ваш шелл перенаправляє stdout у цільовий файл, обрізаний результат уже лежить на диску. Інженерний щит: staging плюс rename — писати в тимчасовий файл і переміщувати на ціль лише після успішного прогону jq. Для тоншого контролю --stream-errors перетворює помилки парсингу на події, які можна обробити й явно перервати через error.

Коли не використовувати jq: Miller і гібридні пайплайни

jq — функційна мова трансформації дерев, сильна в глибокій реструктуризації. Але щойно задача вироджується в «відфільтруй і порахуй гігабайти пласких логів», існують краще скроєні інструменти. Бенчмарк dratini.tech на 2,5 ГБ JSONL (фільтр + вибір колонок):

Інструмент Час Піковий RSS
звичайний jq-пайплайн 48,2с 84 МБ
jq -s OOM (убитий навіть з 16 ГБ+) —
Miller (mlr --json) 11,4с 18 МБ
ripgrep + jq гібрид 8,1с 32 МБ

Правило: глибоке вкладення, реструктуризація, всюдисущість у CI — jq. Пласкі статистики на гігабайтах, перцентилі p95, JSONL у TSV — одне mlr --json stats1 замінює jq-скрипт при сталий пам'яті. А якщо ripgrep здатен відсіяти 90 % зайвих рядків до jq, гібрид найшвидший.

FAQ

З якого розміру jq -s стає небезпечним?

Практична межа: щойно файл перевищує половину доступної пам'яті — насторожіться. Пам'ять після парсингу зазвичай вартує 3–10x тексту (9,5x на наших 220 МБ; сторонні звіти показують файл 4 ГБ, що вбиває машину 16 ГБ). Спершу порівняйте ls -lh з free -m і близько межі замініть -s на reduce inputs.

Чому -n перед reduce inputs?

-n каже jq не споживати перший вхід як початкове значення програми, щоб inputs саме випромінювало кожен запис. Без -n перший запис стає початковим станом reduce й тихо зникає з результату — втрата даних без жодної помилки.

Як обрати між --stream і звичайним режимом?

Спершу гляньте на форму файлу. JSONL — вже потік рядок за рядком; --stream не потрібен. Для одного великого документа, з якого вам треба лише кілька листових значень, --stream обмінює близько 3x часу на сотні разів менше пам'яті. Якщо файл вміщується в пам'ять, звичайний jq просто швидший.

Що робити з пошкодженими рядками під час стрімінгу?

У JSONL fromjson? пропускає рядки, що не парсяться, щоб єдиний брудний рядок не вбив пайплайн. У єдиному великому документі помилка парсингу посеред файлу валить прогін — публікуйте атомарно через staging-файл і rename, або використайте --stream-errors для явного контролю.