jq Practical Guide — JSON Parsing, Filtering, and Transformation

sudo apt install -y jq        # Ubuntu / Debian
sudo yum install -y jq        # CentOS / RHEL
brew install jq               # macOS

jq --version

# . : pretty-print the input as-is
echo '{"name":"Alice","age":30}' | jq '.'

# Read from a file
jq '.' data.json

# Extract a specific field
echo '{"name":"Alice","age":30}' | jq '.name'
# "Alice"

# Raw string only (no quotes)
jq -r '.name' data.json

# Iterate over the entire array
echo '[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]' | jq '.[]'

# Specific index
jq '.[0]' array.json
jq '.[-1]' array.json         # last

# Extract a specific field only
jq '.[].name' array.json

# Array length
jq 'length' array.json

# Slice
jq '.[2:5]' array.json

# Only items matching a condition
jq '.[] | select(.age > 25)' users.json

# Multiple conditions
jq '.[] | select(.age > 20 and .active == true)' users.json

# Match a specific value
jq '.[] | select(.role == "admin")' users.json

# Remove nulls
jq '.[] | select(.email != null)' users.json

# Transform everything with map
jq 'map(.age += 1)' users.json

# Select fields and build a new object
jq '.[] | {id, name, email: .contact.email}' users.json

# Convert to key-value pairs
echo '{"a":1,"b":2}' | jq 'to_entries'
# [{"key":"a","value":1},{"key":"b","value":2}]

# Rename keys
jq '[.[] | {userId: .id, userName: .name}]' users.json

# Parse a curl API response
curl -s https://api.github.com/repos/nodejs/node/releases   | jq -r '.[0] | "version: (.tag_name)  date: (.published_at)"'

# Parse AWS CLI JSON
aws ec2 describe-instances   | jq -r '.Reservations[].Instances[] | "(.InstanceId) (.State.Name) (.PublicIpAddress // "N/A")"'

# Docker inspect
docker inspect mycontainer | jq '.[0].NetworkSettings.IPAddress'

# Convert JSON to CSV
jq -r '.[] | [.id, .name, .email] | @csv' users.json

# Merge multiple JSON files
jq -s '.[0] * .[1]' base.json override.json

# Default values for empty fields
jq '.users[] | .nickname // "anonymous"' data.json

# Number formatting
jq '.[] | .price | tostring + " won"' products.json

# Only items that have a given key
jq '.[] | select(has("email"))' users.json

# Safe nested field access (null if missing)
jq '.user?.address?.city // "unknown"' data.json

# Define a variable
jq --arg name "Alice" '.[] | select(.name == $name)' users.json

# Numeric variable
jq --argjson min 25 '.[] | select(.age >= $min)' users.json

# if-then-else
jq '.[] | if .age >= 18 then .name + " (adult)" else .name + " (minor)" end' users.json