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

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

Вы делаете запрос к API через curl, получаете ответ и... видите одну длинную строку без пробелов и переносов. Найти в ней нужное поле, посчитать количество элементов или отфильтровать ошибки — задача на пять минут, если вручную, и на пять секунд, если у вас есть jq.

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

Установка

jq есть в репозиториях всех основных дистрибутивов.

Debian/Ubuntu:

sudo apt install jq

Fedora/RHEL:

sudo dnf install jq

Arch Linux:

sudo pacman -S jq

macOS (через Homebrew):

brew install jq

1. Базовый синтаксис: точка — это корень

В 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.json

4. Статистика и агрегация (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.json

unique сортирует и удаляет повторы. Это быстрый способ узнать, какие роли вообще существуют в системе .

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.json

jq автоматически добавит отступы и переносы строк (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.json

max_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) придет по мере необходимости.

Читайте также

Шифрование данных в Linux: как использовать LUKS и cryptsetup для безопасного хранения файлов

Шифрование данных в Linux: как использовать LUKS и cryptsetup для безопасного хранения файлов

Практическое руководство по созданию зашифрованных контейнеров и разделов с помощью LUKS. Как хранить резервные копии, пароли и конфиденциальные данные так, чтобы их не прочитал никто посторонний.

28