JQ Command in Linux with Examples

Introduction

jq is a lightweight and flexible command-line JSON processor.

jq is like sed for JSON data – you can use it to slice and filter and map and transform structured data with the same ease that sed, awk, grep and friends let you play with text.

Also jq written in portable C, and it has zero runtime dependencies. You can download a single binary, scp it to a far away machine of the same type, and expect it to work.

jq can mangle the data format that you have into the one that you want with very little effort, and the program to do so is often shorter and simpler than you’d expect.

In this article, we will learn to use the JQ command to manipulate and work with JSON data in a Linux shell.

Install the JQ command

The JQ command is not available in some Linux distributions by default; It needs to be downloaded into the system before it can be used . You can download the JQ command just like any other package on your system. On Ubuntu use the below-given command to install the JQ utility:

qadry@unixcop:~$ sudo apt install jq -y
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following package was automatically installed and is no longer required:
  libreoffice-help-common
Use 'sudo apt autoremove' to remove it.
The following additional packages will be installed:
  libjq1 libonig5
The following NEW packages will be installed:
  jq libjq1 libonig5
0 upgraded, 3 newly installed, 0 to remove and 240 not upgraded.
Need to get 313 kB of archives.
After this operation, 1062 kB of additional disk space will be used.
Get:1 http://us.archive.ubuntu.com/ubuntu focal/universe amd64 libonig5 amd64 6.9.4-1 [142 kB]
Get:2 http://us.archive.ubuntu.com/ubuntu focal-updates/universe amd64 libjq1 amd64 1.6-1ubuntu0.20.04.1 [121 kB]
Get:3 http://us.archive.ubuntu.com/ubuntu focal-updates/universe amd64 jq amd64 1.6-1ubuntu0.20.04.1 [50.2 kB]
Fetched 313 kB in 2s (128 kB/s)
Selecting previously unselected package libonig5:amd64.
(Reading database ... 196337 files and directories currently installed.)
Preparing to unpack .../libonig5_6.9.4-1_amd64.deb ...
Unpacking libonig5:amd64 (6.9.4-1) ...
Selecting previously unselected package libjq1:amd64.
Preparing to unpack .../libjq1_1.6-1ubuntu0.20.04.1_amd64.deb ...
Unpacking libjq1:amd64 (1.6-1ubuntu0.20.04.1) ...
Selecting previously unselected package jq.
Preparing to unpack .../jq_1.6-1ubuntu0.20.04.1_amd64.deb ...
Unpacking jq (1.6-1ubuntu0.20.04.1) ...
Setting up libonig5:amd64 (6.9.4-1) ...
Setting up libjq1:amd64 (1.6-1ubuntu0.20.04.1) ...
Setting up jq (1.6-1ubuntu0.20.04.1) ...
Processing triggers for man-db (2.9.1-1) ...

Processing triggers for libc-bin (2.31-0ubuntu9.2) ...#######################################################################################.........
qadry@unixcop:~$

And use this command below if you are running a distribution like CentOS 8 which already has JQ by default then you will get an output similar to this:

sudo dnf install jq 

Syntax

Let’s take a look at the syntax of the JQ command:

jq [options]  [file...]

jq [options] --args  [strings...]

jq [options] --jsonargs  [JSON_TEXTS...]

Organize JSON data using JQ command

JQ organize and prettify JSON data when printing it to standard output.

So In this example, we have a JSON file named unixcop.json and we need to output the data to the standard output:

qadry@unixcop:~$ cat unixcop.json 
{"product":{"name": "speaker","id": "123"}}
qadry@unixcop:~$ 

The data printed to the standard output using the cat command is unorganized and messy. We can organize this data by using the JQ command below

qadry@unixcop:~$ jq '.' unixcop.json
{
  "product": {
    "name": "speaker",
    "id": "123"
  }
}
qadry@unixcop:~$ 

Now the data has become a lot more organized and easier to understand.This filter is especially needed when accessing data from APIs; The data stored in APIs can be very unorganized and confusing.

Access a Property using JQ command

The .field filter along with the JQ command can_be used to access object property in the shell.

We can use the .field operator. E.g to access the product’s property we can use this command:

qadry@unixcop:~$ jq '.product' unixcop.json 
{
  "name": "speaker",
  "id": "123"
}
qadry@unixcop:~$ 

We can also access the items present within the property by using the .field operator. To access the name item in the product’s property we will use:

qadry@unixcop:~$ jq '.product.name' unixcop.json 
"speaker"
qadry@unixcop:~$ 

Access an Array Item using JQ command

We can also access and output the elements present within an array in a JSON file by using the .[] operator. For this example we are going to modify our JSON file so it looks like this:

qadry@unixcop:~$ cat unixcop.json 
[{"name": "TV","id": "213"},{"name": "speaker","id": "123"},{"name": "keyboard","id": "432"}]

qadry@unixcop:~$ jq '.[]' unixcop.json 
{
  "name": "TV",
  "id": "213"
}
{
  "name": "speaker",
  "id": "123"
}
{
  "name": "keyboard",
  "id": "432"
}
qadry@unixcop:~$ 

To output only the second array we can modify 1 in array operator to above-given command in the following way:

qadry@unixcop:~$ jq '.[1]' unixcop.json 
{
  "name": "speaker",
  "id": "123"
}
qadry@unixcop:~$ 

Note: the array starts at 0

If we want to access the name property in the third array then we will run the following command:

qadry@unixcop:~$ jq '.[2].name' unixcop.json 
"keyboard"
qadry@unixcop:~$ 

Also We can use .[3] to access the 4th array and we make sure that will be null.

qadry@unixcop:~$ jq '.[3].name' unixcop.json 
null
qadry@unixcop:~$ 

Also to access all the name properties inside arrays we can execute this command:

qadry@unixcop:~$ jq '.[].name' unixcop.json 
"TV"
"speaker"
"keyboard"
qadry@unixcop:~$ 

Conclusion

The JQ command is used to transform JSON data into a more readable format and print it to the standard output on Linux. The JQ command is built around filters which are used to find and print only the required data from a JSON file.