Cheat sheet

jq

JSON slicing, filtering, mapping, and kubectl output processing.

Basic filters

# Identity (pretty-print JSON)
cat file.json | jq '.'

# Access a field
jq '.name'

# Nested field
jq '.metadata.name'

# Array index
jq '.[0]'

# Array slice
jq '.[2:5]'

# All array elements
jq '.[]'

# Multiple fields (object construction)
jq '{name: .name, age: .age}'

Array operations

# Map over array
jq '[.[] | .name]'

# Filter array (select)
jq '[.[] | select(.status == "Running")]'

# Select with regex
jq '[.[] | select(.name | test("^web-"))]'

# Flatten nested array
jq '[.[] | .tags[]]'

# Sort by field
jq 'sort_by(.age)'

# Unique values
jq '[.[].status] | unique'

# Length of array
jq '.items | length'

# Group by field
jq 'group_by(.namespace)'

String & type operations

# String interpolation
jq '"Hello, \(.name)!"'

# Convert to string
jq '.port | tostring'

# Convert to number
jq '.replicas | tonumber'

# Keys of an object
jq 'keys'

# Values of an object (as array)
jq '[.[]]'

# Check if field exists
jq 'has("metadata")'

# Null-safe access
jq '.labels? // {}'

# Default value
jq '.timeout // 30'

kubectl + jq

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

# Get pod names and their node
kubectl get pods -o json \
  | jq -r '.items[] | "\(.metadata.name) -> \(.spec.nodeName)"'

# Get all non-running pods
kubectl get pods -A -o json \
  | jq -r '.items[] | select(.status.phase != "Running") | "\(.metadata.namespace)/\(.metadata.name)"'

# Get container image versions
kubectl get pods -o json \
  | jq -r '.items[].spec.containers[] | "\(.name): \(.image)"'

# Find pods with high restart count
kubectl get pods -A -o json \
  | jq -r '.items[] | select(.status.containerStatuses[]?.restartCount > 5) | .metadata.name'

Reduce & aggregation

# Sum values
jq '[.[].count] | add'

# Min / max
jq '[.[].cpu] | min'
jq '[.[].cpu] | max'

# Count items matching condition
jq '[.[] | select(.ready == true)] | length'

# Reduce with accumulator
jq 'reduce .[] as $item (0; . + $item.value)'

# Build lookup map from array
jq 'INDEX(.[]; .id)'

Output & scripting

# Raw string output (no quotes)
jq -r '.name'

# Compact output (no whitespace)
jq -c '.'

# Null input (generate data)
jq -n '{version: "1.0", env: "prod"}'

# Read from file
jq '.' config.json

# Multiple input files
jq -s '.[0] * .[1]' base.json override.json

# Tab-separated output
jq -r '[.name, .namespace, .status] | @tsv'

# CSV output
jq -r '[.name, .age] | @csv'

About the jq cheat sheet

jq is a small functional language rather than a flag-driven tool, and treating it as the latter is why it feels impenetrable at first. Everything is a filter that takes input and produces output, and the pipe composes them exactly as a shell pipe does.

Four constructs cover most real use. The identity and field access filters navigate structure, the array iterator flattens a list into a stream, select filters that stream by a condition, and map applies a filter to every element of an array. Almost every kubectl-processing one-liner you will write is a combination of those.

The distinction that trips people up is a stream of values versus an array of values. Iterating produces separate outputs; wrapping that in brackets collects them back into one array. Getting this wrong is why output sometimes appears as several documents when you wanted one, and it is the source of most confusing jq errors.

Frequently asked questions

How do I get plain strings without quotes?

Use raw output mode, which prints string results without JSON quoting. This is what you want when piping into another command or building a shell loop. Without it, every value arrives quoted and the next command receives literal quote characters as part of the argument.

How do I filter a kubectl list by a field?

Iterate the items array, then select on the condition you care about. The pattern is to iterate, select, then extract the fields you want. Remember that kubectl returns a List object, so the items live under a top-level items key rather than at the root.

Why does my filter return null?

The path does not exist in the input, and jq returns null rather than failing. Check the actual structure first by piping to keys at the level you are querying. Optional access with a question mark suppresses errors on missing paths, which is useful when processing heterogeneous documents where some lack a field.

How do I output CSV or TSV?

Build an array of the values you want per row, then pass it through the CSV or TSV filter, combined with raw output so the result is not JSON-quoted. This is the cleanest way to turn API output into something a spreadsheet or a shell loop can consume.

Should I use jq or kubectl's built-in output options?

Use custom columns or jsonpath for simple field extraction — no extra dependency and adequate for most listing. Reach for jq when you need real filtering, aggregation or reshaping, which jsonpath handles poorly. For scripts that must run anywhere, kubectl's built-in options avoid assuming jq is installed.