jq — работа с JSON в командной строке Linux

Быстрые ссылки

• JSON и jq

• Как установить jq

• Как сделать JSON удобочитаемым

• Доступ к значениям данных

• Работа с массивами

• Использование пайпов с фильтрами

• Создание массивов и изменение результатов

• Более сложные объекты JSON

• Функция length

• Функция keys

• Функция has()

• Не работайте с JSON без него

Коротко о JSON и jq

JSON (JavaScript Object Notation) — текстовый формат для передачи сериализованных данных. В JSON нет комментариев: структура и ключи сами описывают содержимое. Элементы представлены парами ключ:значение. Объекты — это наборы таких пар, заключённые в фигурные скобки { }, массивы — упорядоченные списки в квадратных скобках [ ].

jq — утилита для чтения, фильтрации и преобразования JSON прямо в терминале. Она полезна как при работе с аккуратно составленным JSON, так и с «хаотичным» выводом API. jq поддерживает фильтры, пайпы, арифметику, создание новых объектов и многое другое.

Важно: Bash сам по себе не умеет парсить JSON корректно, поэтому jq решает эту проблему просто и надёжно.

Как установить jq

Примеры инсталляции для популярных дистрибутивов:

sudo apt-get install jq

sudo dnf install jq

sudo pacman -Sy jq

Если вы используете другой дистрибутив — установите пакет из репозиториев или соберите из исходников. На macOS обычно используется brew: brew install jq.

Как сделать JSON удобочитаемым

JSON часто передают как одну длинную строку. Чтобы читать его человеку, нужно отформатировать (pretty-print). Самый простой jq-фильтр — точка (.). Он означает «вывести весь объект», а по умолчанию jq форматирует вывод красиво.

Пример: получаем текущую позицию МКС от публичного API и форматируем:

curl -s http://api.open-notify.org/iss-now.json | jq .

Если нужно сохранить в файл:

curl -s http://api.open-notify.org/iss-now.json | jq . > iss.json

cat iss.json

Доступ к значениям данных

jq позволяет выбирать отдельные ключи. Используйте точечную нотацию: .ключ — это фильтр, который возвращает значение ключа.

Примеры работы с файлом iss.json:

jq .message iss.json

jq .timestamp iss.json

Для вложенных объектов используйте путь через точки:

jq .iss_position.latitude iss.json

Чтобы получить несколько значений сразу, перечислите фильтры через запятую и возьмите строку в кавычки:

jq ".iss_position.latitude, .timestamp" iss.json

Если ключ содержит пробелы или специальные символы, обёртывайте его в кавычки и экранируйте в соответствии с shell-контекстом.

Работа с массивами

Массивы в JSON обрабатываются с помощью []: .arrayName[] — пройти по всем элементам массива. Пример: список космонавтов из API.

Скачиваем и сохраняем:

curl -s http://api.open-notify.org/astros.json | jq . > astro.json

Просмотр файла:

less astro.json

Извлечём все имена:

jq ".people[].name" astro.json

Выбор конкретного элемента по индексу (нумерация начинается с 0):

jq ".people[1].name" astro.json

Поддерживается отрицательная индексация (например, -1 — последний элемент):

jq ".people[-1].name" astro.json

Срезы (slicing): .array[start:end] вернёт элементы от start до end-1. Пример:

jq ".people[2:4]" astro.json

Использование пайпов с фильтрами

В jq есть свой оператор пайпа |, он передаёт вывод одного фильтра во вход следующего. Это удобно для компоновки шагов обработки.

Пример: перечислим имена с применением пайпа:

jq ".people[] | .name" astro.json

Пайпы позволяют комбинировать фильтры, отфильтровывать по условию, менять форму результата.

Создание массивов и изменение результатов

jq может не только выбирать данные, но и создавать новые структуры. Скобки [ ] в фильтре создают массив.

Пример создания нового массива из ключей iss.json:

jq "[.iss_position.latitude, .iss_position.longitude, .timestamp]" iss.json

Арифметика с числовыми значениями:

jq ".timestamp" iss.json

jq ".timestamp - 1570000000" iss.json

Удаление ключей из вывода: del(filteR). Это удаляет ключ только в выводе команды, не меняет файл, если не перенаправлять вывод в новый файл.

jq "del(.message)" iss.json

Более сложные объекты JSON

Рассмотрим большой набор данных с информацией о метеоритных ударах (strikes.json). Множество объектов, вложенные структуры и массивы внутри объектов — обычная ситуация.

Скачиваем и сохраняем:

curl -s https://data.nasa.gov/resource/y77d-th95.json | jq . > strikes.json

Просмотр:

less strikes.json

Чтобы получить имена с 995-го элемента до конца:

jq ".[995:] | .[] | .name" strikes.json

Чтобы выбрать последние 10 элементов:

jq ".[-10:] | .[] | .name" strikes.json

Пример получения среза строки (первые 4 символа имени):

jq "(.[234].name)[0:4]" strikes.json

Вывод целого объекта по индексу:

jq "(.[234])" strikes.json

Вывод только значений объекта без имён ключей:

jq "(.[234])[]" strikes.json

Извлечение нескольких значений для диапазона индексов:

jq "(.[450:455]) | .[] | .name, .mass" strikes.json

Доступ к вложенному массиву coordinates внутри geolocation:

jq "(.[121].geolocation.coordinates[])" strikes.json

Функция length

Функция length даёт разные результаты в зависимости от типа аргумента:

• для строк — длинна в байтах;
• для объектов — число пар ключ:значение;
• для массивов — число элементов.

Примеры:

jq "(.[100:110] | .[].name | length)" strikes.json

jq "(.[0] | length)" strikes.json

Функция keys

keys возвращает массив имён ключей объекта или индексы в массиве. Примеры:

jq ".people.[0] | keys" astro.json

jq ".people | keys" astro.json

Функция has()

has(“key”) проверяет, присутствует ли ключ в объекте. Обратите внимание, имя ключа требуется в кавычках (JSON-строка).

jq '.[] | has("nametype")' strikes.json

Проверка конкретного объекта по индексу:

jq '.[678] | has("nametype")' strikes.json

Практические шаблоны использования

Ниже — собранные шаблоны и приёмы, которые часто пригодятся при работе с реальными данными.

• Получить все значения ключа из массива объектов:

jq ".items[] | .field" file.json

• Отфильтровать объекты по условию (например, mass больше 1000):

jq '.[] | select(.mass != null and (.mass|tonumber) > 1000)' strikes.json

• Создать новый объект с выбранными полями:

jq '.[] | {name: .name, mass: .mass, coords: .geolocation.coordinates}' strikes.json

• Сохранить изменённый JSON в новый файл:

jq 'del(.[].unnecessaryField)' file.json > cleaned.json

• Преобразовать массив в объект с ключами по какому-то полю:

jq 'map({(.id): .}) | add' items.json

Отладка и отлов ошибок

• Частая ошибка — неправильное экранирование кавычек в shell. Используйте одинарные кавычки для jq-выражений и двойные внутри, либо наоборот, в зависимости от ситуации.
• Если jq жалуется на синтаксис — проверьте, что входной JSON корректен: jq . file.json покажет ошибку при некорректном JSON.
• Чтобы увидеть путь к проблемному фрагменту, используйте jq -c ‘.’ file.json и анализируйте структуру по частям.

Безопасность и обработка недоверенного ввода

• Не выполняйте jq-выражения, полученные из ненадёжных источников, без валидации.
• Встраивание данных в shell-команды требует корректного экранирования, иначе можно получить уязвимость shell injection.
• Обрабатывайте размеры входных данных: jq читает весь JSON в память; с очень большими файлами может понадобиться стриминг-решение.

Когда jq не лучший выбор (контрпримеры)

• Очень большие файлы, которые не помещаются в память — лучше использовать стриминговые парсеры или инструменты, поддерживающие потоковую обработку.
• Если нужна сложная логика бизнес-правил, проще реализовать её в языке программирования (Python, JavaScript) с библиотекой JSON, нежели в jq-скриптах.
• Если нужно сохранять точную структуру форматирования (комментарии, нестандартные поля) — jq не хранит исходное форматирование или комментарии.

Альтернативы и сравнение

Короткая справка по альтернативам:

• Python (json, jq-подобная логика в коде) — гибко для сложной логики и больших данных.
• yq — удобен для YAML и поддерживает JSON через преобразование; полезен при смешанных форматах.
• dasel — инструмент для поиска и изменения данных в JSON, YAML, TOML, XML.
• Прямые API-клиенты и библиотеки (Node.js, Go) — предпочтительны, когда вы пишете приложение.

Сравнение (вкратце): jq — лучшая утилита для быстрых CLI-операций над JSON; Python/JS — для сложной логики и интеграции в приложения.

Шаблон методологии обработки JSON (мини-метод)

1. Валидация: убедитесь, что вход — корректный JSON (jq . file.json).
2. Исследование: перечислите ключи и структуру (keys, length).
3. Выбор: сформулируйте требуемые поля и условия фильтрации.
4. Трансформация: используйте фильтры, map/select/редактирование.
5. Тестирование: проверяйте на примерах, покрывающих граничные случаи.
6. Сохранение/экспорт: redirect > файл, при необходимости потоковая обработка.

Чек-листы по ролям

Разработчик:

• Проверить валидность JSON.
• Написать jq-выражения для выборки и тесты с примерами.
• Обработать возможное отсутствие ключей (null и has()).

Системный администратор / DevOps:

• Автоматизировать загрузку (curl/wget) и обработку (jq) в cron/скриптах.
• Контролировать размеры и ресурсные ограничения.
• Логировать ошибки парсинга.

Аналитик данных:

• Использовать jq для быстрой предобработки перед загрузкой в аналитические инструменты.
• Проверять единообразие форматов дат/чисел.

Snippets / Шпаргалка (cheat sheet)

• Pretty print:

jq . file.json

• Получить ключ:

jq .key file.json

• Вложенный путь:

jq .parent.child file.json

• Проход по массиву:

jq .array[] file.json

• Выбрать поле для каждого элемента массива:

jq ".array[] | .name" file.json

• Фильтрация:

jq '.[] | select(.mass != null and (.mass|tonumber) > 1000)' file.json

• Сборка нового объекта:

jq '.[] | {name: .name, coords: .geolocation.coordinates}' file.json

• Удалить поле в выводе:

jq 'del(.unwanted)' file.json

• Количество элементов массива:

jq '.array | length' file.json

• Показать ключи объекта:

jq 'keys' file.json

Критерии приёмки для простого jq-скрипта

• Скрипт должен корректно работать с тестовым файлом с ожидаемой структурой.
• При отсутствии поля скрипт не должен аварийно завершаться (обрабатываются null/has()).
• Результат должен быть валидным JSON (проверяется jq . result.json).
• Время выполнения для файла X не должно превышать Y — установите собственные SLA для ваших данных.

Тест-кейсы и примеры для проверки

1. Файл с корректным JSON и ожидаемой структурой — проверка основных путей.
2. Файл, где некоторые объекты лишены ключей — проверка поведения select / has.
3. Пустой файл или некорректный JSON — ожидается вежливая ошибка и лог.
4. Очень большой файл — тест на потребление ОЗУ и время выполнения.

Советы по производительности

• jq загружает JSON в память: для больших объёмов данных предусмотреть других инструментов или разбивать файл.
• Пишите фильтры, минимально извлекающие то, что нужно — не отдавайте весь объект, если нужна только одна строка.
• Используйте простой потоковый фильтр, если нужно обрабатывать объекты по одному: .[] | …

Совместимость и примечания по версиям

jq старается сохранять совместимость фильтров, но набор функций и поведение может отличаться в очень старых сборках. Если вы используете контейнеры или CI/CD, фиксируйте версию пакета в окружении.

Мини-руководство по безопасности в скриптах

• Экрануйте jq-выражения при вставке переменных (используйте аргументы, а не конкатенацию строк).
• Не подставляйте не прошедшие валидацию пользовательские данные внутрь shell-команды.
• Логируйте только необходимые данные, не публикуйте чувствительную информацию.

Дополнительные примеры и рецепты

Сохранение списка имён в текстовый файл:

jq -r ".people[].name" astro.json > names.txt

Примечание: опция -r (raw output) убирает кавычки вокруг строк — удобно для дальнейшей обработки shell-утилитами.

Сортировка массива по полю (пример, сортировка по массе, если поле mass — строка с числами):

jq 'sort_by(.mass|tonumber)' strikes.json

Группировка элементов по ключу (map и group_by):

jq 'group_by(.recclass) | map({class: .[0].recclass, items: .})' strikes.json

Decision flowchart (простая ветка принятия решения)

flowchart TD
  A[Нужен CLI для JSON?] -->|Да| B{Файлы большие?}
  B -->|Нет| C[Использовать jq]
  B -->|Да| D[Рассмотреть стриминг/скрипт на Python]
  A -->|Нет| E[Использовать языковую библиотеку в приложении]

Справочная таблица основных команд (фактбокс)

• pretty print: jq .
• вывести ключ: jq .key
• проход по массиву: jq .arr[]
• raw output: -r
• удаление поля: del()
• проверка наличия ключа: has(“key”)
• длина: length
• ключи: keys

Частые погрешности и подводные камни (галерея крайних случаев)

• Неправильное экранирование при использовании переменных shell в jq-выражениях.
• Ожидание строковых чисел в фильтрах, когда поле может быть null или отсутствовать.
• Ошибки при преобразовании типов (нужно явное приведение через tonumber/ tostring).
• Проблемы памяти с гигантскими JSON-файлами.

Короткий глоссарий (1-строчный)

• filter — выражение jq, определяющее, какие части JSON выбрать или как их преобразовать.
• . — «входной объект» или корневой фильтр, возвращающий весь объект.
• select — функция фильтрации объектов по условию.
• map — применяет выражение ко всем элементам массива и возвращает массив результатов.

Пример плейбука для автоматизации (SOP)

1. Загрузить данные: curl -s URL > raw.json
2. Проверить валидность: jq . raw.json >/dev/null || { echo “invalid JSON”; exit 1; }
3. Очистить: jq ‘map(del(.temporary))’ raw.json > cleaned.json
4. Экспортировать свод: jq -r ‘.[] | [.id, .name, .mass] | @csv’ cleaned.json > summary.csv
5. Архивировать: gzip -9 cleaned.json

Заключение

jq — это обязательный инструмент в арсенале администратора, разработчика или аналитика, работающего с JSON в Linux. Он упрощает чтение, позволяет писать компактные фильтры, создавать новые структуры и быстро прототипировать обработку данных. Если ваши задачи выходят за рамки возможностей jq (очень большие файлы, сложная бизнес-логика), комбинируйте jq с языковыми библиотеками или выберите другой инструмент.

RELATED: Лучшие ноутбуки на Linux для разработчиков и энтузиастов