jq и большие JSON-файлы: почему -s переполняет память и как писать потоково
Главное: Агрегация сотен мегабайт JSON-логов через jq -s заканчивается OOM, а reduce inputs делает ту же статистику в нескольких мегабайтах памяти. На образце 220MB и 2 миллионов строк измерено: slurp даёт пик 2,08GB против 3,5MB у потокового редьюсера. Разбираем механизм расхода памяти, построчную обработку JSONL, события путей в --stream и три реальные ловушки, включая тихий пустой вывод -n --stream.

jq парсит быстро, но почти каждая смерть на файле в пару сотен мегабайт связана с одним флагом:
-sзагружает весь ввод в один гигантский массив, и пиковый RSS легко превышает размер файла в несколько раз.
Один файл, два запроса — разница в памяти 580 раз
Начнём с измерения. Образец — JSONL-лог 220MB и 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,1s | 2,08 GB (~9,5x размера файла) |
jq -n 'reduce inputs ...' |
тот же подсчёт | 4,7s | 3,5 MB |
jq -r 'select(...) | .path' |
построчный фильтр | 2,6s | 3,6 MB |
Та же статистика, в 580 раз меньше памяти и быстрее по времени. Это не баг jq — -s по определению «читает всё в один массив»; большинство просто не закладывает этот дефолтный ценник. Сторонние цифры совпадают: разбор 2,3GB JSONL в сообществе Huawei Cloud показывает тот же сюжет — OOM от slurp, затем потоковый редьюсер завершается за 47 секунд при RSS чуть больше 30MB. Dratini.tech на 2,5GB ввода зафиксировал, что jq -s убивается OOM killer даже на машине с 16GB+, тогда как обычный конвейер проходит за 48,2s при 84MB.
Вывод сначала: если файл больше половины доступной памяти, -s даже не рассматриваем. Перед работой измерьте три вещи: ls -lh для размера, free -m для запаса памяти, wc -l для числа строк.
Куда на самом деле уходит память
jq -s (slurp) документирован как «прочитать все входы в массив». Реальная цена куда больше текста: после парсинга jq держит дерево из C-структур, и каждый объект, массив, строка и число несёт собственный узел и метаданные. Наши 220MB текста превратились чуть больше чем в 2GB структур — раздувание примерно в 9,5 раза. group_by дополнительно сортирует и группирует в памяти, поднимая пик ещё выше.
С одним большим документом то же самое. Упаковав тот же лог в 300MB массив верхнего уровня и извлекая обычным фильтром:
| Запрос | Время | Пиковый RSS |
|---|---|---|
jq '.[] | select(.level=="ERROR") | .uid' (весь документ) |
4,7s | 1,85 GB |
jq --stream 'select(...)' (события путей) |
13,4s | 3,4 MB |
Полный парсинг всё равно упирается в пик около 1,8GB — jq строит всё дерево целиком, прежде чем запустится фильтр. --stream меняет примерно 3-кратное время выполнения на память меньше в 540 раз. Подробная модель, на каких этапах происходит раздувание, — в статье Откуда берётся память.
JSONL-логи: построчное чтение — уже поток
Если ваш «большой файл» — это на самом деле JSONL, по объекту в строке, то jq по умолчанию уже стримит: каждая строка парсится и выводится независимо, а -s не просто не нужен — он вреден:
# подсчёт по level: построчно, агрегация средствами shell
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 держит состояние ограниченным
Построчная фильтрация — дело shell, но когда агрегация должна произойти внутри jq — счётчики по level, среднее время по path, — ключ в том, чтобы reduce с inputs держал состояние bounded:
# счёт по 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означает: не считать первый ввод начальным значением программы;inputsсам выдаёт каждую запись. Без-nпервая запись будет проглочена как начальное состояние.- Состояние редьюсера должно иметь фиксированную форму — только счётчики и аккумуляторы. Стоит начать push-ить совпавшие строки в массив внутри редьюсера, и память снова растёт вместе с данными — стриминг обесценен.
Отсюда и 3,5MB в таблице: через два гигабайта данных прошло, осталось одно хеш-таблица.
Один большой документ: события путей в --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: сначала отрезаем ведущие сегменты пути, затем 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 молча проглотит пустые контейнеры — включать ли их в статистику, решайте явно.
Ловушка третья: частичный результат после parse error в середине файла. Потоковый конвейер может уже вывести половину, а споткнуться о битый JSON ближе к концу. jq 1.7 по умолчанию падает громко — [1,] в нашем тесте дал parse error: Expected another array element at line 1, column 4 с кодом 5, — но если shell перенаправил stdout в целевой файл, усечённый результат уже на диске. Инженерное решение — staging плюс rename: пишем во временный файл и mv поверх цели только после успеха jq. Тоньше — --stream-errors: ошибки парсинга становятся событиями, которые можно обработать и явно прервать через error.
Когда jq — не лучший выбор: Miller и гибриды
jq — функциональный язык преобразования деревьев, силён в глубокой реструктуризации. Но когда задача вырождается в «отфильтровать и посчитать гигабайты плоских логов», есть инструменты точнее. Бенчмарк dratini.tech на 2,5GB JSONL (фильтр + выбор колонок):
| Инструмент | Время | Пиковый RSS |
|---|---|---|
| jq обычный конвейер | 48,2s | 84 MB |
| jq -s | OOM (убит даже на 16GB+) | — |
| Miller (mlr --json) | 11,4s | 18 MB |
| ripgrep + jq | 8,1s | 32 MB |
Правило: глубокая вложенность, перестройка структуры, повсеместность в CI — jq. Многогигабайтная плоская статистика JSONL, перцентили p95, перевод JSONL в TSV — одна команда mlr --json stats1 заменяет jq-скрипт при постоянной памяти. А если ripgrep может отсеять 90% нерелевантных строк до jq, гибрид быстрее всех.
FAQ
С какого размера файла jq -s становится опасен?
Практический порог: как только файл превышает половину доступной памяти — насторожитесь. Память после парсинга обычно в 3-10 раз больше текста (9,5x на наших 220MB; в сторонних записях 4GB-файл убивал машину на 16GB). Сначала сравните ls -lh и free -m, и если близко — замените -s на reduce inputs.
Почему перед reduce inputs нужен -n?
-n говорит jq не считать первый ввод начальным значением программы, чтобы inputs сам выдал все записи. Без -n первая запись станет начальным состоянием reduce и молча исчезнет из результата — потеря данных без единой ошибки.
Как выбирать между --stream и обычным режимом?
Сначала посмотрите на форму файла. JSONL уже стримится построчно — --stream не нужен. Для одного большого документа, из которого нужны лишь несколько листовых значений, --stream отдаёт примерно 3x времени за память меньше в сотни раз. Если файл помещается в память, обычный jq просто быстрее.
Что делать с битыми строками при потоковой обработке?
В JSONL — fromjson?, пропускающий непарсящиеся строки, чтобы одна грязная строка не убила конвейер. В одном большом документе parse error в середине валит выполнение — публикуйте атомарно через staging-файл и rename, чтобы частичный вывод не оказался в целевом файле; для явного контроля есть --stream-errors.