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

Оглавление

• Что такое jq и где его применяют
• Установка и первые шаги с jq
• Создание простого «фид‑ридера» с jq
• Чтение и поиск в локальной базе JSON
• Работа с не‑JSON входом и выходом
• Альтернативные парсеры JSON
• Ментальные модели и эвристики для работы с jq
• Шпаргалка команд jq (cheat sheet)
• Чек‑листы по ролям: разработчик, SRE, дата‑аналитик, скриптер
• Методика отладки и playbook для ошибок в фильтрах
• Решения — когда использовать jq, jaq, gojq или fq (дерево решений)
• Таблица совместимости и советы по миграции
• Краткое резюме и выводы

Что такое jq и где его применяют

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

• Обработка ответов REST/SaaS API (например, вместе с curl).
• Манипуляции с большими JSON‑файлами локально (логи, экспорт БД, конфиги).
• Встраивание в shell‑скрипты для автоматизации и интеграции.

Краткое определение: jq — это потоковый JSON‑процессор, который позволяет выбирать, преобразовывать и агрегировать данные через понятный и выразительный язык фильтров.

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

Установка и первые шаги с jq

Установка на Debian/Ubuntu простая:

sudo apt install jq

Проверка работы с открытым API — часто используемый способ обучения. В примерах ниже используется ipinfo.io как простой JSON‑эндпоинт.

Основные фильтры: точка (.) и конвейер (|).

• . — проходит входное JSON‑значение и обычно используется для «pretty print».
• | — передаёт вывод одного фильтра как ввод следующему.

Примеры:

curl https://ipinfo.io/ | jq '.'

curl https://ipinfo.io/ | jq '. | .ip'

Здесь .ip выбирает поле ip в корневом объекте.

Совет: используйте jq для отладки API‑ответов, чтобы быстро увидеть структуру и нужные поля.

Создание простого «фид‑ридера» с jq

Многие сервисы (включая GitHub) предоставляют JSON‑API для получения списка ресурсов. jq удобно использовать, чтобы взять только нужные поля и собрать «RSS‑подобный» вывод.

Проверяем эндпоинт:

curl https://api.github.com/repos/bitcoin/bitcoin/issues

Печатаем первый элемент массива:

curl https://api.github.com/repos/bitcoin/bitcoin/issues | jq '.[0]'

Создаём объект с нужными полями:

curl https://api.github.com/repos/bitcoin/bitcoin/issues | jq '.[0] | { title: .title }'

Несколько полей:

curl https://api.github.com/repos/bitcoin/bitcoin/issues | jq '.[0] | {title: .title, url: .html_url, author: .user.login}'

Применение ко всему потоку:

curl https://api.github.com/repos/bitcoin/bitcoin/issues | jq '.[] | {title: .title, url: .html_url, author: .user.login}'

Автоматизация в bash‑скрипте:

#!/bin/bash

# usage: ./script.sh [0 ... 29]

REPO="https://api.github.com/repos/bitcoin/bitcoin/issues"

curl $REPO | jq ".[$1] | {title: .title, url: .html_url, author: .user.login}"

Сделать исполняемым и вызвать:

chmod u+x ./script.sh
./script.sh 0

Практический совет: кешируйте ответы API при массовых запросах и применяйте пагинацию.

Чтение и поиск в локальной базе JSON

jq отлично подходит для локальных файлов — например, когда у вас есть экспорт в формате JSON.

Создадим файл database.json:

nano ./database.json

Вставим пример данных:

[
  {"id": 1, "name": "Ramces", "balance": 20},
  {"id": 2, "name": "Alice", "balance": 30},
  {"id": 3, "name": "Bob", "balance": 10},
  {"id": 4, "name": "Charlie", "balance": 20},
  {"id": 5, "name": "Maria", "balance": 50}
]

Печать первого объекта:

jq '.[0]' database.json

Выбор имён у всех объектов:

jq '.[] | .name' database.json

Фильтр по длине строки (более 6 символов):

jq '.[] | select((.name|length) > 6)' database.json

Операции агрегирования: сумма балансов:

jq '[.[] | .balance] | add' database.json

Пример с условием:

jq 'if .[1].name == "Alice" then [ .[] | .balance ] | add else "Second name is not Alice" end' database.json

Удаление поля временно (del):

jq 'del(.[1].name) | .[]' database.json

Добавление поля (не перезаписывает файл по умолчанию):

jq '.[0] + {active: true}' database.json

Важно: чтобы изменения стали постоянными, перенаправьте вывод в файл (осторожно с перезаписью):

jq '.[0] + {active: true}' database.json > database.json

Примечание по безопасности: при перезаписи файла сначала пишите в временный файл и затем atomically заменяйте (mv).

Работа с не‑JSON входом и выходом

jq может «склеивать» входные значения в массив с опцией -s (slurp). Это полезно, когда вход — пробело‑ или переводо‑разделённая строка.

echo '1 2' | jq -s .

Адресация по индексам массива:

echo '1 2' | jq -s '.[0] + .[1]'

Построение объекта из полей:

echo '6 "Mallory" 10' | jq -s '{"id": .[0], "name": .[1], "balance": .[2]}'

Чистый текст вместо JSON (флаг -r):

jq -r '.[] | .name' database.json

Применение: вывод в другие утилиты, сохранение в лог или в CSV преобразование.

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

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

jaq

• Язык: Rust.
• Плюсы: близкая совместимость с jq, ориентирован на высокую производительность.
• Минусы: не всегда доступен в стандартных репозиториях; возможно, потребуется Homebrew или сборка из исходников.

gojq

• Язык: Go.
• Плюсы: дружелюбные сообщения об ошибках, поддержка YAML вместе с JSON.
• Минусы: некоторые опции jq отсутствуют (например, –ascii-output, –seq, –sort-keys).

fq

• Набор инструментов: умеет работать с текстом и бинарными форматами (JSON, YAML, HTML, FLAC и др.).
• Плюсы: встроенный hex‑ридер, удобен для анализа бинарных файлов.
• Минусы: активная разработка → API/поведение могут меняться.

Совет по выбору: используйте jq для повседневных задач, jaq — для тяжёлых вычислений, gojq — если нужна YAML‑поддержка и понятные ошибки, fq — для бинарного анализа и мультиформатных задач.

Ментальные модели и эвристики для работы с jq

1. Модель «потока фильтров»: думайте о конвейере как о цепочке трансформаций — каждый фильтр получает JSON и возвращает JSON.
2. Одиночная ответственность фильтра: пишите маленькие фильтры и тестируйте их последовательно.
3. Превращение в плоскую структуру: если задача — агрегировать, первым шагом превратите объекты в массивы скалярных значений (например, [.[] | .balance]).
4. Безопасность типов: проверяйте существование полей перед операциями (select/has) чтобы избежать ошибок в больших наборах данных.

Простая эвристика для отладки: сначала jq ‘.’ чтобы увидеть структуру, затем постепенно добавляйте уровни фильтрации.

Шпаргалка команд jq (cheat sheet)

Быстрая подборка команд и паттернов, которые часто применяются:

• Pretty print:

jq '.' file.json

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

jq '.[] | .name' file.json

• Селектор по условию:

jq '.[] | select(.balance > 20)' file.json

• Сбор массива значений и сумма:

jq '[.[] | .balance] | add' file.json

• Добавление/обновление ключа в объекте:

jq '.[0] + {active:true}' file.json

• Удаление ключа:

jq 'del(.[1].name)' file.json

• Конвертация нескольких полей в CSV (пример):

jq -r '.[] | [.id, .name, .balance] | @csv' file.json

• Использование slurp для объединения токенов в массив:

echo 'a b c' | jq -s .

• Вывод сырого текста (без кавычек):

jq -r '.[] | .name' file.json

• Интерполяция и форматирование строк:

jq -r '.[] | "":[.id] " - " .name' file.json  # пример шаблона

(Примечание: внимательно относитесь к управляющим символам — используйте одинарные кавычки оболочки чтобы защищать jq выражение.)

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

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

• Открой JSON и выполните jq ‘.’ чтобы понять структуру.
• Выделите нужные поля минимальным фильтром.
• Напишите модульный фильтр и протестируйте на нескольких записях.
• Добавьте unit‑тесты для крайних случаев (пустые поля, null).

SRE / DevOps:

• Используйте jq -r для интеграции вывода в shell‑скрипты.
• Логируйте ошибки и сохраняйте сырые ответы API для последующего анализа.
• При перезаписи файлов сначала обновляйте временный файл и затем atomically mv.

Дата‑аналитику:

• Преобразуйте JSON в CSV через @csv или вручную сформируйте массивы значений.
• Проверьте целостность типов (числа/строки) перед агрегацией.
• Используйте пакетные преобразования и фильтры для предобработки данных.

Скриптеру/автоматизатору:

• Выбирайте -r для получения чистых значений в скриптах.
• Обрабатывайте ошибки при отсутствии полей через select или try/catch (если доступно).
• Кэшируйте ответы API и контролируйте частоту запросов.

Методика отладки и playbook для ошибок в фильтрах

1. Посмотреть исходный JSON полностью: jq ‘.’ file.json.
2. Изолировать проблемную ветку: используйте .path.to.field | length и другие простые проверки.
3. Добавлять лог‑выводы: jq '.[] | {debug: ., needed: .field}'.
4. Использовать -e для выхода с ненулевым кодом при пустом результате (если нужно в скриптах).
5. Тестировать на минимальном примере (создайте маленький file.json с 2–3 объектами).

Пример runbook при неожиданном null:

• Шаг 1: проверить наличие ключа: jq '.[] | has("name")' file.json.
• Шаг 2: заменить null на значение по умолчанию: jq 'map(if .name==null then .name="(no name)" else . end)' file.json.
• Шаг 3: если проблема повторяется — проанализировать upstream (API) и добавить защитные фильтры.

Решения — когда использовать jq, jaq, gojq или fq

Ниже дерево решений в формате Mermaid, помогающее выбрать инструмент:

flowchart TD
  A[Нужно парсить JSON?] -->|Да| B{Требуется производительность}
  B -->|Очень высокая| C[jaq 'Rust']
  B -->|Умеренная| D{Нужна YAML поддержка}
  D -->|Да| E[gojq]
  D -->|Нет| F[jq]
  A -->|Хочу анализ бинарных файлов| G[fq]
  C --> H[Проверьте доступность сборки]
  E --> I[Отличные ошибки для отладки]
  F --> J[Широкая поддержка и пакетные репозитории]

(Визуализация: если нужен супер‑скоростной парсер — jaq; если нужно удобство и YAML — gojq; универсальный и широко доступный — jq; для бинарных и мультиформатных анализов — fq.)

Таблица совместимости и советы по миграции

Миграция — тактика:

• Начните с запуска существующих jq‑скриптов в выбранном инструменте на тестовой площадке.
• Автоматизированно запускайте тестовый набор входов и сравните результаты.
• Обратите внимание на флаги и поведение при несуществующих ключах.

Контрпримеры и когда jq не подойдёт

• Если входные данные — произвольный бинарный формат, jq не подойдёт; используйте fq.
• Для сложных трансформаций больших объёмов данных в режиме реального времени может потребоваться jaq или даже реальная ETL‑система.
• Если вам нужны расширенные возможности, не реализованные в jq‑языке (например, встроенные HTTP‑запросы), лучше собрать пайплайн с внешними утилитами.

1‑строчный глоссарий

• Фильтр — выражение на языке jq, которое трансформирует JSON.
• Slurp (-s) — режим, который читает весь ввод как массив.
• Pipe (|) — оператор последовательной передачи вывода в другой фильтр.
• Del — удаление поля из объекта.

Практическая шпаргалка: тесты приемки (acceptance)

• jq ‘.’ корректно печатает входной JSON.
• Для заданного фильтра ожидаемый набор полей присутствует и имеет правильные типы.
• Скрипт с -r возвращает строки без кавычек и без лишних символов.
• При перезаписи файла используется атомарная замена.

Риски и mitigations

• Риск: потеря данных при перезаписи. Митигирование: писать в tmp и mv.
• Риск: разный вывод на разных версиях парсера. Митигирование: фиксировать версию в CI и тестах.

Короткий чек: частые шаблоны (snippets)

• Преобразовать список объектов в CSV:

jq -r '(.[0] | keys_unsorted) as $keys | $keys, (.[ ] | [.[$keys[]]]) | @csv' file.json

• Группировка по полю и суммирование баланса:

jq 'group_by(.name) | map({name: .[0].name, total: (map(.balance) | add)})' file.json

• Показать только уникальные имена:

jq '[.[] | .name] | unique' file.json

Рекомендации по безопасности и приватности

• Не логируйте чувствительные поля (пароли, токены). Перед сохранением в логи применяйте del(.secret) или заменяйте значениями‑заполнителями.
• В CI избегайте вывода больших JSON‑файлов в открытые журналы.

Краткое резюме и выводы

jq — универсальный инструмент для работы с JSON в командной строке: от простого просмотра до сложных агрегаций. Для интенсивных задач рассмотрите jaq (производительность) или gojq (YAML и лучшие сообщения об ошибках). fq полезен при анализе смешанных и бинарных форматов. Используйте методику маленьких фильтров, тестируйте на минимальных примерах и защищайте операции перезаписи файлов.

Image credit: Ferenc Almasi via Unsplash. All alterations and screenshots by Ramces Red.