jq Mastery

jq is the SQL of JSON. Master it and you control every API, every config file, every data pipeline in your infrastructure.

Why jq Matters

Every modern tool outputs JSON:

  • APIs (REST, GraphQL) → JSON

  • CLIs (kubectl, gh, glab, vault) → JSON

  • Config files (package.json, terraform state) → JSON

  • Logs (structured logging) → JSON

Without jq, you’re stuck with grep and awk hacks. With jq, you have a real query language.

Learning Path

Document Focus Skill Level

Core Reference

Syntax, operators, patterns, yq for YAML

Foundation

Security Scanning

Dependabot, GitLab vulns, CVE analysis

Practical

Git Forge CLIs

gh, glab, tea - repo management at scale

Practical

Kubernetes

kubectl JSON mastery, resource analysis

Intermediate

Infrastructure APIs

ISE, pfSense, Vault, WLC via netapi

Intermediate

Data Transformation

Pivoting, time series, set operations

Advanced

The Mental Model

Think of jq like SQL:

SQL jq What It Does

SELECT *

.[]

Iterate all items

WHERE x = 'y'

select(.x == "y")

Filter

SELECT a, b

{a, b}

Project fields

ORDER BY x

sort_by(.x)

Sort

GROUP BY x

group_by(.x)

Group

COUNT(*)

length

Count

Quick Wins (Copy These Now)

Explore Unknown JSON

# What type is the root?
cat data.json | jq 'type'

# What keys exist?
cat data.json | jq 'keys'

# Keys with their types (THE pattern)
cat data.json | jq -r 'to_entries[] | "\(.key): \(.value | type)"'

Extract and Filter

# Get all items
jq '.[]' data.json

# Filter by field value
jq '.[] | select(.status == "active")' data.json

# Extract specific fields
jq '.[] | {name, ip}' data.json

Format for Shell

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

# Tab-separated for column
jq -r '[.name, .ip] | @tsv' data.json | column -t

# CSV export
jq -r '.[] | [.name, .ip] | @csv' data.json > export.csv

Common Flags

Flag Purpose

-r

Raw output (no JSON quotes)

-c

Compact (one line per object)

-s

Slurp (read all inputs into array)

-S

Sort object keys

--arg name val

Pass shell variable as string

--argjson name val

Pass shell variable as JSON

The Three-Stage Pattern

Most infrastructure queries follow this:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Source    │ --> │  Transform  │ --> │   Present   │
│  (API/CLI)  │     │    (jq)     │     │ (column/awk)│
└─────────────┘     └─────────────┘     └─────────────┘
# Source: Get raw data
netapi ise --format json get-policy-sets |

# Transform: Extract and shape
jq -r '.[] | [.name, .state, .rank] | @tsv' |

# Present: Human-readable
column -t -N "POLICY,STATE,RANK"

Next Steps

  1. Start with Core Reference - understand the syntax

  2. Apply to your daily tools - pick one deep-dive document

  3. Practice with real API responses - don’t use toy examples

  4. Build muscle memory - use jq daily for 2 weeks

The fastest way to learn jq:

Save a real API response to a file, then iteratively build your query:

curl -s "$API" > response.json
cat response.json | jq 'keys'
cat response.json | jq '.data | keys'
cat response.json | jq '.data[0]'
# ... build incrementally

Resources