3 min to read

What is jq?

Learn how to use jq command effectively for JSON processing

Featured image


Overview

As working with JSON data becomes increasingly common, there’s a need for tools that can process JSON directly from the command line. jq has become an essential utility for handling JSON-formatted data across various systems.

What is jq?

jq is a lightweight command-line JSON processor. It can filter, map, transform, and manipulate JSON data with ease, making it an indispensable tool for data processing tasks.


Installation Methods

1️⃣ Using Package Managers

# apt
sudo apt-get update
sudo apt-get install jq

# apt (specific version)
sudo apt-get install jq=1.5*

# yum
sudo yum install jq

# yum (specific version)
sudo yum install jq-1.5

# dnf
sudo dnf install jq

2️⃣ From Source Code

# Latest version
git clone https://github.com/stedolan/jq.git
cd jq
autoreconf -i
./configure
make
sudo make install

# Specific version
git clone https://github.com/stedolan/jq.git
cd jq
git checkout jq-1.5
autoreconf -i
./configure
make
sudo make install


🛠️ Basic Usage

1️⃣ Simple Element Extraction

# Output single element
echo '{"name": "Somaz", "age": 31}' | jq '.name'
# Output
"Somaz"

# Output entire object
echo '{"name": "Somaz", "age": 31}' | jq '.'
# Output
{
  "name": "Somaz",
  "age": 31
}

2️⃣ Filtering

# Filter by condition
echo '[{"name": "Somaz", "age": 31}, {"name": "Oh9Lee", "age": 28}]' | jq '.[] | select(.age < 30)'
# Output
{
  "name": "Oh9Lee",
  "age": 28
}

# Filter by pattern matching
echo '[{"name": "Oh9Lee", "face": "squid"}, {"name": "Oh9Lee", "face": "cuttlefish"}]' | jq '.[] | select(.face | test("^squid"))'
# Output
{
  "name": "Oh9Lee",
  "face": "squid"
}


🚄 Advanced Usage

1️⃣ Mapping and Transformation

echo '[{"name": "Somaz", "age": 31}, {"name": "Oh9Lee", "age": 28}]' | jq '.[] | {personName: .name, yearOfBirth: (2024 - .age + 1)}'
# Output
{
  "personName": "Somaz",
  "yearOfBirth": 1994
}
{
  "personName": "Oh9Lee",
  "yearOfBirth": 1997
}

2️⃣ Conditional Output

echo '[{"name": "Somaz", "age": 31}, {"name": "Oh9Lee", "age": 28}]' | jq 'map(if .age > 30 then .name else empty end)'
# Output
[
  "Somaz"
]


⚙️ Useful Options

1️⃣ Raw Output (-r)

Remove quotes from the output.

echo '{"name": "Somaz", "age": 31}' | jq -r '.name'
# Output
Somaz

2️⃣ Compact Output (-c)

Output in a compact format.

echo '[{"name": "Somaz", "age": 31}, {"name": "Oh9Lee", "age": 25}]' | jq -c '.[]'
# Output
{"name":"Somaz","age":31}
{"name":"Oh9Lee","age":25}

3️⃣ Using Arguments (–arg)

Pass arguments to jq.

# Create data.json
cat <<EOF > data.json
[
  {"name": "Somaz", "age": 31},
  {"name": "Jane", "age": 25},
  {"name": "Doe", "age": 22},
  {"name": "John", "age": 45}
]
EOF

jq --arg name "Somaz" '.[] | select(.name == $name)' data.json
# Output
{
  "name": "Somaz",
  "age": 31
}


Reference