Maitriser la commande jq de A à Z

Mise à jour : 22/05/2025

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 :

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.
jq '.[]' Ce filtre dit à jq : “Parcours chaque élément du tableau”. Cela signifie que jq va traiter chaque utilisateur un par un.
| {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 ?

`jq` est un outil en ligne de commande puissant permettant de lire, filtrer, transformer et manipuler des données JSON. Il est particulièrement utile pour les développeurs et administrateurs qui manipulent des APIs ou des fichiers de configuration JSON en ligne de commande.

Comment lire un fichier JSON avec jq ?

Pour lire un fichier JSON avec jq, utilisez la commande `jq '.' fichier.json`. Le filtre `.` affiche tout le contenu JSON de manière indentée pour une meilleure lisibilité.

Comment utiliser jq avec une API ?

Vous pouvez combiner `curl` et `jq` pour interroger une API et formater sa réponse. Par exemple : `curl -s URL | jq '.'` permet d'afficher les données JSON retournées.

Comment extraire une clé imbriquée avec jq ?

Pour extraire une clé imbriquée, utilisez la notation par points. Exemple : `.address.city` extrait la ville d'un objet `address`.

Comment filtrer des données JSON avec jq ?

Utilisez la fonction `select` pour afficher uniquement les objets répondant à certains critères. Exemple : `select(.id > 5)` affiche les objets avec un identifiant supérieur à 5.

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

Utilisez la fonction `del` pour retirer un champ spécifique d’un objet JSON. Exemple : `del(.address)` supprime le champ `address`.

Comment renommer des champs avec jq ?

Vous pouvez construire un nouvel objet avec des clés renommées : `{identifiant: .id, nom: .name}`. Cela permet de personnaliser les noms des champs.

Comment ajouter un champ statique avec jq ?

Avec l’opérateur `+`, vous pouvez ajouter un champ fixe à tous les objets : `. + {statut: "actif"}` ajoute un champ `statut` avec la valeur `actif`.

Comment trier des objets JSON avec jq ?

Utilisez la fonction `sort_by` pour trier les objets selon une clé donnée : `sort_by(.name)` trie par nom.

Quelles sont les fonctions les plus utiles de jq ?

Parmi les fonctions utiles de jq, on trouve : `map`, `select`, `sort_by`, `length`, `ascii_upcase`, `contains`, `del`, `tostring`, `walk`, et `recurse`.