tech
Defaultdeesfrzh

jq

Command-line JSON processor - parse, filter, transform JSON data in shell scripts and pipelines

TL;DR

What: Lightweight command-line JSON processor.

Why: Parse, filter, transform JSON, scriptable, pipe-friendly.

Quick Start

Install:

# macOS
brew install jq

# Ubuntu/Debian
sudo apt install jq

# Check version
jq --version

Basic usage:

# Pretty print
echo '{"name":"John"}' | jq '.'

# Get field
echo '{"name":"John"}' | jq '.name'

# From file
jq '.' data.json

Cheatsheet

FilterDescription
.Identity (whole input)
.fieldGet field
.[]Iterate array
.[0]Array index
``
select()Filter items
map()Transform items

Gotchas

Basic selection

# Sample JSON
echo '{"user":{"name":"John","age":30}}' | jq '.'

# Get nested field
echo '{"user":{"name":"John"}}' | jq '.user.name'
# Output: "John"

# Get raw string (no quotes)
echo '{"name":"John"}' | jq -r '.name'
# Output: John

# Multiple fields
echo '{"name":"John","age":30}' | jq '.name, .age'

Arrays

# Sample array
echo '[1,2,3,4,5]' | jq '.'

# Get all elements
echo '[1,2,3]' | jq '.[]'

# Get by index
echo '["a","b","c"]' | jq '.[1]'
# Output: "b"

# Slice
echo '[1,2,3,4,5]' | jq '.[2:4]'
# Output: [3,4]

# Array length
echo '[1,2,3]' | jq 'length'

Objects in arrays

# Sample data
DATA='[{"name":"John","age":30},{"name":"Jane","age":25}]'

# Get all names
echo $DATA | jq '.[].name'

# Get first item
echo $DATA | jq '.[0]'

# Map to new structure
echo $DATA | jq 'map({n: .name, a: .age})'

Filtering

# Select items
echo '[1,2,3,4,5]' | jq 'map(select(. > 2))'
# Output: [3,4,5]

# Filter objects
DATA='[{"name":"John","age":30},{"name":"Jane","age":25}]'
echo $DATA | jq '.[] | select(.age > 26)'

# Multiple conditions
echo $DATA | jq '.[] | select(.age > 20 and .name == "John")'

Transformation

# Map values
echo '[1,2,3]' | jq 'map(. * 2)'
# Output: [2,4,6]

# Add field
echo '{"name":"John"}' | jq '. + {age: 30}'

# Update field
echo '{"count":1}' | jq '.count += 1'

# Delete field
echo '{"name":"John","age":30}' | jq 'del(.age)'

# Construct new object
echo '{"first":"John","last":"Doe"}' | jq '{fullName: "\(.first) \(.last)"}'

Practical examples

# Parse API response
curl -s https://api.github.com/users/octocat | jq '{name, company, location}'

# Count items
cat data.json | jq 'length'

# Sum values
echo '[{"price":10},{"price":20}]' | jq '[.[].price] | add'

# Group by field
echo '[{"type":"a"},{"type":"b"},{"type":"a"}]' | jq 'group_by(.type)'

# Sort
echo '[3,1,2]' | jq 'sort'
echo '[{"name":"B"},{"name":"A"}]' | jq 'sort_by(.name)'

Next Steps