jq-Tutorial: JSON filtern und transformieren

jq ist das Standard-Kommandozeilentool zum Zerlegen, Filtern und Transformieren von JSON. Es macht aus Einzeilern eine mächtige Abfragesprache für API-Antworten, Logdateien und Konfigurationen. Dieses Tutorial behandelt die Installation, die Kern-Filter, die du täglich verwendest, und eine Sammlung von Copy-and-Paste-Rezepten für die häufigsten Aufgaben aus der Praxis.

Was ist jq?

jq liest JSON aus einer Datei oder von Standard-Input, wendet einen Filter an und schreibt JSON (oder reinen Text) auf Standard-Output. Es pretty-printet standardmäßig und schickt deine Daten nirgendwohin —— es ist ein lokales Binary, ideal für sensible Payloads.

jq installieren

# macOS
brew install jq

# Debian / Ubuntu
sudo apt-get install jq

# Windows (winget oder choco)
winget install jqlang.jq

# Prüfen
jq --version

Der Identity-Filter: alles pretty-printen

Der einfachste Filter, ., gibt die Eingabe unverändert zurück —— was jq zu einem sofortigen Formatter macht:

# Datei pretty-printen
jq . data.json

# Eine curl-Antwort pretty-printen
curl -s https://api.example.com/users | jq .

# Andersrum: minifizieren (kompakte Ausgabe)
jq -c . data.json

Felder auswählen

Bohre dich in Objekte mit .key und in Arrays mit []:

echo '{"user":{"name":"Ada","age":36}}' | jq '.user.name'
# "Ada"

# Alle Elemente eines Arrays
echo '[{"id":1},{"id":2}]' | jq '.[]'
# {"id":1}
# {"id":2}

# Ein Feld aus jedem Array-Element
echo '[{"id":1,"name":"Ada"},{"id":2,"name":"Bob"}]' | jq '.[].name'
# "Ada"
# "Bob"

# JSON-Anführungszeichen mit -r weglassen (raw output)
jq -r '.[].name' users.json

Mit select filtern

# Nur Objekte behalten, die einer Bedingung entsprechen
echo '[{"name":"Ada","active":true},{"name":"Bob","active":false}]' \
  | jq '.[] | select(.active == true)'
# {"name":"Ada","active":true}

# Numerischer Vergleich
jq '.[] | select(.age > 30)' users.json

Mit map und Objektkonstruktion transformieren

# Jedes Element in ein neues Objekt umbauen
echo '[{"id":1,"name":"Ada","email":"a@x.com"}]' \
  | jq 'map({ userId: .id, label: .name })'
# [{"userId":1,"label":"Ada"}]

# Flache Werteliste herausziehen
jq '[.[].email]' users.json     # ["a@x.com", ...]

# Filter mit | aneinanderreihen
jq '.items | map(.price) | add' order.json   # Summe aller Preise

Häufige Rezepte

Objekte umformen: to_entries / from_entries

Die zwei nützlichsten Objekt-Shape-Transformer in jq:

# Jeden Key umbenennen (hier in Kleinbuchstaben)
echo '{"Name":"Ada","Active":true}' \
  | jq 'with_entries(.key |= ascii_downcase)'
# → {"name":"Ada","active":true}

# Keys mit null-Wert verwerfen
jq 'with_entries(select(.value != null))' file.json

# Objekt ⇄ Array von Paaren
jq 'to_entries' file.json     # → [{"key":"name","value":"Ada"}, ...]
jq 'from_entries' pairs.json  # → {"name":"Ada", ...}

Interpolation und Ausgabeformate: \(.x), @csv, @json, @base64

jq hat String-Interpolation und eingebaute Format-Strings, um JSON in andere Formate zu verwandeln:

# String-Interpolation innerhalb eines String-Literals
jq -r '"\(.user) bought \(.items|length) items"' order.json

# Eine CSV-Zeile pro Objekt
jq -r '.[] | [.id, .name, .total] | @csv' orders.json

# Inline-JSON für die Shell (escaped string literal)
jq -r '.user | @json' record.json

# Einen Wert Base64-kodieren (praktisch für Tokens / Data-URIs)
jq -r '.payload | @base64' message.json
# Decode-Seite: jq akzeptiert @base64d in neueren Versionen

JSON mit jq validieren

Da jq bei ungültiger Eingabe mit Nicht-Null beendet, ist jq empty file.json ein sauberer Validitätscheck für Skripte und CI —— siehe Wie man JSON validiert für weitere Validierungsansätze.

Wann ein Browser-Tool schneller ist

jq glänzt in Skripten und Pipelines, aber für einen schnellen Einzelfall —— eine eingefügte Antwort pretty-printen, eine unbekannte Struktur inspizieren oder kaputtes JSON reparieren —— braucht ein Browser-Tool keine Installation und kein Shell-Escaping:

• JSON Fix —— formatieren und reparieren in einem Schritt
• JSON Viewer —— große Antworten als zusammenklappbaren Baum erkunden
• Wie man JSON formatiert —— Formatieren in Code und auf der Kommandozeile

Häufig gestellte Fragen

Wie pretty-printe ich JSON mit jq?

Führe jq . file.json aus —— der Identity-Filter . gibt die Eingabe zurück und jq formatiert sie standardmäßig. Verwende -c für kompakte Ausgabe.

Wie extrahiere ich ein einzelnes Feld mit jq?

Nutze einen Pfadfilter wie jq '.data.token' und füge -r für Raw-Ausgabe hinzu, wenn du den Wert ohne umgebende Anführungszeichen willst.

Wie filtere ich ein JSON-Array mit jq?

Iteriere mit .[] und wende select() an, z. B. jq '.[] | select(.active == true)'.

Kann jq JSON validieren?

Ja —— jq empty file.json parst die Eingabe und beendet mit Nicht-Null, wenn sie ungültig ist, was es in CI praktisch macht. Details siehe Wie man JSON validiert.

Weiterlesen

• Wie man JSON formatiert —— jq, JavaScript, Python und Browser-Formatierung
• Wie man JSON minifiziert —— kompakte Ausgabe mit jq -c und darüber hinaus
• Wie man JSON validiert —— inklusive jq empty in CI
• JSON Viewer —— eine Browser-Alternative zum JSON-Erkunden