Преобразование и создание объектов JSON с jq

Необработанный JSON, полученный от API или из файлов журналов, редко имеет именно ту структуру, которая Вам нужна. Вам может прийти большой объект, из которого нужны только определённые поля, либо потребуется переименовать ключи, распрямить вложенные структуры или создать полностью новую полезную нагрузку для отправки другой службе.

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

• Создание объекта — построение нового объекта JSON с нуля
• map — применение преобразования к каждому элементу массива
• to_entries / from_entries — представление пар ключ-значение объекта в виде массива, чтобы их можно было фильтровать и собирать заново

Во всех примерах предполагается, что jq установлен (apt install jq / brew install jq).

Самая фундаментальная возможность jq — создание объектов: заключение выражений в {} для построения нового объекта JSON. Вы выбираете, какие поля включить и как их назвать.

Синтаксис:

• { newKey: .existingField } — переименовать поле
• { name, age } — сокращённая запись, когда новый ключ совпадает с именем поля
• { total: (.price * .qty) } — вычислить значение непосредственно в выражении

Приведённый ниже фрагмент считывает JSON с данными о товаре и создаёт более компактную структуру с вычисляемым полем subtotal.

В реальных данных JSON часто встречаются вложенные структуры. jq позволяет обращаться к вложенным путям внутри конструктора объекта, одновременно распрямляя структуру.

Используйте точечную запись пути в выражении значения конструктора:

• { city: .address.city }
• { lat: .location.coords.lat }

Пример ниже получает глубоко вложенную запись о пользователе и создаёт плоскую сводку, подходящую для строки заголовков CSV или тела запроса к API.

map(expr) — эквивалент цикла для каждого в jq: он применяет expr к каждому элементу входного массива и возвращает новый массив такой же длины.

Основные моменты:

• map(expr) — это сокращённая запись [.[] | expr]
• Внутреннее выражение может быть любым фильтром jq, включая создание объектов
• Объединяйте с select(), чтобы выполнить фильтрацию перед преобразованием

Приведённый фрагмент обрабатывает список заказов, оставляя только поля, необходимые для отгрузочной ведомости.

Внутри map можно вычислять новые значения, преобразовывать типы и объединять поля, а не только копировать их. Распространённые шаблоны:

• Интерполяция строк: "\(.first) \(.last)"
• Арифметика: (.price * 1.2 | round) для наценки 20 %
• Условные выражения: if .score >= 90 then "A" else "B" end

Пример ниже дополняет список сотрудников вычисляемым полем fullName и меткой seniority на основе количества лет опыта.

to_entries преобразует объект JSON в массив пар {key, value}. Это позволяет применять к полям объекта операции над массивами (map, select, sort), что невозможно сделать непосредственно с объектом.

Пример преобразования:

• Входные данные: {"a": 1, "b": 2}
• Результат: [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

Обратная операция — from_entries, преобразующая этот массив обратно в объект. Вместе они образуют идиому to_entries | map(...) | from_entries для преобразований на уровне объекта.

Одно из наиболее практичных применений to_entries — динамическая фильтрация ключей, которые нужно оставить или удалить, на основе самого имени ключа. Создание объекта не позволяет сделать это, если имена ключей заранее неизвестны.

Шаблон:

• to_entries | map(select(.key | test("regex"))) | from_entries
• to_entries | map(select(.key != "secret")) | from_entries

Приведённый ниже фрагмент удаляет все ключи, начинающиеся с символа подчёркивания (внутренние или приватные поля), прежде чем передать объект конфигурации внешней службе.

Создание объекта переименовывает ключи, если их имена известны во время написания выражения. to_entries позволяет переименовывать ключи программно — например, преобразовывать camelCase в snake_case или добавлять префикс.

Внутри map Вы изменяете поле .key каждой записи, а затем передаёте результат в from_entries:

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) — преобразование camelCase в snake_case
• map(.key |= "app_" + .) — добавление префикса к каждому ключу

Пример добавляет ко всем именам переменных окружения префикс APP_, чтобы объединить их в отдельное пространство имён перед передачей в контейнер.

Шаблон to_entries | map(...) | from_entries настолько распространён, что jq предоставляет для него сокращённую запись: with_entries(expr).

Она полностью эквивалентна исходному шаблону, но короче:

• with_entries(.value |= . * 2) — удвоить каждое числовое значение
• with_entries(select(.value != null)) — удалить ключи со значением null
• with_entries(.key |= ascii_upcase) — перевести все ключи в верхний регистр

Приведённый фрагмент удаляет все ключи, значения которых равны null или пустой строке, — это распространённый этап очистки перед отправкой запроса PATCH к REST API.

Реальные преобразования объединяют несколько операций jq. Типичный конвейер подготовки полезной нагрузки API может выполнять следующие действия:

1. Отфильтровать входной массив с помощью map(select(...))
2. Изменить структуру каждого элемента с помощью создания объекта
3. Добавить вычисляемые поля
4. Отсортировать результат

Пример ниже считывает список показателей серверов, оставляет только серверы с высокой загрузкой CPU и создаёт компактную полезную нагрузку оповещения, готовую для отправки методом POST веб-перехватчику.

jq может объединять входные данные и создавать объекты на основе нескольких источников JSON с помощью оператора сложения + и привязки переменных через as $var.

Полезные шаблоны:

• obj1 + obj2 — объединить два объекта (при конфликте ключей побеждает значение справа)
• --argjson — передать второй документ JSON в виде переменной
• $ENV — напрямую прочитать переменные окружения внутри jq

Приведённый фрагмент объединяет базовую конфигурацию с переопределениями для конкретного окружения — это распространённый шаблон управления конфигурацией приложений по принципам 12 факторов в скриптах оболочки.

У Вас есть следующий объект JSON, и Вам нужно удалить все ключи, значение которых меньше 0, создав новый объект только с неотрицательными значениями. Какое выражение jq правильно решает эту задачу?

Входные данные: {"a": 10, "b": -3, "c": 0, "d": 5}

Вы изучили основные приёмы изменения структуры JSON с помощью jq:

• Создание объектов {} — построение новых объектов путём выбора, переименования и вычисления полей из входных данных
• map(expr) — применение любого преобразования к каждому элементу массива, включая создание вложенных объектов и использование select() для фильтрации
• to_entries / from_entries — преобразование объекта в массив пар {key, value}, что позволяет выполнять операции над ключами и значениями как над элементами массива, а затем преобразование обратно
• with_entries(expr) — краткая запись полного конвейера to_entries → map → from_entries
• Объединение объектов с помощью + и --argjson для полезных нагрузок из нескольких источников

Эти строительные блоки можно комбинировать: фильтровать с помощью select, изменять структуру с помощью создания объектов, дополнять вычисляемыми полями и объединять всё в одном понятном выражении jq. Освоив эти шаблоны, Вы сможете обрабатывать практически любую полезную нагрузку JSON непосредственно в оболочке, не создавая отдельный скрипт на Python или Node.