jq

Syntax for filtering, mapping, transforming, and restructuring JSON data from the command line.

Basic Extraction & Formatting

Essential commands to format, pretty-print, extract keys, and work with raw text or indices.

Pretty Print JSON

Formats JSON with indentation for human-readable output.

jq '.'

Example

cat data.json | jq '.'

Extract Key Value

Selects the value of a specific key in a JSON object.

jq '.<key_name>'

Example

jq '.name' data.json

Output Raw Text

Outputs string values without surrounding double quotes for scripting.

jq -r '.<key_name>'

Example

jq -r '.name' data.json

Access Array Index

Retrieves a specific element from an array by its numeric index.

jq '.[<index>]'

Example

jq '.[0]' items.json

Slice Array Range

Extracts a sub-range of elements from an array.

jq '.[<start>:<end>]'

Example

jq '.[1:3]' items.json

Filtering, Length & Conditionals

Methods to search, evaluate conditions, check sizes, and apply conditional logic.

Select with Condition

Filters objects based on a conditional expression.

jq 'select(.<key> <operator> <value>)'

Example

jq 'select(.age > 18)' users.json

Check Length

Returns the length of an array, string, or object.

jq '.<key> | length'

Example

jq '.tags | length' post.json

Conditional If Else

Transforms values conditionally using if-then-else logic.

jq 'if .<key> then <true_expr> else <false_expr> end'

Example

jq 'if .active then "Active" else "Inactive" end' data.json

Mapping and Restructuring

Transforming arrays, projecting new objects, and flattening data structures.

Map Over Array

Applies an expression to each element in an array.

jq 'map(.<key>)'

Example

jq 'map(.name)' users.json

Construct New Object

Builds a custom JSON object with selected properties.

jq '{<new_key>: .<old_key>}'

Example

jq '{fullName: .name, userAge: .age}' user.json

Map Object Fields

Creates an array of custom-shaped objects from an array.

jq 'map({<key1>: .<prop1>, <key2>: .<prop2>})'

Example

jq 'map({name: .name, age: .age})' users.json

Flatten Nested Arrays

Flattens an array of arrays into a single-level array.

flatten

Example

jq 'flatten' nested.json

Advanced Transformations & Aggregations

Powerful aggregations, string interpolation, grouping, conversion, and variables.

String Interpolation

Formats strings dynamically using object variables.

jq '"<text> \(.<key>) <text>"'

Example

jq '"Hello \\(.name)!"' user.json

Group By Key

Groups objects in an array by a specific key.

jq 'group_by(.<key>)'

Example

jq 'group_by(.category)' products.json

Count Value Occurrences

Counts occurrences of unique values within an array.

jq 'group_by(.) | map({key: .[0], count: length})'

Example

jq '["a", "b", "a", "c"] | group_by(.) | map({key: .[0], count: length})'

Convert JSON to CSV

Converts an array of objects into flat CSV rows.

jq -r 'map([.<prop1>, .<prop2>] | @csv) | .[]'

Example

jq -r 'map([.name, .age] | @csv) | .[]' users.json

Pass External Variables

Safely passes external shell variables into jq scripts.

jq --arg <var_name> "<value>" '.<key> == $var_name'

Example

jq --arg target "Admin" '.role == $target' users.json