Filtrare e selezionare JSON con le pipeline jq

jq è uno strumento da riga di comando leggero e potente per analizzare, filtrare e trasformare dati JSON. È il sed del JSON: gli si invia JSON tramite pipe e si ottiene in risposta un output strutturato.

• Preinstallato nella maggior parte delle distribuzioni Linux o disponibile tramite apt install jq / brew install jq
• Funziona perfettamente nelle pipeline shell con curl, cat e altri strumenti
• Supporta filtraggio, mapping, riduzione e conversione di formato

L'invocazione di base è: jq '<filter>' file.json oppure tramite pipe con cat file.json | jq '<filter>'. Il filtro . (punto) è l'identità: formatta in modo leggibile l'intero documento.

Per accedere a un campo in un oggetto JSON, utilizzi la notazione a punti: .fieldName. Può concatenare i selettori per navigare tra oggetti annidati.

• .name — campo di primo livello
• .address.city — campo annidato
• ."field-with-dash" — i campi con caratteri speciali richiedono le virgolette

Se il campo non esiste, jq restituisce null invece di generare un errore. Questo rende sicuro l'utilizzo negli script senza controlli aggiuntivi sui valori nulli per i campi opzionali.

Si accede agli array JSON con la notazione tra parentesi quadre. jq utilizza indici a partire da zero.

• .items[0] — primo elemento
• .items[-1] — ultimo elemento
• .items[1:3] — sezione (dall'indice 1 fino a prima del 3)
• .items[] — espande l'array: produce ogni elemento come valore separato (questo è l'iteratore)

L'iteratore [] è fondamentale nelle pipeline jq: consente di applicare i filtri successivi separatamente a ogni elemento.

Proprio come la pipe della shell |, jq dispone di un proprio operatore pipe interno. Questo passa l'output di un filtro come input al filtro successivo.

• jq '.users[] | .name' — itera sugli utenti, quindi estrae il nome di ciascuno
• jq '.data | .items[] | .id' — raggiunge data, espande items ed estrae id

Le pipe all'interno di un'espressione jq consentono di creare trasformazioni complesse un passaggio alla volta. Ogni fase riceve ciò che ha prodotto la fase precedente, inclusi più valori generati da un iteratore.

Concetto fondamentale: quando un iteratore produce N valori, ogni filtro successivo viene eseguito N volte, una per ciascun valore.

Il filtro select(condition) lascia passare un valore solo se la condizione è vera; in caso contrario non produce alcun output. È l'equivalente jq di grep o di WHERE in SQL.

• select(.age > 18) — conserva gli oggetti in cui age è maggiore di 18
• select(.status == "active") — verifica l'uguaglianza
• select(.name | startswith("A")) — test su una stringa annidato

Combini select con l'iteratore per filtrare gli array: .items[] | select(.active) produce solo gli elementi per cui .active è valutato come vero.

jq consente di rimodellare i dati costruendo nuovi oggetti con {} e nuovi array con [].

• {name: .name, city: .address.city} — seleziona e rinomina i campi in un nuovo oggetto
• [.items[] | .id] — raccoglie nuovamente in un array i valori iterati
• Forma abbreviata: {name, age} equivale a {name: .name, age: .age}

Racchiudere una pipeline in [...] si chiama costruzione di un array ed è essenziale quando si desidera un array JSON come output anziché un flusso di valori.

Il JSON del mondo reale è spesso profondamente annidato. jq offre due strumenti per la navigazione in profondità:

• .a.b.c — percorso esplicito quando la struttura è nota
• .. | .fieldName? — discesa ricorsiva: attraversa ogni nodo dell'albero e produce i valori nei nodi in cui esiste la chiave

L'operatore ? (try) sopprime gli errori quando un campo non esiste in un determinato nodo; è fondamentale quando si utilizza la discesa ricorsiva su alberi eterogenei.

Utilizzi la discesa ricorsiva con moderazione sui documenti di grandi dimensioni: visita ogni nodo e può essere lenta. Preferisca percorsi espliciti quando la struttura è prevedibile.

Uno dei casi d'uso più comuni di jq consiste nell'analizzare le risposte di API REST recuperate con curl. La combinazione di curl -s (silenzioso) con una pipeline jq consente di estrarre dati in modo pulito e adatto agli script.

• Estrarre un singolo valore: curl -s URL | jq '.field'
• Creare una tabella di riepilogo: iterare un array e ricostruire oggetti contenenti solo i campi necessari
• Utilizzare -r (output non elaborato) per rimuovere le virgolette che racchiudono i valori stringa, una funzione essenziale quando li si assegna a variabili shell

Suggerimento: aggiunga sempre -r quando l'output di jq verrà utilizzato come variabile shell o inviato tramite pipe a un altro comando.

jq offre due comode funzioni di ordine superiore per trasformare le collezioni:

• map(f) — applica il filtro f a ogni elemento di un array e restituisce un nuovo array. Equivale a [.[] | f].
• map_values(f) — applica f a ogni valore di un oggetto o array, preservando chiavi e indici.

Sono più leggibili rispetto a racchiudere manualmente le pipeline in [] e rappresentano lo stile jq idiomatico per le trasformazioni che devono rimanere array.

I dati JSON provenienti da fonti esterne sono spesso incoerenti: alcuni campi possono mancare o avere valore null. jq offre l'operatore alternativo // (doppia barra) per fornire un valore predefinito.

• .nickname // "anonymous" — utilizza .nickname se non è null o false, altrimenti utilizza "anonymous"
• .count // 0 — valore predefinito numerico
• Da combinare con select: select((.status // "inactive") == "active")

È molto più conciso dell'equivalente shell ${VAR:-default} e si integra facilmente in pipeline più lunghe.

La registrazione strutturata in JSON è uno standard nei sistemi moderni. Ecco uno script realistico che legge un file di log JSON delimitato da newline, filtra le voci di errore e formatta un riepilogo leggibile.

Modelli principali utilizzati:

• -c (output compatto) — un oggetto JSON per riga, utile per l'invio tramite pipe ai cicli shell
• --arg name value — inserisce una variabile shell come argomento stringa di jq
• select per filtrare in base al livello del log
• -r per ottenere output stringa non elaborato, adatto a echo

Verifichi la Sua comprensione del funzionamento di select() all'interno di una pipeline jq.

Consideri il seguente comando:

Quale sarà l'output?

Ha visto gli strumenti fondamentali di jq per esplorare e filtrare JSON dalla riga di comando:

• Notazione con il punto (.field, .a.b.c) seleziona i campi degli oggetti
• Accesso agli array (.[0], .[]) indicizza gli array e ne scorre gli elementi
• Operatore pipe (|) concatena i filtri; ogni fase elabora tutti i valori della fase precedente
• select(cond) filtra i valori, lasciando passare solo quelli per cui la condizione è vera
• Costruzione di oggetti e array ({}, [], map()) ristruttura i dati in nuove strutture
• Operatore alternativo (//) fornisce valori predefiniti per i campi null o mancanti
• Flag -r rimuove le virgolette per assegnare valori a variabili della shell; --arg inserisce in modo sicuro le variabili della shell
• Discesa ricorsiva (.. | .field?) cerca in profondità negli alberi annidati quando il percorso non è noto

Con questi strumenti può trasformare qualsiasi risposta di un'API JSON, file di log o configurazione nei dati di cui hanno bisogno i Suoi script, senza mai uscire dal terminale.