Cancel

JQ command in Linux

JQ is a CLI JSON parser with pretty prints and filters the results as JSON. So JSON stands for JavaScript Object Notation, and JQ stands for JSON Query.

If you don’t have JQ package installed in your system, then run the following commands to install JQ.

Linux (Debian, Ubuntu, Mint)

1
sudo apt install jq

MacOSx (don’t forget to install Homebrew if you don’t have one)

1
brew install --cask jq

Windows (don’t forget to install choco if you don’t have one)

1
choco install jq

Basic concepts

The syntax for JQ is pretty coherent.

Syntax Description
, Separated by a comma will produce multiple independent outputs
? Will ignores error if the type is unexpected
[] Array construction
{} Object construction
+ Concatenate or Add
- Difference of sets or Subtract
length Size of selected element
\| Pipes are used to chain commands in a similar fashion to bash

Mapping and Transforming

Description Command
jq 'sort' Sort an array of basic type
jq 'sort_by(.foo)' Sort an array of objects
jq 'group_by(.foo)' Group by a key - opposite to flatten
jq 'min' .See also min, max, min_by(path_exp), max_by(path_exp) Minimun value of an array
jq 'unique' or jq 'unique_by(.foo)' or jq 'unique_by(length)' Remove duplicates
jq 'reverse' Reverse an array

Demo filename.json file you to test the JQ command.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "slideshow": {
    "author": "Yafiz Abraham",
    "date": "date of publication",
    "slides": [
      {
        "title": "Abraham",
        "type": "Father"
      },
      {
        "title": "Overview",
        "type": "text"
      },
      {
        "title": "JSON Query",
        "type": "command"
      }
    ]
  }
}

You can download a file using the curl command. Click here to read another article. You have 3 options to run the JQ command.

1
2
3
4
5
6
7
8
# Options 1
jq '.' filename.json # read json from a filename.json

# Options 2
cat filename.json | jq '.' # alternative, by cat with jq

# Options 3
curl -s https://httpbin.org/json | jq '.' # Return specific value from API

In this is an article, I am going to use 1st option. You can choose whatever option you like.

Run the following command to get a single item.

1
jq '.slideshow | {author}' filename.json
  1. . notation is mandatory here.
  2. slideshow is the key from the object, aka methods chain.
  3. Get me an item called author from the given object.

Run the following command to get multiple items.

1
jq '.slideshow | {author,date}' filename.json
  1. , or comma will help you to find out multiple items from the given object.
  2. Get me author and date values from the given object.

The beauty of the JQ Parser command is, you can print all titles without using 4 loops.

1
jq '.slideshow.slides[] | {title}' filename.json

Let’s say you want to return items only, if title (key) contains Abraham (value), then the select function will check the condition for you, and will return only matched items.

1
jq '.slideshow.slides[] | select(.title | contains("Abraham"))' filename.json

Let’s say this time you want to delete an item from an array, then the del function will check the condition for you first and will remove an item only if matched from an array.

1
jq '.slideshow | del(.slides[] | select(.title == "Overview"))' filename.json

Now let’s double-check how many data types the JQ command supports. map is a function for looping and type is a variable to check data types, both are provided by the JQ command itself, which will check valid data types only.

1
echo '[true, null, 42, "hello", [], {}]' | jq 'map(type)'

This is how you can create a new object using JQ.

1
echo '{ "a": 1, "b": 2 }' | jq '.'

This is how you can insert a new item into an object using JQ.

1
echo '{ "a": 1, "b": 2 }' | jq '. + {"c": 3}'

And about delete, I have already told you above. To test queries live you can use jqplay.org.