jq (обработка JSON)

jq — как grep/sed, но для JSON. Незаменим при работе с API (curl) и конфигами. Понимает структуру, а не просто текст.

echo '{"name":"web","port":80}' | jq .          # красиво напечатать
echo '{"name":"web","port":80}' | jq '.name'    # → "web"
curl -s https://api/x | jq '.items[0].id'       # поле из ответа API

jq '.'                            # весь JSON (pretty)
jq '.key' ; jq '.a.b.c'           # поле / вложенное
jq '.key // "default"'            # значение или дефолт, если null/отсутствует
jq '.items[]'                     # все элементы массива
jq '.items[0]' ; jq '.items[-1]'  # первый / последний
jq '.items | length'              # длина массива
jq 'keys' ; jq 'has("name")'      # ключи / есть ли ключ
jq '.items[] | .name'             # имя каждого элемента
jq '.items[] | select(.active)'   # фильтр по условию
jq '.items[] | select(.cpu > 80)' # числовое условие
jq '.items | map(.name)'          # массив имён
jq '.items | group_by(.role)'     # сгруппировать
jq -r '.name'                     # -r: «сырой» вывод (без кавычек) — для скриптов

# IP всех сервисов из API (в строки для скрипта)
curl -s https://api/services | jq -r '.[].ip'

# отфильтровать и собрать таблицу (TSV)
curl -s https://api/users | jq -r '.[] | select(.role=="admin") | [.id,.name] | @tsv'

# собрать CSV с заголовком
jq -r '["id","name"], (.[] | [.id,.name]) | @csv' users.json

# подставить переменную shell в фильтр (безопасно)
jq --arg u "$USER" '.users[] | select(.name==$u)' data.json

# собрать новый объект
jq '{name: .name, port: .ports[0]}' svc.json

# править JSON-файл «на месте» (sponge из moreutils)
jq '.version="2"' conf.json | sponge conf.json

jq: error: Cannot index ...

Структура не та, что ждёшь. Сначала jq . (посмотри форму), потом стройся под неё. Поле — объект или массив? .items[] для массива, .items.x для объекта.

В выводе лишние кавычки

Для строк jq печатает с кавычками. Нужен «сырой» текст (в скрипты/циклы) — jq -r.

Невалидный JSON на входе

jq падает на не-JSON. Проверь, что команда выше отдаёт именно JSON (а не HTML/ошибку): curl -s URL | head. Для «потока» JSON-объектов — jq -s (slurp) или --stream.

Нужно подставить shell-переменную

Не вклеивай в строку фильтра — используй --arg name val (строка) или --argjson (число/JSON), внутри ссылайся как $name.

jq .                              # pretty
jq '.field' ; jq '.a.b'           # поле / вложенное
jq '.arr[]'                       # элементы массива
jq -r '.[].name'                  # сырой вывод (скрипты)
jq '.[] | select(.x=="y")'        # фильтр
jq -r '.[] | [.id,.name] | @tsv'  # таблица TSV
jq --arg v "$V" '... $v ...'      # shell-переменная в фильтр