Коротко о главном

JSON встречается в API, конфигурациях, логах и выводе облачных утилит. jq превращает его в удобный поток данных, который можно фильтровать и агрегировать. В статье разберём выборку полей, работу с массивами, безопасное редактирование и разбор JSON Lines. Материал рассчитан на разработчиков и администраторов с базовым опытом терминала.

Ручной просмотр JSON быстро становится неудобным при большой вложенности. jq даёт точный доступ к нужным полям и позволяет строить компактные отчёты. Скрипты с jq легче автоматизировать и проверять, чем разбор через регулярные выражения. Инструмент также помогает диагностировать API и конфигурации.

В этой подборке — практические приёмы для jq, которые можно применить сразу после установки. Каждый пункт объясняет не только «что нажать», но и зачем это нужно.

С чего начать

Не пытайтесь применить всё сразу. Сначала настройте окружение так, чтобы команды было удобно повторять, а результаты — проверять. Для 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

Практические советы

Эти рекомендации проверены на повседневных задачах. Начните с тех, которые закрывают вашу текущую боль, а не со всего списка сразу.

Совет 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.

Совет 5. Отсутствующий ключ даёт null, поэтому проверяйте результат через // ил

Отсутствующий ключ даёт null, поэтому проверяйте результат через // или select.

Совет 6. Не пытайтесь менять файл через перенаправление в него же: оболочка обр

Не пытайтесь менять файл через перенаправление в него же: оболочка обрежет файл до запуска jq.

Совет 7. Для больших потоков избегайте -s: slurp загружает весь вход в память.

Для больших потоков избегайте -s: slurp загружает весь вход в память.

Настройки, которые стоит сохранить

Начните с минимального рабочего варианта. Не копируйте большой конфиг целиком: добавляйте параметры по одному и проверяйте результат после каждого изменения.

# ~/.jq
def compact: with_entries(select(.value != null));
def only_keys: keys | sort;

Типичные ошибки

Ниже — сбои, которые встречаются чаще всего. Перед исправлением сохраните текущие конфиги и запишите, какие изменения вносите: так проще откатиться.

1. jq выдаёт parse error: Invalid numeric literal.

Входные данные не являются корректным JSON. Проверьте файл целиком, лишний текст до или после документа и корректность кавычек.

2. Ошибка Cannot index string with string.

Фильтр предполагает объект, а на этом уровне находится строка или массив. Просмотрите структуру через jq ‘type’ и скорректируйте путь.

3. Команда работает в терминале, но ломается в скрипте.

Проверьте кавычки и передачу аргументов. Фильтр jq лучше заключать в одинарные кавычки, а значения передавать через —arg.

Практический сценарий

Представьте типовую задачу: нужно развернуть jq на одной машине, проверить работу и передать доступ коллеге. Начните с чистой системы или снапшота, чтобы результат был воспроизводим. Запишите все команды в отдельный файл — это одновременно шпаргалка и черновик будущей автоматизации.

Дальше действуйте короткими шагами: установка, минимальная конфигурация, проверка, затем расширение. После каждого шага фиксируйте, что именно изменилось и как это проверить. Такой журнал экономит время, когда через месяц понадобится повторить настройку на другом сервере или объяснить её коллеге.

Порядок работ для этого сценария выглядит так:

  1. Прочитайте и отформатируйте JSON
  2. Выберите поля и отфильтруйте массив
  3. Получите сырой или компактный вывод
  4. Объедините несколько файлов
  5. Измените файл через временную копию
  6. Разберите JSON Lines из логов

Отдельно продумайте, что произойдёт при сбое. Для jq важно заранее знать, где хранятся данные, как их скопировать и сколько времени займёт восстановление. Если ответа нет, не двигайтесь дальше: сначала закройте этот пробел, потом добавляйте новые возможности.

Что проверить перед вводом в работу

Перед тем как считать настройку завершённой, пройдитесь по короткому списку. Он не заменяет полноценный аудит, но отсекает большинство очевидных проблем.

Чек-лист

  • Версия jq зафиксирована, а обновления не применяются вслепую.
  • Есть резервная копия конфигурации и данных, восстановление проверено.
  • Доступ ограничен нужными пользователями и сетями, лишние порты закрыты.
  • Логи и метрики собираются, понятно, куда смотреть при сбое.
  • Изменения описаны в документации и могут быть повторены на другой машине.
  • Есть план отката и понятный критерий, по которому вы решите его применить.

Если какой-то пункт вызывает затруднение, это сигнал вернуться к соответствующему разделу, а не откладывать проверку. Настройка, которую нельзя повторить, плохо работает не только у коллег, но и у вас самих через полгода.

Итог

Главная ценность приёмов выше — в экономии внимания. Выберите два-три, доведите до автоматизма, и jq перестанет отнимать время на рутину.

Насколько публикация полезна?

Нажмите на звезду, чтобы оценить!

Средняя оценка 0 / 5. Количество оценок: 0

Оценок пока нет. Поставьте оценку первым.

Поделиться: Telegram ВКонтакте