jq --arg u "$USER" '.[]|select(.name==$u)'shell-переменная в фильтр
Обзор
jq — как grep/sed, но для JSON. Незаменим при работе с API (curl) и
конфигами. Понимает структуру, а не просто текст.
bash
echo '{"name":"web","port":80}' | jq . # красиво напечатать
echo '{"name":"web","port":80}' | jq '.name' # → "web"
curl -s https://api/x | jq '.items[0].id' # поле из ответа API
Ключи
8
-r убирает кавычки у строкового результата — без него в скрипт попадёт JSON
literal "value", а не value. --arg/--argjson — единственный безопасный
способ подставить значение shell-переменной в фильтр: вклеивание переменной в
текст фильтра ломается на кавычках и спецсимволах. -s (slurp) нужен, когда
вход — поток из нескольких JSON-объектов, а обработать их надо как один массив.
Ключ
Что делает
Пример
-r--raw-output
Сырой вывод строк — без кавычек JSON, удобно для скриптов.
jq -r '.name'
--argname value
Передать значение shell-переменной в фильтр как строку.
jq --arg u "$USER" '.users[]|select(.name==$u)'
-c--compact-output
Компактный вывод — один JSON-объект на строку, без отступов.
jq -c '.'
-s--slurp
Собрать весь входной поток в один массив перед обработкой.
jq -s '.'
--argjsonname value
Передать значение в фильтр как JSON (число, объект, массив).
jq --argjson n 5 '.items[:$n]'
-n--null-input
Не читать входные данные — полезно для генерации JSON с нуля.
jq -n '{a:1}'
-e--exit-status
Код возврата 1, если результат — false или null; удобно в скриптах.
jq -e '.ok'
-C--color-output
Всегда красить вывод, даже если он идёт не в терминал.
jq -C . file.json
Ничего не найдено. Попробуй запрос короче.
Рецепты
2
Фильтры
bash
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: «сырой» вывод (без кавычек) — для скриптов
Примеры и сборка
bash
# 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
Неполадки
4
СимптомПричина и решение
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.
См. также
curl — Запросы HTTP/HTTPS из CLI — отладка API и веб-сервисов, заголовки, методы.
text-tools — Обработка текста и потоков — сортировка, уникальность, столбцы, подсчёт.