JSON Toolkit

jq и большие JSON-файлы: почему -s переполняет память и как писать потоково

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

Продвинутый~6 мин чтенияОпубликовано 2026-11-12Обновлено 2026-11-12
Сравнение памяти потоковой обработки jq и -s на больших JSON-файлах

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.