JSON-Objekte mit jq umformen und erstellen

Rohes JSON aus APIs oder Protokolldateien hat nur selten genau die Struktur, die Sie benötigen. Möglicherweise erhalten Sie ein großes Objekt, möchten aber nur bestimmte Felder verwenden, Schlüssel umbenennen, verschachtelte Strukturen abflachen oder eine vollständig neue Nutzlast für einen anderen Dienst erstellen.

jq ist ein schlanker, leistungsfähiger JSON-Prozessor für die Kommandozeile, mit dem solche Transformationen in einer einzigen Pipeline möglich werden. In dieser Lektion lernen Sie die drei grundlegenden Techniken zum Umformen von Daten kennen:

• Objekterstellung – ein neues JSON-Objekt von Grund auf erstellen
• map – eine Transformation auf jedes Element eines Arrays anwenden
• to_entries / from_entries – die Schlüssel-Wert-Paare eines Objekts als Array behandeln, um sie zu filtern und neu zusammenzusetzen

Bei allen Beispielen wird vorausgesetzt, dass jq installiert ist (apt install jq / brew install jq).

Die grundlegendste jq-Funktion ist die Objekterstellung: Sie schließen Ausdrücke in {} ein, um ein neues JSON-Objekt zu erstellen. Dabei wählen Sie aus, welche Felder enthalten sein sollen und wie sie heißen.

Syntax:

• { newKey: .existingField } – ein Feld umbenennen
• { name, age } – Kurzschreibweise, wenn der neue Schlüssel dem Feldnamen entspricht
• { total: (.price * .qty) } – einen Wert direkt im Ausdruck berechnen

Das folgende Snippet liest ein Produkt-JSON ein und erzeugt daraus eine kompaktere Struktur mit dem berechneten Feld subtotal.

JSON aus der Praxis ist häufig verschachtelt. Mit jq können Sie in einem Objektkonstruktor auf verschachtelte Pfade zugreifen und dabei die Struktur gleichzeitig abflachen.

Verwenden Sie die Punktpfadnotation innerhalb des Wertausdrucks des Konstruktors:

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

Das folgende Beispiel nimmt einen tief verschachtelten Benutzerdatensatz und erstellt daraus eine flache Zusammenfassung, die sich für eine CSV-Kopfzeile oder den Body einer API-Anfrage eignet.

map(expr) entspricht in jq einer for-each-Schleife: Der Ausdruck expr wird auf jedes Element eines Eingabearrays angewendet, und es wird ein neues Array gleicher Länge zurückgegeben.

Wichtige Punkte:

• map(expr) ist eine Kurzschreibweise für [.[] | expr]
• Der enthaltene Ausdruck kann jeder jq-Filter sein – einschließlich der Objekterstellung
• Verketten Sie map() mit select(), um vor der Transformation zu filtern

Das Snippet verarbeitet eine Liste von Bestellungen und behält nur die für einen Versandbegleitschein benötigten Felder bei.

Innerhalb von map können Sie neue Werte berechnen, Typen konvertieren und Felder kombinieren – sie also nicht nur kopieren. Häufige Muster sind:

• String-Interpolation: "\(.first) \(.last)"
• Arithmetik: (.price * 1.2 | round) für einen Aufschlag von 20 %
• Bedingungen: if .score >= 90 then "A" else "B" end

Das folgende Beispiel erweitert eine Liste von Mitarbeitenden um den berechneten vollständigen Namen fullName und eine Bezeichnung für die Betriebszugehörigkeit seniority, die auf den Jahren an Berufserfahrung basiert.

to_entries wandelt ein JSON-Objekt in ein Array aus {key, value}-Paaren um. Dadurch können Sie Array-Operationen (map, select, sort) auf die Felder eines Objekts anwenden – etwas, das direkt auf einem Objekt nicht möglich ist.

Beispieltransformation:

• Eingabe: {"a": 1, "b": 2}
• Ausgabe: [{"key": "a", "value": 1}, {"key": "b", "value": 2}]

Die umgekehrte Operation ist from_entries; sie wandelt das Array wieder in ein Objekt um. Zusammen bilden sie das Idiom to_entries | map(...) | from_entries für Transformationen auf Objektebene.

Eine der praktischsten Anwendungen von to_entries ist das dynamische Filtern der beizubehaltenden oder zu entfernenden Schlüssel anhand des Schlüsselnamens selbst – etwas, das mit der Objekterstellung nicht möglich ist, wenn die Schlüsselnamen im Voraus nicht bekannt sind.

Muster:

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

Das folgende Snippet entfernt alle Schlüssel, die mit einem Unterstrich beginnen (interne/private Felder), bevor ein Konfigurationsobjekt an einen externen Dienst weitergeleitet wird.

Mit der Objekterstellung können Sie Schlüssel umbenennen, wenn ihre Namen beim Schreiben bekannt sind. to_entries ermöglicht es Ihnen, Schlüssel programmatisch umzubenennen – beispielsweise camelCase in snake_case umzuwandeln oder ein Präfix hinzuzufügen.

Innerhalb von map aktualisieren Sie das Feld .key jedes Eintrags und leiten anschließend an from_entries weiter:

• map(.key |= gsub("(?<=[a-z])(?=[A-Z])"; "_") | .key |= ascii_downcase) – camelCase in snake_case umwandeln
• map(.key |= "app_" + .) – jedem Schlüssel ein Präfix hinzufügen

Das Beispiel versieht alle Namen von Umgebungsvariablen mit dem Präfix APP_, um sie vor der Injektion in einen Container zu namespacen.

Das Muster to_entries | map(...) | from_entries kommt so häufig vor, dass jq dafür eine Kurzschreibweise bereitstellt: with_entries(expr).

Sie ist genau gleichwertig, aber kürzer:

• with_entries(.value |= . * 2) – jeden numerischen Wert verdoppeln
• with_entries(select(.value != null)) – Schlüssel mit dem Wert null entfernen
• with_entries(.key |= ascii_upcase) – alle Schlüssel in Großbuchstaben umwandeln

Das Snippet entfernt alle Schlüssel, deren Wert null oder eine leere Zeichenkette ist – ein üblicher Bereinigungsschritt vor dem Senden einer PATCH-Anfrage an eine REST-API.

Transformationen aus der Praxis verketten mehrere jq-Operationen. Eine typische Pipeline zur Vorbereitung einer API-Nutzlast könnte:

1. das Eingabearray mit map(select(...)) filtern
2. jedes Element mit der Objekterstellung umformen
3. berechnete Felder hinzufügen
4. das Ergebnis sortieren

Das folgende Beispiel liest eine Liste von Servermetriken ein, behält nur Server mit hoher CPU-Auslastung bei und erstellt eine kompakte Alarmnutzlast, die direkt per POST an einen Webhook gesendet werden kann.

Mit jq können Sie Eingaben zusammenführen und Objekte erstellen, die mithilfe des Additionsoperators + und der Variablenbindung mit as $var Daten aus mehreren JSON-Quellen beziehen.

Nützliche Muster:

• obj1 + obj2 – zwei Objekte zusammenführen (bei Konflikten hat die rechte Seite Vorrang)
• --argjson – ein zweites JSON-Dokument als Variable übergeben
• $ENV – Umgebungsvariablen direkt innerhalb von jq lesen

Das Snippet führt eine Basiskonfiguration mit umgebungsspezifischen Überschreibungen zusammen – ein gängiges Muster für die Verwaltung von Konfigurationen nach dem 12-Factor-Prinzip in Shell-Skripten.

Sie haben das folgende JSON-Objekt und müssen alle Schlüssel entfernen, deren Wert kleiner als 0 ist, sodass ein neues Objekt mit ausschließlich nicht negativen Werten entsteht. Welcher jq-Ausdruck erfüllt diese Aufgabe korrekt?

Eingabe: {"a": 10, "b": -3, "c": 0, "d": 5}

Sie haben die wichtigsten Techniken zum Umformen von JSON mit jq behandelt:

• Objekterstellung {} – neue Objekte erstellen, indem Sie Felder aus einer Eingabe auswählen, umbenennen und berechnen
• map(expr) – eine beliebige Transformation auf jedes Element eines Arrays anwenden, einschließlich der Erstellung verschachtelter Objekte und select() zum Filtern
• to_entries / from_entries – ein Objekt in ein Array aus {key, value}-Paaren umwandeln, um Operationen auf Schlüsseln und Werten zu ermöglichen, und anschließend zurückwandeln
• with_entries(expr) – die kompakte Kurzschreibweise für die vollständige Pipeline to_entries → map → from_entries
• Objekte zusammenführen mit + und --argjson für Nutzlasten aus mehreren Quellen

Diese Bausteine lassen sich kombinieren: mit select filtern, mit der Objekterstellung umformen, mit berechneten Feldern erweitern und alles in einem einzigen gut lesbaren jq-Ausdruck verketten. Wenn Sie diese Muster beherrschen, können Sie praktisch jede JSON-Nutzlast direkt in der Shell verarbeiten, ohne ein eigenes Skript in Python oder Node schreiben zu müssen.