Przekształcanie i tworzenie obiektów JSON za pomocą jq

Surowy JSON z API lub plików dziennika rzadko ma dokładnie taką strukturę, jakiej Państwo potrzebują. Mogą Państwo otrzymać duży obiekt, z którego potrzebne są tylko konkretne pola, albo chcieć zmienić nazwy kluczy, spłaszczyć zagnieżdżone struktury lub zbudować zupełnie nowy payload do wysłania do innej usługi.

jq to lekki i potężny procesor JSON działający w wierszu poleceń, który umożliwia wykonywanie takich przekształceń w jednym potoku. W tej lekcji poznają Państwo trzy podstawowe techniki zmiany struktury danych:

• Tworzenie obiektów — zbudowanie nowego obiektu JSON od podstaw
• map — zastosowanie przekształcenia do każdego elementu tablicy
• to_entries / from_entries — potraktowanie par klucz-wartość obiektu jako tablicy, aby można było je filtrować i ponownie zbudować

Wszystkie przykłady zakładają, że jq jest zainstalowany (apt install jq / brew install jq).

Najbardziej podstawową funkcją jq jest tworzenie obiektów: umieszczanie wyrażeń w {}, aby zbudować nowy obiekt JSON. Mogą Państwo wybrać pola, które mają zostać uwzględnione, oraz nadać im własne nazwy.

Składnia:

• { newKey: .existingField } — zmiana nazwy pola
• { name, age } — skrócona składnia, gdy nowy klucz ma taką samą nazwę jak pole
• { total: (.price * .qty) } — obliczenie wartości bezpośrednio w wyrażeniu

Poniższy fragment odczytuje JSON produktu i tworzy jego uproszczoną strukturę z obliczanym polem subtotal.

JSON spotykany w praktyce jest często zagnieżdżony. jq pozwala odwoływać się do zagnieżdżonych ścieżek wewnątrz konstruktora obiektu, jednocześnie spłaszczając strukturę.

W wyrażeniu określającym wartość konstruktora używają Państwo notacji ścieżki z kropkami:

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

Poniższy przykład pobiera głęboko zagnieżdżony rekord użytkownika i tworzy płaskie podsumowanie, odpowiednie jako wiersz nagłówkowy pliku CSV lub treść żądania API.

map(expr) jest odpowiednikiem jq konstrukcji for-each: stosuje expr do każdego elementu wejściowej tablicy i zwraca nową tablicę o tej samej długości.

Najważniejsze informacje:

• map(expr) jest skróconym zapisem [.[] | expr]
• Wyrażenie wewnątrz może być dowolnym filtrem jq — także tworzeniem obiektu
• Można połączyć je z select(), aby filtrować dane przed przekształceniem

Poniższy fragment przetwarza listę zamówień, zachowując tylko pola potrzebne w wykazie wysyłkowym.

Wewnątrz map mogą Państwo obliczać nowe wartości, konwertować typy i łączyć pola — a nie tylko je kopiować. Typowe wzorce obejmują:

• Interpolację ciągów znaków: "\(.first) \(.last)"
• Działania arytmetyczne: (.price * 1.2 | round) dla narzutu w wysokości 20%
• Wyrażenia warunkowe: if .score >= 90 then "A" else "B" end

Poniższy przykład wzbogaca listę pracowników, dodając obliczane pole fullName oraz etykietę seniority na podstawie liczby lat doświadczenia.

to_entries przekształca obiekt JSON w tablicę par {key, value}. Umożliwia to wykonywanie operacji na tablicach (map, select, sort) na polach obiektu — czego nie można zrobić bezpośrednio na obiekcie.

Przykładowe przekształcenie:

• Wejście: {"a": 1, "b": 2}
• Wyjście: [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

Operacją odwrotną jest from_entries, która ponownie przekształca tę tablicę w obiekt. Razem tworzą idiom to_entries | map(...) | from_entries służący do przekształceń na poziomie obiektu.

Jednym z najbardziej praktycznych zastosowań to_entries jest dynamiczne filtrowanie kluczy, które mają zostać zachowane lub usunięte, na podstawie samej nazwy klucza — czego nie można zrobić za pomocą tworzenia obiektu, gdy nazwy kluczy nie są wcześniej znane.

Wzorzec:

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

Poniższy fragment usuwa wszystkie klucze zaczynające się od podkreślenia (pola wewnętrzne/prywatne), zanim przekaże obiekt konfiguracji do zewnętrznej usługi.

Tworzenie obiektu umożliwia zmianę nazw kluczy, gdy ich nazwy są znane w momencie zapisu. to_entries pozwala zmieniać nazwy kluczy programowo — na przykład konwertować camelCase na snake_case lub dodawać prefiks.

Wewnątrz map aktualizują Państwo pole .key każdego wpisu, a następnie przekazują wynik do from_entries:

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) — konwersja camelCase na snake_case
• map(.key |= "app_" + .) — dodanie prefiksu do każdego klucza

Przykład dodaje prefiks APP_ do wszystkich nazw zmiennych środowiskowych, aby utworzyć dla nich przestrzeń nazw przed wstrzyknięciem do kontenera.

Wzorzec to_entries | map(...) | from_entries jest tak często używany, że jq udostępnia jego skróconą wersję: with_entries(expr).

Jest dokładnie równoważny, ale bardziej zwięzły:

• with_entries(.value |= . * 2) — podwojenie każdej wartości liczbowej
• with_entries(select(.value != null)) — usunięcie kluczy, których wartości wynoszą null
• with_entries(.key |= ascii_upcase) — zamiana wszystkich kluczy na wielkie litery

Poniższy fragment usuwa wszystkie klucze, których wartością jest null lub pusty ciąg znaków — to częsty etap czyszczenia danych przed wysłaniem żądania PATCH do interfejsu REST API.

Rzeczywiste przekształcenia łączą wiele operacji jq. Typowy potok przygotowujący payload API może:

1. Przefiltrować wejściową tablicę za pomocą map(select(...))
2. Zmienić strukturę każdego elementu za pomocą tworzenia obiektu
3. Dodać pola obliczane
4. Posortować wynik

Poniższy przykład odczytuje listę metryk serwerów, zachowuje tylko serwery o wysokim użyciu procesora i tworzy zwięzły payload alertu gotowy do wysłania metodą POST do webhooka.

jq może scalać dane wejściowe i tworzyć obiekty korzystające z wielu źródeł JSON za pomocą operatora dodawania + oraz wiązania zmiennych z użyciem as $var.

Przydatne wzorce:

• obj1 + obj2 — scalenie dwóch obiektów (w przypadku konfliktu kluczy wygrywa wartość po prawej stronie)
• --argjson — przekazanie drugiego dokumentu JSON jako zmiennej
• $ENV — bezpośredni odczyt zmiennych środowiskowych wewnątrz jq

Poniższy fragment scala podstawową konfigurację z nadpisaniami zależnymi od środowiska — to częsty wzorzec zarządzania konfiguracją aplikacji zgodnie z metodologią 12-factor w skryptach powłoki.

Mają Państwo następujący obiekt JSON i należy usunąć wszystkie klucze, których wartość jest mniejsza od 0, tworząc nowy obiekt zawierający wyłącznie wartości nieujemne. Które wyrażenie jq poprawnie realizuje to zadanie?

Wejście: {"a": 10, "b": -3, "c": 0, "d": 5}

Omówiono najważniejsze techniki zmiany struktury JSON za pomocą jq:

• Tworzenie obiektów {} — budowanie nowych obiektów przez wybieranie, zmianę nazw i obliczanie pól na podstawie danych wejściowych
• map(expr) — stosowanie dowolnego przekształcenia do każdego elementu tablicy, w tym tworzenie zagnieżdżonych obiektów i używanie select() do filtrowania
• to_entries / from_entries — konwersja obiektu na tablicę par {key, value}, co umożliwia operacje na kluczach i wartościach, a następnie konwersja z powrotem
• with_entries(expr) — zwięzły skrót pełnego potoku to_entries → map → from_entries
• Scalanie obiektów za pomocą + i --argjson w payloadach pochodzących z wielu źródeł

Te elementy można łączyć: filtrować za pomocą select, zmieniać strukturę przez tworzenie obiektów, wzbogacać danymi obliczanymi i łączyć wszystko w jednym czytelnym wyrażeniu jq. Opanowanie tych wzorców pozwala przetwarzać praktycznie dowolny payload JSON bezpośrednio w powłoce, bez pisania osobnego skryptu w Pythonie lub Node.