jq-yq

name	jq-yq
description	JSON and YAML manipulation with jq and yq command-line tools. Use when user asks to "parse JSON", "transform YAML", "extract from JSON", "filter JSON array", "convert YAML to JSON", "query JSON", or manipulate structured data from command line.

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