jq в Linux: как парсить JSON в терминале — фильтры, примеры и работа с API

Вы делаете запрос к API через curl, получаете ответ и... видите одну длинную строку без пробелов и переносов. Найти в ней нужное поле, посчитать количество элементов или отфильтровать ошибки — задача на пять минут, если вручную, и на пять секунд, если у вас есть jq.
jq — это не просто «форматтер JSON». Это полноценный язык обработки данных для терминала, который превращает сырой JSON в структурированную информацию. В этой статье мы разберем, как использовать его для реальных задач: от простого чтения полей до сложных фильтров и статистики.
Установка
jq есть в репозиториях всех основных дистрибутивов.
Debian/Ubuntu:
sudo apt install jqFedora/RHEL:
sudo dnf install jqArch Linux:
sudo pacman -S jqmacOS (через Homebrew):
brew install jq1. Базовый синтаксис: точка — это корень
В jq точка . означает «весь входной JSON». Чтобы получить значение конкретного поля, используйте точечную нотацию.
Исходный JSON (response.json):
{
"id": 123,
"name": "Alice",
"email": "alice@example.com",
"roles": ["admin", "user"]
}Прочитать поле:
jq '.name' response.jsonВывод: "Alice" (с кавычками, потому что это строка в JSON).
Прочитать вложенное поле:
jq '.user.profile.city' response.jsonЕсли поля нет, jq вернет null. Это безопаснее, чем пытаться парсить строку вручную.
Убрать кавычки (raw output):
Флаг -r (raw) выводит строки без JSON-кавычек. Это критически важно для скриптов и для вставки в другие команды .
jq -r '.name' response.jsonВывод: Alice
2. Работа с массивами и API
Чаще всего jq используют вместе с curl, когда нужно сразу отфильтровать ответ API.
Пример: получить список пользователей и вытащить только имена
curl -s https://api.example.com/users | jq -r '.[] | .name'Разберем:
.[]— означает «пройти по каждому элементу массива».|— передает результат дальше..name— берет полеnameиз каждого элемента.
Пример: вытащить несколько полей
jq -r '.[] | "\(.id) - \(.name)"' users.jsonИспользуем интерполяцию строк \(...), чтобы собрать читаемый текст.
Пример: собрать поля в объект (для читаемости)
jq '.[] | {id, name}' users.jsonВывод будет массивом объектов, содержащих только id и name. Это удобно, когда API возвращает 50 полей, а вам нужны два .
3. Фильтрация: select() — ваш главный инструмент
select() пропускает дальше только те элементы, для которых условие истинно. Это аналог WHERE в SQL .
Пример: найти всех пользователей с ролью admin
jq '.[] | select(.role == "admin")' users.jsonПример: найти ошибки в ответе API
jq '.items[] | select(.status == "failed") | {id, error}' response.jsonВы увидите только id и текст ошибки для упавших элементов. Это экономит время при отладке .
Пример: комбинированное условие (И)
jq '.items[] | select(.score >= 60 and .status == "ok")' response.json4. Статистика и агрегация (map, length, group_by)
jq умеет не только фильтровать, но и считать. Это делает его мощным инструментом анализа.
Посчитать количество элементов в массиве:
jq 'length' users.jsonЕсли массив — вернет число элементов. Если объект — число ключей. Если строка — длину в символах .
Посчитать сумму значений:
jq '[.[] | .score] | add' response.json[.[] | .score]— собирает все значенияscoreв массив.add— суммирует их.
Сгруппировать и посчитать:
jq 'group_by(.role) | map({role: .[0].role, count: length})' users.jsonЭта команда сгруппирует пользователей по роли и покажет, сколько человек в каждой группе .
Убрать дубликаты:
jq 'map(.role) | unique' users.jsonunique сортирует и удаляет повторы. Это быстрый способ узнать, какие роли вообще существуют в системе .
5. Преобразование в TSV (для Excel и скриптов)
Если нужно передать данные в другую систему или открыть в Excel, JSON не всегда удобен. jq умеет конвертировать в TSV (tab-separated values).
jq -r '.[] | [.id, .name, .email] | @tsv' users.jsonФлаг @tsv разделяет поля табуляцией. Вывод можно перенаправить в файл и открыть в таблице .
6. Обработка ошибок: что делать, если JSON битый
Если jq выдает ошибку парсинга, не спешите менять код. Скорее всего, проблема в самом ответе.
Проверка валидности:
jq . response.jsonЕсли JSON валиден, jq просто отформатирует его. Если нет — покажет строку и позицию ошибки. Это первый шаг диагностики: возможно, API вернул HTML-страницу с ошибкой вместо JSON .
Что делать, если JSON пришел одной строкой (без переносов):
jq . response.jsonjq автоматически добавит отступы и переносы строк (pretty-print). Это режим по умолчанию, если не указан -c (compact).
7. Полезные флаги для скриптов
-c(compact): Выводит JSON в одну строку. Удобно для логов и пайпов.-r(raw): Убирает кавычки у строк. Обязателен для@tsvи скриптов.-e(exit status): Устанавливает код возврата в зависимости от результата. Полезно в bash-скриптах для проверки условий .-s(slurp): Читает весь входной поток в один массив. Если у вас несколько JSON-объектов подряд,jqс-sсоберет их в массив.
Сценарии из жизни
Сценарий 1: Быстрая проверка ответа API
Вы делаете curl и хотите сразу увидеть, успешен ли запрос и что вернулось:
curl -s https://api.example.com/status | jq '{code: .status, message: .message}'Сценарий 2: Найти самый дорогой товар
jq '.products | max_by(.price) | {name, price}' catalog.jsonmax_by находит элемент с максимальным значением указанного поля .
Сценарий 3: Извлечь ID всех упавших задач для повторного запуска
jq -r '.tasks[] | select(.status == "failed") | .id' tasks.json > failed_ids.txtТеперь у вас есть файл с ID, который можно передать в другую команду.
Итог
jq — это обязательный инструмент для любого, кто работает с API и JSON в терминале. Он заменяет десятки строк ручного парсинга на одну команду и делает отладку в разы быстрее.
Начните с трех вещей: .field для чтения полей, select() для фильтрации и -r для скриптов. Этого уже хватит для 80% задач. Остальное (map, group_by, @tsv) придет по мере необходимости.





