The Ultimate JQ Cheat Sheet - Comprehensive guide to jq command-line JSON processor

jq-cheatsheet.md

🔧 The Ultimate JQ Cheat Sheet

jq — lightweight, flexible command-line JSON processor

📋 Table of Contents

• Basics
• Navigation
• Arrays
• Objects
• Filtering & Selection
• Transformation
• String Operations
• Math & Aggregation
• Conditionals
• Advanced
• Real-World Examples

---

Basics

# Pretty print JSON
cat file.json | jq '.'

# Compact output (single line)
jq -c '.' file.json

# Raw output (no quotes on strings)
jq -r '.name' file.json

# Read from string
echo '{"a":1}' | jq '.a'

# Null input (create JSON from scratch)
jq -n '{name: "test", value: 42}'

---

Navigation

# Get a field
jq '.name'                          # → "John"

# Nested field
jq '.address.city'                  # → "New York"

# Optional field (no error if missing)
jq '.missing?'                      # → null

# Multiple fields
jq '.name, .age'                    # → "John" \n 30

# Pipe through filters
jq '.address | .city'               # → "New York"

---

Arrays

# First element
jq '.[0]'                           # → first item

# Last element
jq '.[-1]'                          # → last item

# Slice
jq '.[2:5]'                         # → elements 2,3,4

# All elements (iterate)
jq '.[]'                            # → each element

# Collect into array
jq '[.[] | .name]'                  # → ["a","b","c"]

# Length
jq 'length'                         # → 5

# First / Last
jq 'first'                          # → first element
jq 'last'                           # → last element

# Reverse
jq 'reverse'                        # → [3,2,1]

# Flatten
jq 'flatten'                        # → [1,2,3,4]

# Unique values
jq 'unique'                         # → deduplicated

# Sort
jq 'sort'                           # → sorted array
jq 'sort_by(.name)'                 # → sorted by field

# Range
jq -n '[range(5)]'                  # → [0,1,2,3,4]

---

Objects

# Get all keys
jq 'keys'                           # → ["a","b","c"]

# Get all values
jq 'values'                         # → [1,2,3]

# Check if key exists
jq 'has("name")'                    # → true/false

# Add/update field
jq '. + {newfield: "value"}'        # → merged object
jq '.name = "Jane"'                 # → update in place

# Delete field
jq 'del(.unwanted)'                 # → without field

# Rename key
jq '.newname = .oldname | del(.oldname)'

# Convert to entries
jq 'to_entries'                     # → [{key,value},...]

# Convert from entries
jq 'from_entries'                   # → {key: value, ...}

# Transform entries
jq 'with_entries(.value += 10)'     # → modify all values

---

Filtering & Selection

# Select by condition
jq '.[] | select(.age > 21)'

# Select by field value
jq '.[] | select(.role == "admin")'

# Select non-null
jq '.[] | select(.email != null)'

# Select by type
jq '.. | numbers'                   # → all numbers
jq '.. | strings'                   # → all strings
jq '.. | booleans'                  # → all booleans
jq '.. | arrays'                    # → all arrays
jq '.. | objects'                   # → all objects

# Map with filter
jq 'map(select(.active == true))'

# Contains
jq 'select(.tags | contains(["admin"]))'

# Inside (inverse of contains)
jq 'select(.role | inside("admin user"))'

# Test with regex
jq 'select(.email | test("@gmail"))'

# Limit results
jq '.[:5]'                          # → first 5
jq 'limit(5; .[])'                  # → first 5 iterated

---

Transformation

# Map over array
jq 'map(.name)'                     # → extract field
jq 'map(. * 2)'                     # → transform each

# Create new object
jq '{username: .name, mail: .email}'

# Construct array
jq '[.users[].name]'

# Group by field
jq 'group_by(.category)'            # → [[...],[...]]

# Index by field
jq 'INDEX(.id)'                     # → {id: obj, ...}

# Transpose
jq 'transpose'                      # → pivot array

# Add to array
jq '. += ["new"]'                   # → append

# Combine arrays
jq '. + ["extra"]'                  # → concatenate

---

String Operations

# Uppercase / Lowercase
jq '.name | ascii_upcase'           # → "JOHN"
jq '.name | ascii_downcase'         # → "john"

# String length
jq '.name | length'                 # → 4

# Split string
jq '.csv | split(",")'              # → ["a","b","c"]

# Join array to string
jq '.tags | join(", ")'             # → "a, b, c"

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

# Replace (regex)
jq '.text | gsub("old"; "new")'

# Trim whitespace
jq '.text | ltrimstr(" ") | rtrimstr(" ")'

# Starts/ends with
jq 'select(.url | startswith("https"))'
jq 'select(.file | endswith(".json"))'

# Match regex
jq '.text | match("[0-9]+")'        # → match object
jq '.text | capture("(?<num>[0-9]+)")' # → named groups

---

Math & Aggregation

# Sum array
jq 'add'                            # → sum of array
jq '[.[].price] | add'              # → sum field

# Average
jq 'add / length'                   # → average

# Min / Max
jq 'min'                            # → smallest
jq 'max'                            # → largest
jq 'min_by(.price)'                 # → object with min
jq 'max_by(.score)'                 # → object with max

# Count
jq 'length'                         # → count items
jq '[.[] | select(.active)] | length'  # → count filtered

# Floor / Ceil / Round
jq '.price | floor'
jq '.price | ceil'  
jq '.price | round'

# Absolute value
jq '.delta | fabs'

# Math operations
jq '.a + .b'                        # add
jq '.a - .b'                        # subtract
jq '.a * .b'                        # multiply
jq '.a / .b'                        # divide
jq '.a % .b'                        # modulo

---

Conditionals

# If-then-else
jq 'if .age > 18 then "adult" else "minor" end'

# Alternative operator (default value)
jq '.missing // "default"'          # → "default" if null

# Error suppression
jq '.field?'                        # → null if missing

# Not
jq 'select(.active | not)'          # → where not active

# And / Or
jq 'select(.a and .b)'
jq 'select(.a or .b)'

# Empty (skip output)
jq 'if .hide then empty else . end'

# Try-catch
jq 'try .bad.path catch "error"'

---

Advanced

# Recursive descent
jq '.. | .id? // empty'             # → all id fields

# Walk and transform
jq 'walk(if type == "string" then ascii_upcase else . end)'

# Reduce
jq 'reduce .[] as $x (0; . + $x)'   # → sum

# Define variables
jq '.price as $p | .qty * $p'

# Define functions
jq 'def double: . * 2; [.[] | double]'

# Path expressions
jq 'path(.a.b)'                     # → ["a","b"]
jq 'getpath(["a","b"])'             # → value at path
jq 'setpath(["a","b"]; 42)'         # → set value

# Env variables
jq -n 'env.HOME'                    # → /home/user

# Input/Inputs (multiple JSON docs)
jq -s '.'                           # → slurp into array
jq -n '[inputs]'                    # → stream to array

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

# Format as TSV
jq -r '.[] | [.name, .age] | @tsv'

# Base64
jq '.data | @base64'                # → encode
jq '.encoded | @base64d'            # → decode

# URI encode
jq '.query | @uri'

# JSON stringify
jq '. | @json'                      # → escaped JSON string

# Dates
jq '.timestamp | todate'            # → ISO date string
jq '"2024-01-01T00:00:00Z" | fromdateiso8601'  # → epoch
jq 'now | todate'                   # → current time

---

Real-World Examples

API Response Processing

# Extract data from paginated API
curl -s 'https://api.example.com/users' | \
  jq '.data[] | {id, name, email}'

# Get specific fields as CSV
curl -s 'https://api.example.com/users' | \
  jq -r '.data[] | [.id, .name, .email] | @csv'

Log Analysis

# Parse JSON logs, filter errors
cat app.log | jq -c 'select(.level == "error")'

# Count errors by type
cat app.log | jq -s 'group_by(.error_type) | 
  map({type: .[0].error_type, count: length})'

# Get last 10 errors
cat app.log | jq -s '[ .[] | select(.level == "error") ] | .[-10:]'

Config Manipulation

# Update config value
jq '.database.host = "newhost"' config.json > config.new.json

# Merge configs
jq -s '.[0] * .[1]' defaults.json overrides.json

# Remove sensitive fields before commit
jq 'del(.password, .api_key, .secret)' config.json

Data Transformation

# Convert array to lookup object
jq 'INDEX(.id)'

# Pivot data
jq 'group_by(.category) | 
  map({category: .[0].category, items: map(.name)})'

# Flatten nested structure
jq '[.. | objects | select(has("value")) | .value]'

Kubernetes / Docker

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

# Get container images
kubectl get pods -o json | jq -r '.items[].spec.containers[].image' | sort -u

# Docker inspect - get IP
docker inspect container_id | jq -r '.[0].NetworkSettings.IPAddress'

AWS CLI

# List EC2 instance IDs and states
aws ec2 describe-instances | \
  jq -r '.Reservations[].Instances[] | [.InstanceId, .State.Name] | @tsv'

# Get S3 bucket sizes
aws s3api list-buckets | jq -r '.Buckets[].Name'

---

CLI Flags Reference

Flag	Description
-r	Raw output (no JSON quotes)
-c	Compact output
-s	Slurp (read all inputs into array)
-n	Null input (don't read stdin)
-e	Exit with error if result is null/false
-S	Sort keys
-C	Colorize output
-M	Monochrome output
-f	Read filter from file
--arg name val	Pass string variable
--argjson name val	Pass JSON variable
--slurpfile var file	Load file into variable

---

Quick Reference Card

Task	Command
Pretty print	jq '.'
Get field	jq '.field'
Get nested	jq '.a.b.c'
Array element	jq '.[0]'
All elements	jq '.[]'
Filter	jq '.[] | select(.x > 5)'
Map	jq 'map(.field)'
Keys	jq 'keys'
Length	jq 'length'
Sort	jq 'sort_by(.field)'
Unique	jq 'unique'
Group	jq 'group_by(.field)'
Sum	jq 'add'
Default	jq '.x // "default"'
Delete	jq 'del(.field)'
Merge	jq '. + {new: 1}'
To CSV	jq -r '@csv'

---

Version: jq 1.6+ | License: MIT | More: https://jqlang.github.io/jq/manual/