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

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 для явного контролю.