Maitriser la commande jq de A à Z

jq est un outil en ligne de commande conçu pour lire, filtrer, transformer et manipuler des données au format JSON. Dans un monde où les APIs et les fichiers de configuration s’appuient massivement sur ce format, jq devient indispensable pour tout administrateur système ou développeur DevOps.

Son principal avantage ? Permettre des requêtes complexes sur des structures de données imbriquées, directement depuis un terminal, sans avoir à écrire de script en Python ou en JavaScript.

L’API utilisée dans ce guide

Pour illustrer chaque commande jq de manière concrète, nous allons utiliser l’API publique JSONPlaceholder. C’est une API gratuite qui simule les fonctionnalités d’un service REST, idéale pour s’exercer sans avoir à configurer un backend.

Pourquoi cette API ?

• Elle retourne des données JSON réalistes : utilisateurs, articles, commentaires, etc.
• Elle est accessible sans authentification.
• Les réponses sont structurées de manière cohérente, parfaites pour apprendre à manipuler des objets et tableaux JSON.

Nous nous appuierons notamment sur ces deux points d’entrée :

• https://jsonplaceholder.typicode.com/users : pour manipuler une liste d’utilisateurs.
• https://jsonplaceholder.typicode.com/posts : pour travailler avec des publications et filtrer les contenus.

Toutes les requêtes seront faites avec curl et traitées avec jq, directement en ligne de commande. Ainsi, tu pourras reproduire chaque commande sur ton propre terminal, sans installation complexe.

Syntaxe de base

jq s’utilise principalement de deux façons : en lisant un fichier JSON ou en traitant un flux de données en entrée standard (stdin). Ces deux méthodes sont interchangeables selon le contexte.

Lire un fichier JSON

La syntaxe classique consiste à passer un fichier JSON en argument :

jq '.' fichier.json

Ici, le filtre . signifie “affiche tout”. Cette commande affiche le contenu JSON avec une indentation propre, ce qui facilite la lecture.

Lire depuis l’entrée standard (stdin)

jq peut également lire directement depuis un flux, comme celui produit par une commande curl :

curl -s https://jsonplaceholder.typicode.com/users | jq '.'

[
  {
    "id": 1,
    "name": "Leanne Graham",
    "username": "Bret",
    "email": "Sincere@april.biz",
    "address": {
      "street": "Kulas Light",
      "suite": "Apt. 556",
      "city": "Gwenborough",
      "zipcode": "92998-3874",
      "geo": {
        "lat": "-37.3159",
        "lng": "81.1496"
      }
    },
    "phone": "1-770-736-8031 x56442",
    "website": "hildegard.org",
    "company": {
      "name": "Romaguera-Crona",
      "catchPhrase": "Multi-layered client-server neural-net",
      "bs": "harness real-time e-markets"
    }
  },
  ...
]

Dans ce cas, jq reçoit les données JSON via le pipe |, les interprète et les formate à l’écran.

Extraction de données spécifiques

Avec jq, tu peux extraire précisément les éléments qui t’intéressent dans une structure JSON. Voici comment faire à partir de l’API JSONPlaceholder, qui renvoie une liste d’utilisateurs.

Extraire une clé simple

Affichons tous les noms des utilisateurs :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[].name'
"Leanne Graham"
"Ervin Howell"
"Clementine Bauch"
"Patricia Lebsack"
"Chelsey Dietrich"
"Mrs. Dennis Schulist"
"Kurtis Weissnat"
"Nicholas Runolfsdottir V"
"Glenna Reichert"
"Clementina DuBuque"

Le filtre .[].name signifie : “dans chaque élément du tableau principal, affiche la clé name”.

Extraire plusieurs clés

Pour chaque utilisateur, on peut extraire plusieurs informations à la fois :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | {id: .id, nom: .name, email: .email}'
{
  "id": 1,
  "nom": "Leanne Graham",
  "email": "Sincere@april.biz"
}
{
  "id": 2,
  "nom": "Ervin Howell",
  "email": "Shanna@melissa.tv"
}
{
  "id": 3,
  "nom": "Clementine Bauch",
  "email": "Nathan@yesenia.net"
}
{
  "id": 4,
  "nom": "Patricia Lebsack",
  "email": "Julianne.OConner@kory.org"
}
{
  "id": 5,
  "nom": "Chelsey Dietrich",
  "email": "Lucio_Hettinger@annie.ca"
}
{
  "id": 6,
  "nom": "Mrs. Dennis Schulist",
  "email": "Karley_Dach@jasper.info"
}
{
  "id": 7,
  "nom": "Kurtis Weissnat",
  "email": "Telly.Hoeger@billy.biz"
}
{
  "id": 8,
  "nom": "Nicholas Runolfsdottir V",
  "email": "Sherwood@rosamond.me"
}
{
  "id": 9,
  "nom": "Glenna Reichert",
  "email": "Chaim_McDermott@dana.io"
}
{
  "id": 10,
  "nom": "Clementina DuBuque",
  "email": "Rey.Padberg@karina.biz"
}

Voici ce que fait en détail la commande :

1. curl -s https://jsonplaceholder.typicode.com/users Cette commande envoie une requête HTTP GET à l’API JSONPlaceholder. Le drapeau -s signifie “silent”, donc curl n’affiche pas la barre de progression. Le résultat est un tableau JSON contenant 10 utilisateurs.

2. jq '.[]' Ce filtre dit à jq : “Parcours chaque élément du tableau”. Cela signifie que jq va traiter chaque utilisateur un par un.

3. | {id: .id, nom: .name, email: .email} Pour chaque utilisateur, jq crée un nouvel objet JSON composé uniquement de trois clés :

   • id → la valeur du champ .id (identifiant de l’utilisateur)
   • nom → la valeur du champ .name
   • email → la valeur du champ .email

Ce type de transformation est parfait pour simplifier l’affichage, extraire des données ciblées, ou préparer une exportation vers un autre outil.

Extraire une clé imbriquée

Affichons le nom et la ville de chaque utilisateur :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | {nom: .name, ville: .address.city}'
{
  "nom": "Leanne Graham",
  "ville": "Gwenborough"
}
{
  "nom": "Ervin Howell",
  "ville": "Wisokyburgh"
}
{
  "nom": "Clementine Bauch",
  "ville": "McKenziehaven"
}
{
  "nom": "Patricia Lebsack",
  "ville": "South Elvis"
}
{
  "nom": "Chelsey Dietrich",
  "ville": "Roscoeview"
}
{
  "nom": "Mrs. Dennis Schulist",
  "ville": "South Christy"
}
{
  "nom": "Kurtis Weissnat",
  "ville": "Howemouth"
}
{
  "nom": "Nicholas Runolfsdottir V",
  "ville": "Aliyaview"
}
{
  "nom": "Glenna Reichert",
  "ville": "Bartholomebury"
}
{
  "nom": "Clementina DuBuque",
  "ville": "Lebsackbury"
}

.address.city permet d’accéder à une propriété imbriquée dans un objet "address".

Extraire un élément par son index

Pour obtenir les données du 3e utilisateur :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[2]'

{
  "id": 3,
  "name": "Clementine Bauch",
  "username": "Samantha",
  "email": "Nathan@yesenia.net",
  "address": {
    "street": "Douglas Extension",
    "suite": "Suite 847",
    "city": "McKenziehaven",
    "zipcode": "59590-4157",
    "geo": {
      "lat": "-68.6102",
      "lng": "-47.0653"
    }
  },
  "phone": "1-463-123-4447",
  "website": "ramiro.info",
  "company": {
    "name": "Romaguera-Jacobson",
    "catchPhrase": "Face to face bifurcated interface",
    "bs": "e-enable strategic applications"
  }
}

Les tableaux JSON commencent à l’index 0. .[2] cible donc le 3e élément.

Accès à un champ d’un élément spécifique

Extraire uniquement l’email du 5e utilisateur :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[4].email'

Tu peux combiner les index avec les noms de clés pour naviguer dans la structure.

Astuce pour les noms de champs avec des tirets

Si un champ contient un caractère spécial, utilise les guillemets doubles et l’opérateur . :

jq '."nom-du-champ"' fichier.json

Même si ce cas ne se produit pas dans JSONPlaceholder, il est bon à connaître pour d’autres API.

Filtres et transformations

Le point d’entrée https://jsonplaceholder.typicode.com/users retourne une liste de 10 utilisateurs, chacun avec des champs comme id, name, email, et un objet address contenant city, zipcode, etc. Voici comment transformer ces données avec jq.

Sélectionner certains utilisateurs avec select

Filtrons les utilisateurs vivant dans la ville de “McKenziehaven” :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | select(.address.city == "McKenziehaven")'

Le filtre select(.address.city == "McKenziehaven") affiche uniquement les utilisateurs correspondant à ce critère.

Supprimer un champ avec del

Retirons les adresses complètes des utilisateurs :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | del(.address)'

Cette commande supprime le champ address de chaque objet utilisateur.

Renommer et réorganiser les champs

Construisons une vue simplifiée avec des noms de champs personnalisés :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | {identifiant: .id, nom: .name, ville: .address.city}'

Ici, on crée un nouvel objet avec des clés renommées et un sous-champ extrait.

Ajouter un champ statique

Ajoutons une clé statut à tous les utilisateurs :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | . + {statut: "actif"}'

Chaque objet utilisateur contient maintenant une clé statut avec la valeur "actif".

Compter le nombre d’utilisateurs

Pour obtenir le total d’entrées dans la réponse JSON :

curl -s https://jsonplaceholder.typicode.com/users | jq 'length'

Le filtre length compte les objets du tableau.

Extraire un tableau de valeurs avec map

Récupérons une liste des emails :

curl -s https://jsonplaceholder.typicode.com/users | jq 'map(.email)'

Ce filtre renvoie un tableau contenant uniquement les adresses email des utilisateurs.

Utilisation avancée de jq

Une fois les bases maîtrisées, jq permet d’aller beaucoup plus loin grâce à des filtres avancés, des combinaisons logiques, et des fonctions intégrées. Voici quelques usages puissants, toujours avec le point d’entrée https://jsonplaceholder.typicode.com/users.

Combiner plusieurs conditions avec and / or

Filtrons les utilisateurs dont l’ID est supérieur à 5 et vivant dans la ville de “Howemouth” :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | select(.id > 5 and .address.city == "Howemouth")'

Avec and, jq évalue plusieurs conditions sur un même objet. On peut aussi utiliser or :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | select(.id < 3 or .address.city == "Lebsackbury")'

Appliquer une fonction à une chaîne ou un nombre

Obtenir tous les noms en majuscules :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | {nom_majuscule: (.name | ascii_upcase)}'

Ici, ascii_upcase convertit la valeur de .name en majuscules.

Filtrer sur une valeur contenue (avec contains)

Trouver les utilisateurs dont le nom contient “Glen” :

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | select(.name | contains("Glen"))'

contains est sensible à la casse. Pour ignorer la casse, on peut combiner avec ascii_downcase :

curl -s https://jsonplaceholder.typicode.com/users |  jq '.[] | select((.name | ascii_downcase) | contains("glen"))'

Trier les données (tri local)

On peut trier les utilisateurs par nom :

curl -s https://jsonplaceholder.typicode.com/users | jq 'sort_by(.name)[] | {id, nom: .name}'

sort_by(.name) trie le tableau par ordre alphabétique selon .name.

Liste des Fonctions intégrées

jq propose une riche collection de fonctions intégrées pour manipuler des données JSON en ligne de commande. Ces fonctions couvrent des opérations sur les chaînes, les tableaux, les objets, les nombres, les types, et bien plus encore. Voici un aperçu des principales catégories de fonctions disponibles :

Fonctions sur les chaînes de caractères

• length : Renvoie la longueur d’une chaîne.
• ascii_upcase / ascii_downcase : Convertit une chaîne en majuscules ou minuscules.
• split / join : Divise une chaîne en tableau ou joint un tableau en chaîne.
• startswith / endswith : Vérifie si une chaîne commence ou se termine par une sous-chaîne donnée.
• contains : Vérifie si une chaîne contient une sous-chaîne spécifique.

Fonctions sur les tableaux

• map : Applique une transformation à chaque élément d’un tableau.
• select : Filtre les éléments d’un tableau selon une condition.
• add : Additionne les éléments d’un tableau numérique.
• sort / sort_by : Trie les éléments d’un tableau.
• unique / unique_by : Supprime les doublons dans un tableau.
• reverse : Inverse l’ordre des éléments d’un tableau.

Fonctions sur les objets

• keys : Renvoie les clés d’un objet.
• has : Vérifie la présence d’une clé dans un objet.
• del : Supprime une clé d’un objet.
• to_entries / from_entries : Convertit un objet en tableau de paires clé/valeur et inversement.
• with_entries : Transforme les paires clé/valeur d’un objet

Fonctions mathématiques

• floor / ceil / round : Arrondit un nombre vers le bas, le haut ou à l’entier le plus proche.
• sqrt : Calcule la racine carrée d’un nombre.
• tonumber : Convertit une chaîne en nombre.

Fonctions de type et de conversion

• type : Renvoie le type JSON d’une valeur (string, number, object, etc.).
• tostring : Convertit une valeur en chaîne de caractères.
• isfinite / isnan / isinfinite : Vérifie les propriétés d’un nombre.

Fonctions de parcours et de récursion

• recurse : Parcourt récursivement une structure JSON.
• walk : Applique une fonction à chaque élément d’une structure JSON.
• paths / getpath / setpath : Travaille avec les chemins dans une structure JSON.

Fonctions de contrôle de flux

• if / then / else / end : Structure conditionnelle.
• try / catch : Gestion des erreurs.
• empty : Ne produit aucune sortie, utile pour filtrer des éléments.

Fonctions diverses

• range : Génère une séquence de nombres.
• error : Génère une erreur personnalisée.
• input / inputs : Lit des entrées supplémentaires.

Pour une liste complète et détaillée des fonctions intégrées de jq, consulte la documentation officielle : https://jqlang.org/manual/

Voici alors des exemples concrets inédits de fonctions intégrées avancées de jq, toujours à partir de l’endpoint https://jsonplaceholder.typicode.com/users, et non couvertes précédemment :

Quelques exemples avancés

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | {id_texte: (.id | tostring)}'

→ Convertit le champ numérique id en texte, utile pour concaténations ou formats spécifiques.

curl -s https://jsonplaceholder.typicode.com/users | jq '.[] | {nom: (.name | type), adresse: (.address | type)}'

→ Affiche les types de données (string, object, etc.) pour des champs donnés.

curl -s https://jsonplaceholder.typicode.com/users | jq '.[0] | with_entries(.key |= ascii_upcase)'

→ Met en majuscules toutes les clés du premier utilisateur.

curl -s https://jsonplaceholder.typicode.com/users | jq '.[0] | to_entries | map(.key += "_mod") | from_entries'

→ Renomme toutes les clés du premier utilisateur en ajoutant un suffixe _mod.

curl -s https://jsonplaceholder.typicode.com/users | jq '.[0] | recurse(.[]? | select(type == "object"))'

→ Explore récursivement toutes les clés imbriquées du premier utilisateur.

curl -s https://jsonplaceholder.typicode.com/users | jq '.[0] | walk(if type == "string" then ascii_downcase else . end)'

→ Met en minuscules toutes les chaînes de caractères du premier utilisateur, quelle que soit leur profondeur.

Conclusion

À travers ce guide, tu as appris à manipuler les données JSON en ligne de commande avec jq, depuis les bases jusqu’aux transformations complexes. Grâce à cette maîtrise, tu peux maintenant intégrer jq dans tes scripts d’automatisation, que ce soit pour :

• Extraire des métriques de réponse API,
• Nettoyer des données JSON pour des dashboards ou du monitoring,
• Convertir des objets complexes en formats simplifiés pour des outils CLI ou des pipelines CI/CD.

jq est compact, rapide, sans dépendance, et surtout puissant : c’est un outil incontournable pour tout administrateur système, développeur ou DevOps travaillant avec des flux JSON.

Liens utiles

• Documentation officielle de jq
• jqlang : Utilise jq en ligne pour tester tes commandes.

FAQ - Questions Fréquemment Posées

À quoi sert la commande jq ?

Comment lire un fichier JSON avec jq ?

Comment utiliser jq avec une API ?

Comment extraire une clé imbriquée avec jq ?

Comment filtrer des données JSON avec jq ?

Comment supprimer un champ d’un objet JSON avec jq ?

Comment renommer des champs avec jq ?

Comment ajouter un champ statique avec jq ?

Comment trier des objets JSON avec jq ?

Quelles sont les fonctions les plus utiles de jq ?

×

📖 Voir la documentation →