Skip to content

Drill: jq Recipes for JSON Processing

Goal

Use jq to select, filter, map, and transform JSON output from APIs and Kubernetes commands.

Setup

  • Install jq (apt install jq or yum install jq)
  • JSON data to process (API responses, kubectl output, config files)

Commands

Pretty-print JSON:

echo '{"name":"nginx","replicas":3}' | jq .

Extract a field:

echo '{"name":"nginx","replicas":3}' | jq '.name'

Extract from an array:

echo '[{"name":"a","status":"running"},{"name":"b","status":"failed"}]' | jq '.[0].name'

Select/filter array elements:

echo '[{"name":"a","status":"running"},{"name":"b","status":"failed"}]' | jq '.[] | select(.status == "failed")'

Map over an array to extract fields:

echo '[{"name":"a","cpu":2},{"name":"b","cpu":4}]' | jq '[.[] | {name, cpu}]'

Use with kubectl:

kubectl get pods -o json | jq '.items[] | {name: .metadata.name, status: .status.phase}'

Filter pods by status:

kubectl get pods -o json | jq '.items[] | select(.status.phase != "Running") | .metadata.name'

Count items:

kubectl get pods -o json | jq '.items | length'

Construct new JSON:

echo '{"first":"John","last":"Doe"}' | jq '{fullName: (.first + " " + .last)}'

Handle null values:

echo '{"a":1,"b":null}' | jq '.b // "default"'

Raw string output (no quotes):

echo '{"name":"nginx"}' | jq -r '.name'

Sort and group:

kubectl get pods -o json | jq '[.items[] | .status.phase] | group_by(.) | map({state: .[0], count: length})'

What to Look For

  • .[] iterates over array elements; .field accesses object fields
  • select() filters; map() transforms; group_by() aggregates
  • -r gives raw strings without JSON quoting (useful for shell variables)
  • // provides a default value when a field is null

Common Mistakes

  • Forgetting -r and getting quoted strings in shell variables
  • Using .[] on an object (iterates values) when you meant .keys[]
  • Not wrapping filter output in [] when you need the result as an array
  • Forgetting that jq expressions are single-quoted to prevent shell interpolation

Cleanup

No cleanup needed. jq processes stdin/files without modification.