jq is the industry-standard command-line JSON processor for Linux, macOS, and Windows. Acting like sed or awk specifically designed for JSON data structures, jq enables developers and DevOps engineers to parse API responses, slice arrays, transform object schemas, and extract fields directly within terminal pipelines.
Operating jq efficiently requires understanding stream processing filters, array mapping syntax, boolean conditionals, and raw unquoted output flags to pass data directly into shell variables or automated scripts.
Key Takeaways
- Use `jq '.' file.json` to pretty-print raw JSON payloads with syntax highlighting.
- Extract nested properties using dot notation (`.user.profile.name`) and optional chaining (`.user?.email`).
- Filter and map arrays using bracket notation (`.items[] | select(.status == "active")`).
- Combine multiple JSON inputs into a unified array using the `-s` (`--slurp`) flag.
How do you pretty-print and format JSON data using jq?
Pretty-printing formats compact, minified JSON strings into human-readable indented structures with syntax highlighting. Applying jq filters to raw cURL response streams ensures that API data is visually clean and easily inspectable in your terminal.
# Pretty-print JSON from a file
jq '.' data.json
# Pretty-print JSON stream from cURL API response
curl -s https://api.github.com/repos/octocat/Hello-World | jq '.'
# Output raw unquoted text strings (strips outer quotes)
curl -s https://api.github.com/users/octocat | jq -r '.name'
# Output compact minified single-line JSON
jq -c '.' data.jsonHow do you extract nested keys, array elements, and slice sequences?
Property extraction retrieves specific values, sub-objects, or array elements using dot paths and index brackets. Using optional chaining (?) prevents script execution errors when parsing payloads that may contain null or missing keys.
| Filter Syntax | Action |
|---|---|
.name | Extract value of top-level name property |
.user.address.city | Navigate nested object hierarchy |
.items[0] | Extract first element of an array |
.items[-1] | Extract last element of an array |
.items[0:3] | Slice first 3 items from an array |
.items[].title | Iterate array elements and extract title from each |
.user?.phone | Optional chaining (suppresses error if user is null) |
How do you filter arrays with select and conditional expressions?
Conditional filtering uses select() and boolean operators to return only array elements matching specific criteria. You can combine comparison operators, regular expressions, and numerical bounds to isolate targeted data objects from large JSON arrays.
# Filter array elements where status is "active"
jq '.users[] | select(.status == "active")' users.json
# Filter numerical range (age greater than or equal to 21)
jq '.users[] | select(.age >= 21)' users.json
# Case-insensitive substring matching on a field
jq '.users[] | select(.email | test("@gmail\\.com$"; "i"))' users.json
# Filter with multiple conditions (active AND admin)
jq '.users[] | select(.status == "active" and .role == "admin")' users.jsonHow do you construct new JSON objects and arrays from existing data?
Data transformation reshapes input JSON by constructing new custom keys, mapping array objects, or combining fields into custom structures. Constructing new JSON objects directly within jq allows you to strip unused metadata and pass minimal payloads to downstream APIs.
# Construct a new custom object with selected fields
jq '{username: .name, email_address: .contact.email}' user.json
# Map an array of objects into simplified key-value pairs
jq '[.users[] | {id: .id, name: .name}]' users.json
# Group items by category property
jq 'group_by(.category)' items.json
# Sort an array of objects by price field ascending
jq 'sort_by(.price)' products.jsonFrequently Asked Questions
What is the difference between jq -r and standard jq?
jq outputs values formatted as valid JSON (meaning strings include surrounding double quotes like "Vishnu"). The -r (--raw-output) flag outputs raw text strings without quotes, making it ideal for passing variables to shell scripts.
How do I parse multi-line JSON or concatenated streams with jq -s?
The -s (--slurp) flag reads all input JSON objects into a single top-level array before applying filters, allowing you to run operations like jq -s 'length' across multi-object files.
What to Read Next
- cURL Command-Line Cheat Sheet — Combine cURL API calls with
jqparsing. - Linux Bash Cheat Sheet: Commands & Scripting — Shell scripting pipelines.
- Vim Cheat Sheet: Modes & Navigation — Terminal editing tools.
