Работа с JSON в командной строке с помощью jq

Цель

Извлекать, фильтровать или менять структуру JSON из ответа API, строки журнала или файла конфигурации внутри конвейера, без написания одноразовой программы.

Предварительные условия

Установленный jq; входные данные в виде корректного JSON или потока JSON-текстов; некоторое представление об их структуре (jq 'keys', jq '.[0]' и jq 'paths' помогают её изучить).

Шаги

1. Убедитесь, что входные данные разбираются, и посмотрите их структуру: jq . печатает с форматированием; для большого ввода jq -c '.[0]' или jq 'keys' проще прочитать.
2. Перемещайтесь по структуре: .foo.bar и .[0] обращаются по индексу, .[] перебирает массив или значения объекта, .foo? подавляет ошибку, когда входные данные — не объект. Соединяйте фильтры через |.
3. Фильтруйте и преобразуйте: .items[] | select(.status == "open") | {id, name}; map(f) применяет фильтр к каждому элементу; to_entries, from_entries и with_entries(f) преобразуют объекты в списки пар ключ-значение и обратно; a // b выдаёт b, когда a выдаёт только null или false.
4. Передавайте значения оболочки через --arg name value (всегда строка) или --argjson name json (с типом) и используйте $name в фильтре. Руководство отмечает, что --arg foo 123 связывает строку "123", а не число.
5. Выберите форму вывода для следующей программы: -r (--raw-output) пишет строки без кавычек; -c печатает компактный однострочный JSON; @tsv, @csv и @sh форматируют массивы для использования в формате с разделением табуляцией, в CSV или в оболочке POSIX; --raw-output0 разделяет результаты байтом NUL, когда значения могут содержать переводы строк.
6. Обрабатывайте несколько входов: по умолчанию фильтр запускается один раз на каждый JSON-текст в потоке; -s (--slurp) собирает их в один массив; -n (--null-input) запускает фильтр один раз с null на входе, что позволяет строить JSON с нуля: jq -n --arg a "$x" '{a: $a}'.
7. Делайте отсутствие данных ошибкой: -e (--exit-status) устанавливает код завершения 1, если последний результат — null или false, и 4, если не получено допустимого результата; проверяйте его в скриптах вместо проверки пустой строки.

Ожидаемый результат

Однострочный конвейер, выдающий ровно нужное поле или структуру, с корректными кавычками для следующей программы и ненулевым кодом завершения при отсутствии данных.

Ограничения и основания проверки

Семантика следует цитируемому руководству jq. jq полностью загружает каждый JSON-текст, если не используется --stream, поэтому очень большие документы требуют потоковой обработки или другого инструмента. Руководство указывает, что обработка чисел в jq менялась со временем и зависит от параметров сборки, а разбор очень больших или очень точных чисел может терять точность; прежде чем полагаться на арифметику jq с такими значениями, проверьте руководство установленной версии. Данные о времени выполнения не заявляются.