JSON mit jq-Pipelines filtern und auswählen

jq ist ein schlankes, leistungsfähiges Befehlszeilenwerkzeug zum Parsen, Filtern und Transformieren von JSON-Daten. Es ist das sed für JSON: Sie leiten JSON hinein und erhalten strukturierte Ausgabe zurück.

• Auf den meisten Linux-Distributionen vorinstalliert oder über apt install jq / brew install jq verfügbar
• Funktioniert nahtlos in Shell-Pipelines mit curl, cat und anderen Werkzeugen
• Unterstützt Filtern, Abbilden, Reduktion und Formatkonvertierung

Der grundlegende Aufruf lautet: jq '<filter>' file.json oder als Pipeline cat file.json | jq '<filter>'. Der Filter . (Punkt) ist die Identitätsfunktion – er gibt das gesamte Dokument formatiert aus.

Um auf ein Feld in einem JSON-Objekt zuzugreifen, verwenden Sie die Punktnotation: .fieldName. Verschachtelte Objekte können Sie über mehrere Selektoren hintereinander durchlaufen.

• .name – Feld der obersten Ebene
• .address.city – verschachteltes Feld
• ."field-with-dash" – Felder mit Sonderzeichen benötigen Anführungszeichen

Wenn das Feld nicht vorhanden ist, gibt jq null zurück, statt einen Fehler zu erzeugen. Dadurch können Sie es in Skripten sicher verwenden, ohne optionale Felder zusätzlich auf null prüfen zu müssen.

Auf JSON-Arrays greifen Sie mit der Klammernotation zu. jq verwendet eine nullbasierte Indizierung.

• .items[0] – erstes Element
• .items[-1] – letztes Element
• .items[1:3] – Ausschnitt (Index 1 bis, aber nicht einschließlich, 3)
• .items[] – das Array aufspalten: gibt jedes Element als separaten Wert aus (dies ist der Iterator)

Der Iterator [] ist grundlegend für jq-Pipelines: Mit ihm können Sie nachfolgende Filter unabhängig auf jedes Element anwenden.

Wie die Shell-Pipe | verfügt auch jq über einen eigenen internen Pipe-Operator. Er übergibt die Ausgabe eines Filters als Eingabe an den nächsten.

• jq '.users[] | .name' – Benutzer durchlaufen und anschließend aus jedem den Namen extrahieren
• jq '.data | .items[] | .id' – zu den Daten navigieren, die Elemente aufspalten und die IDs extrahieren

Pipes innerhalb eines jq-Ausdrucks ermöglichen es, komplexe Transformationen Schritt für Schritt aufzubauen. Jede Stufe erhält alles, was die vorherige Stufe erzeugt hat – einschließlich mehrerer Werte aus einem Iterator.

Wichtige Erkenntnis: Wenn ein Iterator N Werte erzeugt, wird jeder nachgelagerte Filter N-mal ausgeführt, einmal pro Wert.

Der Filter select(condition) lässt einen Wert nur dann passieren, wenn die Bedingung wahr ist; andernfalls erzeugt er keine Ausgabe. Er entspricht in jq dem grep-Befehl oder WHERE in SQL.

• select(.age > 18) – Objekte behalten, deren Alter größer als 18 ist
• select(.status == "active") – Gleichheitsprüfung
• select(.name | startswith("A")) – verschachtelte Zeichenkettenprüfung

Kombinieren Sie select mit dem Iterator, um Arrays zu filtern: .items[] | select(.active) gibt nur Elemente aus, bei denen .active einen Wahrheitswert ergibt.

Mit jq können Sie Daten umformen, indem Sie neue Objekte mit {} und neue Arrays mit [] erstellen.

• {name: .name, city: .address.city} – Felder auswählen und in ein neues Objekt übernehmen
• [.items[] | .id] – iterierte Werte wieder in einem Array sammeln
• Kurzform: {name, age} entspricht {name: .name, age: .age}

Das Einschließen einer Pipeline in [...] wird als Array-Erstellung bezeichnet und ist unerlässlich, wenn Sie als Ausgabe ein JSON-Array statt eines Wertestroms benötigen.

JSON aus der Praxis ist häufig tief verschachtelt. jq stellt zwei Werkzeuge für die Navigation in die Tiefe bereit:

• .a.b.c – expliziter Pfad, wenn die Struktur bekannt ist
• .. | .fieldName? – rekursiver Abstieg: durchläuft jeden Knoten im Baum und gibt Werte aus, wenn der Schlüssel vorhanden ist

Der ?-Operator (try) unterdrückt Fehler, wenn ein Feld an einem bestimmten Knoten nicht vorhanden ist. Das ist entscheidend, wenn Sie den rekursiven Abstieg auf heterogene Bäume anwenden.

Verwenden Sie den rekursiven Abstieg bei großen Dokumenten sparsam – er besucht jeden Knoten und kann langsam sein. Bevorzugen Sie explizite Pfade, wenn die Struktur vorhersehbar ist.

Einer der häufigsten Anwendungsfälle für jq ist das Parsen von REST-API-Antworten, die mit curl abgerufen wurden. Die Kombination aus curl -s (stille Ausgabe) und einer jq-Pipeline ermöglicht eine übersichtliche, skriptfähige Datenextraktion.

• Einen einzelnen Wert extrahieren: curl -s URL | jq '.field'
• Eine Übersichtstabelle erstellen: ein Array durchlaufen und Objekte mit nur den benötigten Feldern neu aufbauen
• -r (rohe Ausgabe) verwenden, um die umschließenden Anführungszeichen von Zeichenkettenwerten zu entfernen – unerlässlich bei der Zuweisung an Shell-Variablen

Tipp: Fügen Sie immer -r hinzu, wenn die jq-Ausgabe als Shell-Variable verwendet oder an einen anderen Befehl weitergeleitet wird.

jq stellt zwei praktische Funktionen höherer Ordnung zum Transformieren von Sammlungen bereit:

• map(f) – wendet den Filter f auf jedes Element eines Arrays an und gibt ein neues Array zurück. Entspricht [.[] | f].
• map_values(f) – wendet f auf jeden Wert eines Objekts oder Arrays an und behält die Schlüssel bzw. Indizes bei.

Diese Funktionen sind besser lesbar, als Pipelines manuell in [] einzuschließen, und entsprechen dem idiomatischen jq-Stil für Transformationen, die als Arrays erhalten bleiben sollen.

JSON-Daten aus externen Quellen sind häufig uneinheitlich – Felder können fehlen oder null sein. jq stellt den Alternativoperator // (doppelter Schrägstrich) bereit, um einen Standardwert anzugeben.

• .nickname // "anonymous" – .nickname verwenden, wenn der Wert nicht null oder false ist, andernfalls "anonymous"
• .count // 0 – numerischer Standardwert
• Mit select kombinieren: select((.status // "inactive") == "active")

Das ist deutlich kompakter als das entsprechende Shell-Konstrukt ${VAR:-default} und lässt sich problemlos in längeren Pipelines verwenden.

Strukturiertes JSON-Logging ist in modernen Systemen Standard. Hier ist ein praxisnahes Skript, das eine JSON-Logdatei mit einem JSON-Objekt pro Zeile einliest, Fehler­einträge filtert und eine lesbare Zusammenfassung formatiert.

Wichtige verwendete Muster:

• -c (kompakte Ausgabe) – ein JSON-Objekt pro Zeile, praktisch für die Weiterleitung an Shell-Schleifen
• --arg name value – eine Shell-Variable als jq-Zeichenkettenargument übergeben
• select zum Filtern nach Log-Level
• -r für die Ausgabe roher Zeichenketten, geeignet für echo

Testen Sie Ihr Verständnis dafür, wie select() innerhalb einer jq-Pipeline funktioniert.

Gegeben ist der folgende Befehl:

Wie lautet die Ausgabe?

Sie haben die grundlegenden jq-Werkzeuge zum Navigieren und Filtern von JSON über die Kommandozeile behandelt:

• Punktnotation (.field, .a.b.c) wählt Felder aus Objekten aus
• Array-Zugriff (.[0], .[]) greift per Index auf Arrays zu und durchläuft sie
• Pipe-Operator (|) verkettet Filter; jede Stufe verarbeitet alle Werte der vorherigen Stufe
• select(cond) filtert Werte und gibt nur diejenigen weiter, für die die Bedingung wahr ist
• Erstellung von Objekten und Arrays ({}, [], map()) formt Daten in neue Strukturen um
• Alternativoperator (//) liefert Standardwerte für null oder fehlende Felder
• -r-Flag entfernt Anführungszeichen für die Zuweisung an Shell-Variablen; --arg fügt Shell-Variablen sicher ein
• Rekursiver Abstieg (.. | .field?) durchsucht tief verschachtelte Strukturen, wenn der Pfad unbekannt ist

Mit diesen Bausteinen können Sie jede JSON-API-Antwort, Protokolldatei oder Konfiguration genau in die Daten umwandeln, die Ihre Skripte benötigen – und das alles, ohne das Terminal zu verlassen.