jq : manipuler du JSON en ligne de commande comme un pro

terminalclioutils

Vous appelez une API et vous obtenez 200 lignes de JSON. Vous voulez juste l’id du premier élément du tableau data. Avec curl | python -m json.tool vous formatez, mais vous ne filtrez pas. jq fait les deux — et bien plus.

Ce que fait jq

jq est un processeur de JSON en ligne de commande. Il lit du JSON sur l’entrée standard (ou depuis un fichier), applique un filtre, et retourne le résultat. Sa syntaxe est un mini-langage de requêtes, proche du XPath pour XML.

curl -s https://api.exemple.com/users | jq '.'
# Formate et colorise le JSON

curl -s https://api.exemple.com/users | jq '.[0].name'
# Retourne le nom du premier utilisateur

Installation

# macOS
brew install jq

# Linux (Debian/Ubuntu)
sudo apt install jq

# Windows (Chocolatey)
choco install jq

Filtres de base

# Formater (pretty-print)
echo '{"a":1,"b":2}' | jq '.'

# Accéder à un champ
echo '{"name":"Alice","age":30}' | jq '.name'
# "Alice"

# Accéder à un élément de tableau
echo '[1,2,3]' | jq '.[1]'
# 2

# Tous les éléments d'un tableau
echo '[{"id":1},{"id":2}]' | jq '.[]'

# Extraire un champ de chaque élément
echo '[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]' | jq '.[].name'
# "Alice"
# "Bob"

Construire de nouvelles structures

# Créer un objet avec des champs sélectionnés
curl -s https://api.exemple.com/users | jq '.[] | {id: .id, email: .email}'

# Créer un tableau de valeurs extraites
curl -s https://api.exemple.com/users | jq '[.[] | .name]'

# Renommer des champs
jq '.[] | {identifiant: .id, nom: .name}' users.json

Filtrer et sélectionner

# select() filtre les éléments qui satisfont une condition
jq '.[] | select(.age > 18)' users.json

# Filtrer par valeur exacte
jq '.[] | select(.role == "admin")' users.json

# Filtrer sur une valeur nullable
jq '.[] | select(.email != null)' users.json

# Combiner plusieurs conditions
jq '.[] | select(.age > 18 and .active == true)' users.json

Transformations utiles

# Compter les éléments
jq '. | length' tableau.json

# Trier
jq 'sort_by(.name)' users.json

# Valeur unique
jq '[.[].category] | unique' products.json

# Additionner des valeurs
jq '[.[].price] | add' orders.json

# Grouper
jq 'group_by(.category)' products.json

Cas d’usage réels

Extraire des IDs depuis une réponse API :

curl -s https://api.github.com/repos/astrojs/astro/issues \
  | jq '[.[] | {id: .number, titre: .title, auteur: .user.login}]'

Lire un champ de package.json :

jq -r '.version' package.json
# -r pour raw output (sans guillemets)

Transformer un CSV en JSON avec d’autres outils :

cat data.csv | python3 -c "import csv,json,sys; print(json.dumps(list(csv.DictReader(sys.stdin))))" | jq '.[] | select(.age | tonumber > 25)'

Chaîner des appels API :

USER_ID=$(curl -s https://api.exemple.com/me | jq -r '.id')
curl -s "https://api.exemple.com/users/$USER_ID/posts" | jq '.[0]'

+ Les points forts

  • Expressif — un mini-langage complet : filtres, transformations, conditions, fonctions
  • Composable — s’intègre parfaitement dans les pipes shell
  • -r pour les scripts — sortie brute sans guillemets, directement utilisable dans des variables shell
  • Rapide — traite des fichiers JSON volumineux sans délai
  • Disponible partout — présent dans la plupart des gestionnaires de paquets

- Les points faibles

  • Courbe d’apprentissage — la syntaxe jq est unique. Les premiers filtres complexes demandent des allers-retours dans la documentation
  • Pas de modification en place — jq ne modifie pas les fichiers. Il faut rediriger la sortie : jq '...' fichier.json > tmp.json && mv tmp.json fichier.json
  • Gestion des erreurs limitée — si un champ est absent, jq retourne null sans erreur. Facile de rater un problème silencieusement
  • Moins adapté aux gros fichiers en streaming — pour des fichiers JSON de plusieurs Go, des outils comme jstream sont plus appropriés

En résumé

jq est indispensable dès qu’on travaille avec des APIs ou des fichiers de config JSON. La syntaxe s’apprend progressivement — commencez par .champ et .[].champ, et le reste vient au fur et à mesure des besoins.

Voir aussi :

  • HTTPie — requêter des APIs et manipuler les réponses JSON
  • bat — afficher du JSON avec coloration syntaxique
  • ripgrep — chercher dans des fichiers JSON volumineux