JantonioFC/skillsbank

jq — Interrogation et transformation JSON

Vue d'ensemble

jq est l'outil CLI standard pour interroger et remodeler du JSON. Ce skill couvre une utilisation pratique et experte : filtrage de données profondément imbriquées, transformation de structures, agrégation de valeurs et composition de jq dans des pipelines shell. Chaque exemple est prêt à être copié-collé pour des workflows réels.

Quand utiliser ce skill

• Lors de l'analyse de sorties JSON provenant d'API, d'outils CLI (AWS, GitHub, kubectl, docker) ou de fichiers journaux
• Lors de la transformation de structures JSON (renommer des clés, aplatir des tableaux, regrouper des enregistrements)
• Lorsque l'utilisateur a besoin de jq dans un script bash ou une commande en une ligne
• Lorsqu'il faut expliquer ce que fait une expression jq complexe

Comment ça marche

jq prend une expression de filtre et l'applique à une entrée JSON. Les filtres se composent avec des pipes (|), et jq gère nativement les tableaux, objets, chaînes, nombres, booléens et null.

Sélection de base

# Extraire un champ
echo '{"name":"alice","age":30}' | jq '.name'
# "alice"

# Accès imbriqué
echo '{"user":{"email":"[email protected]"}}' | jq '.user.email'

# Index de tableau
echo '[10, 20, 30]' | jq '.[1]'
# 20

# Tranche de tableau
echo '[1,2,3,4,5]' | jq '.[2:4]'
# [3, 4]

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

Filtrage avec select

# Conserver uniquement les éléments correspondants
echo '[{"role":"admin"},{"role":"user"},{"role":"admin"}]' \
  | jq '[.[] | select(.role == "admin")]'

# Comparaison numérique
curl -s https://api.github.com/repos/owner/repo/issues \
  | jq '[.[] | select(.comments > 5)]'

# Tester si un champ existe et n'est pas nul
jq '[.[] | select(.email != null)]'

# Combiner des conditions
jq '[.[] | select(.active == true and .score >= 80)]'

Mappage et transformation

# Extraire un champ de chaque élément du tableau
echo '[{"name":"alice","age":30},{"name":"bob","age":25}]' \
  | jq '[.[] | .name]'
# ["alice", "bob"]

# Raccourci : map()
jq 'map(.name)'

# Construire un nouvel objet par élément
jq '[.[] | {user: .name, years: .age}]'

# Ajouter un champ calculé
jq '[.[] | . + {senior: (.age > 28)}]'

# Renommer des clés
jq '[.[] | {username: .name, email_address: .email}]'

Agrégation et reduce

# Somme de toutes les valeurs
echo '[1, 2, 3, 4, 5]' | jq 'add'
# 15

# Somme d'un champ sur des objets
jq '[.[].price] | add'

# Compter les éléments
jq 'length'

# Max / min
jq 'max_by(.score)'
jq 'min_by(.created_at)'

# reduce : accumulateur personnalisé
echo '[1,2,3,4,5]' | jq 'reduce .[] as $x (0; . + $x)'
# 15

# Grouper par champ
jq 'group_by(.department)'

# Compter par groupe
jq 'group_by(.status) | map({status: .[0].status, count: length})'

Interpolation de chaînes et formatage

# Interpolation de chaînes
jq -r '.[] | "\(.name) a \(.age) ans"'

# Format CSV (sans en-tête)
jq -r '.[] | [.name, .age, .email] | @csv'

# Format TSV
jq -r '.[] | [.name, .score] | @tsv'

# Encoder une valeur en URL
jq -r '.query | @uri'

# Encoder en Base64
jq -r '.data | @base64'

Travailler avec les clés et les chemins

# Lister toutes les clés de premier niveau
jq 'keys'

# Vérifier si une clé existe
jq 'has("email")'

# Supprimer une clé
jq 'del(.password)'

# Supprimer des clés imbriquées de chaque élément
jq '[.[] | del(.internal_id, .raw_payload)]'

# Descente récursive : trouver toutes les valeurs d'une clé dans l'arbre
jq '.. | .id? // empty'

# Obtenir tous les chemins feuilles
jq '[paths(scalars)]'

Conditionnels et gestion des erreurs

# if-then-else
jq 'if .score >= 90 then "A" elif .score >= 80 then "B" else "C" end'

# Opérateur alternatif : utiliser une valeur de repli si nul ou faux
jq '.nickname // .name'

# try-catch : ignorer les erreurs au lieu de s'arrêter
jq '[.[] | try .nested.value catch null]'

# Supprimer les sorties nulles avec // empty
jq '.[] | .optional_field // empty'

Intégration pratique dans le shell

# Lire depuis un fichier
jq '.users' data.json

# Sortie compacte (sans espace blanc) pour un pipe ultérieur
jq -c '.[]' records.json | while IFS= read -r record; do
  echo "Traitement de : $record"
done

# Passer une variable shell à jq
STATUS="active"
jq --arg s "$STATUS" '[.[] | select(.status == $s)]'

# Passer un nombre
jq --argjson threshold 42 '[.[] | select(.value > $threshold)]'

# Lire plusieurs lignes JSON dans un tableau
jq -s '.' records.ndjson

# Plusieurs fichiers : tout regrouper en un tableau
jq -s 'add' file1.json file2.json

# Pipeline null-safe à partir d'une commande
kubectl get pods -o json | jq '.items[] | {name: .metadata.name, status: .status.phase}'

# GitHub CLI : extraire les numéros de PR
gh pr list --json number,title | jq -r '.[] | "\(.number)\t\(.title)"'

# AWS CLI : lister les IDs des instances en cours d'exécution
aws ec2 describe-instances \
  | jq -r '.Reservations[].Instances[] | select(.State.Name=="running") | .InstanceId'

# Docker : afficher les noms et images des conteneurs
docker inspect $(docker ps -q) | jq -r '.[] | "\(.Name)\t\(.Config.Image)"'

Patrons avancés

# Transposer un objet de tableaux en un tableau d'objets
# Entrée : {"names":["a","b"],"scores":[10,20]}
jq '[.names, .scores] | transpose | map({name: .[0], score: .[1]})'

# Aplatir d'un niveau
jq 'flatten(1)'

# Unique par champ
jq 'unique_by(.email)'

# Trier, dédoublonner et ré-indexer
jq '[.[] | .name] | unique | sort'

# walk : appliquer une transformation à chaque nœud récursivement
jq 'walk(if type == "string" then ascii_downcase else . end)'

# env : lire les variables d'environnement dans jq
export API_KEY=secret
jq -n 'env.API_KEY'

Bonnes pratiques

• Utilisez toujours -r (sortie brute) lorsque vous passez les résultats de jq à des variables shell ou à d'autres commandes pour supprimer les guillemets JSON
• Utilisez --arg / --argjson pour injecter les variables shell en toute sécurité — n'interpolez jamais directement les variables shell dans les chaînes de filtre
• Préférez map(f) à [.[] | f] pour la lisibilité
• Utilisez -c (compact) pour les pipelines JSON délimités par des sauts de ligne ; omettez-le pour un débogage lisible par l'humain
• Testez les filtres de manière interactive avec jq -n et une entrée littérale avant de les intégrer dans des scripts
• Utilisez empty pour supprimer les éléments indésirables plutôt que de les filtrer à null

Notes de sécurité

• jq est en lecture seule par conception — il ne peut pas écrire de fichiers ni exécuter de commandes
• Évitez d'intégrer directement des valeurs de champs JSON non fiables dans des commandes shell ; citez toujours ou utilisez --arg

Pièges courants

• Problème : jq affiche null au lieu de la valeur attendue Solution : Vérifiez les fautes de frappe dans les noms de clé ; utilisez keys pour inspecter les noms réels des champs. N'oubliez pas que JSON est sensible à la casse.

• Problème : Les nombres sont entre guillemets sous forme de chaînes dans la sortie Solution : Utilisez --argjson au lieu de --arg lors de l'injection de valeurs numériques.

• Problème : Le filtre fonctionne dans le terminal mais échoue dans un script Solution : Assurez-vous que la chaîne de filtre utilise des guillemets simples dans le shell pour empêcher l'expansion des variables. Exemple : jq '.field' et non jq ".field".

• Problème : add renvoie null sur un tableau vide Solution : Utilisez add // 0 ou add // "" pour fournir une valeur par défaut.

• Problème : Le streaming de gros fichiers est lent Solution : Utilisez jq --stream ou passez à jstream/gron pour les très gros fichiers.

Compétences associées

• @bash-pro — Encapsulation des appels jq dans des scripts shell robustes
• @bash-linux — Patrons généraux de pipeline shell
• @github-automation — Utilisation de jq avec la sortie JSON de GitHub CLI

Limitations

• N'utilisez ce skill que lorsque la tâche correspond clairement au champ d'application décrit ci-dessus.
• Ne considérez pas la sortie comme un substitut à une validation, un test ou une revue d'expert spécifique à l'environnement.
• Arrêtez-vous et demandez des éclaircissements si les entrées, autorisations, limites de sécurité ou critères de réussite requis sont manquants.