Коротко о главном
JSON встречается в API, конфигурациях, логах и выводе облачных утилит. jq превращает его в удобный поток данных, который можно фильтровать и агрегировать. В статье разберём выборку полей, работу с массивами, безопасное редактирование и разбор JSON Lines. Материал рассчитан на разработчиков и администраторов с базовым опытом терминала.
Ручной просмотр JSON быстро становится неудобным при большой вложенности. jq даёт точный доступ к нужным полям и позволяет строить компактные отчёты. Скрипты с jq легче автоматизировать и проверять, чем разбор через регулярные выражения. Инструмент также помогает диагностировать API и конфигурации.
jq редко ломается сам по себе. Чаще проблема в неверной конфигурации, устаревшей версии или команде, скопированной без понимания. Разберём типичные сбои и способы их исправления.
Почему это происходит
Ошибки почти всегда связаны с контекстом: другая версия пакета, не тот пользователь, устаревший конфиг или команда из руководства для другой системы. jq не исключение. Поэтому сначала фиксируем исходное состояние, затем меняем одну вещь за раз.
Типичные ошибки
Ниже — сбои, которые встречаются чаще всего. Перед исправлением сохраните текущие конфиги и запишите, какие изменения вносите: так проще откатиться.
1. jq выдаёт parse error: Invalid numeric literal.
Входные данные не являются корректным JSON. Проверьте файл целиком, лишний текст до или после документа и корректность кавычек.
2. Ошибка Cannot index string with string.
Фильтр предполагает объект, а на этом уровне находится строка или массив. Просмотрите структуру через jq ‘type’ и скорректируйте путь.
3. Команда работает в терминале, но ломается в скрипте.
Проверьте кавычки и передачу аргументов. Фильтр jq лучше заключать в одинарные кавычки, а значения передавать через —arg.
4. jq не находит файл или читает пустой поток.
Проверьте путь и права доступа. Если вход формируется конвейером, убедитесь, что предыдущая команда завершилась успешно и что-то вывела.
Как настроить правильно
Правильная последовательность проста: проверить версию и зависимости, сделать резервную копию конфигурации, внести минимальное изменение, проверить логи и только потом двигаться дальше.
Установка
В Debian, Ubuntu и Linux Mint используется пакетный менеджер APT:
sudo apt install jq
В Fedora и RHEL-совместимых системах пакет ставится через DNF:
sudo dnf install jq
В Arch Linux и производных пакет доступен в официальных репозиториях:
sudo pacman -S jq
1. Прочитайте и отформатируйте JSON
Фильтр . возвращает документ без изменений, а jq печатает его с отступами. Это удобно для проверки структуры после ответа API. Если файл содержит несколько JSON-документов, поведение нужно проверять отдельно.
jq '.' package.json
2. Выберите поля и отфильтруйте массив
Точечная нотация обращается к ключам, а квадратные скобки выбирают элементы массива. Функция select оставляет объекты, удовлетворяющие условию. Комбинируйте фильтры через вертикальную черту.
jq '.dependencies | keys[]' package.json
jq '.items[] | select(.active)' data.json
3. Получите сырой или компактный вывод
Флаг -r убирает JSON-кавычки у строк, что удобно для shell-переменных. Флаг -c печатает документ в одну строку. Сырой вывод безопасен только тогда, когда вы контролируете формат данных.
jq -r '.name' package.json
jq -c '.scripts' package.json
4. Объедините несколько файлов
Флаг -s собирает все входные документы в один массив. После этого можно применить map и извлечь нужные поля. Это полезно для отчётов по нескольким ответам API.
jq -s 'map(.id)' a.json b.json
Рабочий конфиг
Начните с минимального рабочего варианта. Не копируйте большой конфиг целиком: добавляйте параметры по одному и проверяйте результат после каждого изменения.
# ~/.jq
def compact: with_entries(select(.value != null));
def only_keys: keys | sort;
Практические советы
Эти рекомендации проверены на повседневных задачах. Начните с тех, которые закрывают вашу текущую боль, а не со всего списка сразу.
Совет 1. Используйте —arg name value для безопасной передачи строк из оболочки
Используйте —arg name value для безопасной передачи строк из оболочки вместо ручной сборки JSON.
Совет 2. Флаг -e возвращает ненулевой код, если результат равен false или null;
Флаг -e возвращает ненулевой код, если результат равен false или null; это удобно в проверках.
Совет 3. Флаг -S сортирует ключи и делает вывод стабильным для сравнения файлов
Флаг -S сортирует ключи и делает вывод стабильным для сравнения файлов.
Совет 4. Функция del удаляет поле: jq ‘del(.secret)’ config.json.
Функция del удаляет поле: jq ‘del(.secret)’ config.json.
Профилактика
Большинство повторяющихся сбоев с jq связано не с ошибкой в самой программе, а с окружением: обновились зависимости, изменился путь, закончилось место или другой администратор поправил конфиг. Поэтому профилактика начинается с фиксации исходного состояния.
Сохраните рабочий конфиг в систему контроля версий, добавьте короткий комментарий о том, зачем нужен каждый нестандартный параметр, и запишите команду проверки. Через месяц вы скажете себе спасибо: восстановить логику по чужому файлу без пояснений почти невозможно.
Чек-лист
- Версия пакета и конфигурация зафиксированы и доступны для сравнения.
- Есть автоматическая проверка синтаксиса перед перезапуском службы.
- Журналы ротуются, а диск не заполняется ими за неделю.
- Изменения проходят через тестовый стенд, а не сразу на рабочий сервер.
Итог
Большинство ошибок с jq лечится не переустановкой, а проверкой конфигурации, логов и прав доступа. Действуйте по одному изменению за раз — и причина быстро найдётся.