jq & yq

Command-line JSON and YAML processing.

jq Basics

Extract Values

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

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

# Array element
echo '[1,2,3]' | jq '.[0]'
# 1

# Multiple fields
echo '{"a":1,"b":2,"c":3}' | jq '{a,b}'
# {"a":1,"b":2}

Array Operations

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

# Filter array
echo '[1,2,3,4,5]' | jq '[.[] | select(. > 2)]'
# [3,4,5]

# Map
echo '[1,2,3]' | jq '[.[] * 2]'
# [2,4,6]

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

# First/last
echo '[1,2,3]' | jq 'first'
echo '[1,2,3]' | jq 'last'

Object Arrays

# Extract field from each
echo '[{"name":"a"},{"name":"b"}]' | jq '.[].name'

# Filter objects
echo '[{"age":20},{"age":30}]' | jq '[.[] | select(.age > 25)]'

# Sort
echo '[{"a":2},{"a":1}]' | jq 'sort_by(.a)'

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

Transform

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

# Add field
echo '{"a":1}' | jq '. + {b:2}'

# Delete field
echo '{"a":1,"b":2}' | jq 'del(.b)'

# Rename key
echo '{"old":1}' | jq '{new: .old}'

Conditionals

# If-then-else
echo '{"age":20}' | jq 'if .age >= 18 then "adult" else "minor" end'

# Null handling
echo '{"a":null}' | jq '.a // "default"'

Raw Output

# No quotes
echo '{"name":"John"}' | jq -r '.name'
# John

# Compact output
echo '{"a":1}' | jq -c '.'
# {"a":1}

yq Basics

YAML Operations

# Read value
yq '.name' file.yaml

# Update value
yq -i '.version = "2.0"' file.yaml

# Add field
yq -i '.new_field = "value"' file.yaml

# Delete field
yq -i 'del(.unwanted)' file.yaml

Convert Formats

# YAML to JSON
yq -o=json file.yaml

# JSON to YAML
yq -P file.json

# YAML to XML
yq -o=xml file.yaml

Multiple Documents

# Select document
yq 'select(documentIndex == 0)' multi.yaml

# Evaluate all docs
yq ea '. as $item ireduce ([]; . + [$item])' multi.yaml

Common Patterns

API Response Processing

# Get specific fields from API
curl -s api.example.com/users | jq '.data[] | {id, name, email}'

# Count results
curl -s api.example.com/items | jq '.results | length'

# Filter and format
curl -s api.example.com/posts | jq -r '.[] | "\(.id): \(.title)"'

Config File Manipulation

# Update version in package.json
jq '.version = "1.2.3"' package.json > tmp && mv tmp package.json

# Add script
jq '.scripts.test = "jest"' package.json | sponge package.json

# Merge configs
jq -s '.[0] * .[1]' base.json override.json

Kubernetes/Helm

# Get pod names
kubectl get pods -o json | jq -r '.items[].metadata.name'

# Filter by status
kubectl get pods -o json | jq '.items[] | select(.status.phase=="Running")'

# Update YAML manifest
yq -i '.spec.replicas = 3' deployment.yaml

Reference

For advanced jq filters and recipes:

references/recipes.md