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
-
.
notation is mandatory here. -
slideshow
is the key from the object, aka methods chain. - 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
-
,
orcomma
will help you to find out multiple items from the given object. - Get me
author
anddate
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.