Mit jq auf der Kommandozeile mit JSON arbeiten

Ziel

JSON aus einer API-Antwort, einer Log-Zeile oder einer Konfigurationsdatei innerhalb einer Pipeline extrahieren, filtern oder umformen, ohne ein Wegwerfprogramm zu schreiben.

Voraussetzungen

jq installiert; eine Eingabe, die gültiges JSON oder ein Strom von JSON-Texten ist; eine ungefähre Vorstellung von der Form der Eingabe (jq 'keys', jq '.[0]' und jq 'paths' helfen bei der Erkundung).

Schritte

1. Bestätigen, dass die Eingabe parst, und ihre Form ansehen: jq . gibt formatiert aus; bei grosser Eingabe ist jq -c '.[0]' oder jq 'keys' günstiger zu lesen.
2. Navigieren: .foo.bar und .[0] indizieren, .[] iteriert über ein Array oder die Werte eines Objekts, .foo? unterdrückt den Fehler, wenn die Eingabe kein Objekt ist. Filter mit | verketten.
3. Filtern und umformen: .items[] | select(.status == "open") | {id, name}; map(f) wendet einen Filter auf jedes Element an; to_entries, from_entries und with_entries(f) wandeln zwischen Objekten und Schlüssel-Wert-Listen um; a // b liefert b, wenn a nur null oder false ergibt.
4. Shell-Werte mit --arg name value (immer ein String) oder --argjson name json (typisiert) übergeben und im Filter mit $name verwenden. Das Handbuch merkt an, dass --arg foo 123 den String "123" bindet, keine Zahl.
5. Die Ausgabeform für das nächste Programm wählen: -r (--raw-output) schreibt Strings ohne Anführungszeichen; -c gibt kompaktes einzeiliges JSON aus; @tsv, @csv und @sh formatieren Arrays für tabgetrennte, CSV- oder POSIX-Shell-Verarbeitung; --raw-output0 trennt Ausgaben mit NUL, wenn Werte Zeilenumbrüche enthalten können.
6. Viele Eingaben verarbeiten: standardmässig läuft der Filter einmal pro JSON-Text im Strom; -s (--slurp) sammelt sie in einem Array; -n (--null-input) führt den Filter einmal mit null als Eingabe aus, was sich nutzen lässt, um JSON von Grund auf zu bauen: jq -n --arg a "$x" '{a: $a}'.
7. Fehlende Daten zum Scheitern bringen: -e (--exit-status) setzt den Exit-Status auf 1, wenn die letzte Ausgabe null oder false ist, und auf 4, wenn kein gültiges Ergebnis erzeugt wurde; das in Skripten prüfen statt auf einen leeren String zu testen.

Erwartetes Ergebnis

Eine einzeilige Pipeline, die genau das benötigte Feld oder die benötigte Struktur liefert, korrekt für das nächste Programm zitiert, und einen von null verschiedenen Exit-Status, wenn die Daten fehlen.

Grenzen und Prüfbasis

Die Semantik folgt dem zitierten jq-Handbuch. jq lädt jeden JSON-Text vollständig, ausser --stream wird verwendet, deshalb brauchen sehr grosse Dokumente Streaming oder ein anderes Werkzeug. Das Handbuch hält fest, dass sich jqs Umgang mit Zahlen im Lauf der Zeit geändert hat und von den Build-Optionen abhängt, und dass das Parsen bei sehr grossen oder sehr präzisen Zahlen Präzision verlieren kann; bevor man sich für Arithmetik mit solchen Werten auf jq verlässt, das Handbuch für die installierte Version prüfen. Es werden keine Zeitmessungen behauptet.