jq - Command-Line JSON Processor
jq is a lightweight and flexible command-line JSON processor. It allows you to easily filter, transform, and manipulate JSON data directly from your terminal.
jq Command Examples
Basic Usage and Pretty-Printing
To output a JSON file in a human-readable, pretty-print format, you can use:
jq '.' file.json
This command reads the JSON from file.json and outputs it with indentation.
Extracting Data
You can extract specific fields or elements from JSON data:
- Extract a specific field:
jq '.fieldName' file.json - Extract a specific element from an array by index:
jq '.[index]' file.json - Select multiple fields:
jq '{field1: .field1, field2: .field2}' file.json - Query nested JSON data:
jq '.outerField.innerField' file.json
Array and Object Manipulation
jq excels at working with arrays and objects:
- Output all elements from arrays:
jq .[] - Count the number of elements in an array:
jq '.arrayName | length' file.json - Apply a function to each element in an array:
jq '.arrayName[] | .fieldName' file.json - Concatenate fields:
jq '.field1 + " " + .field2' file.json - Group by a particular field:
jq 'group_by(.fieldName)' file.json - Sort JSON objects by field:
jq 'sort_by(.fieldName)' file.json - Find unique values:
jq 'unique' file.json - Delete a field:
jq 'del(.fieldName)' file.json - Concatenate arrays:
jq 'add' - Flatten an array:
jq 'flatten' - Create a range of numbers:
jq '[range(2;4)]' - Sort an array of basic type:
jq 'sort' - Sort an array of objects:
jq 'sort_by(.foo)' - Sort lines of a file:
jq --slurp '. | sort | .[]' - Minimum value of an array:
jq 'min' - Remove duplicates:
jq 'unique' - Reverse an array:
jq 'reverse'
Filtering and Conditional Logic
Filter JSON objects based on specific conditions:
jq 'select(.fieldName == "value")' file.json
Filter a list of objects:
jq 'map(select(.name == "foo"))'
Input and Output Formats
jq supports various input and output formats:
- Parse JSON from stdin:
cat file.json | jq '.fieldName' - Load JSON from URL:
curl -s "http://example.com/file.json" | jq '.fieldName' - Output compact JSON without whitespace:
jq -c '.' file.json - Combine data from two JSON files:
jq -s '.[0] + .[1]' file1.json file2.json - Read JSON objects from a file into an array:
jq --slurp - Converting arbitrary data to JSON:
jq -r '(map(keys) | add | unique | sort) as $cols \ | .[] as $row | $cols | map($row[.]) | @csv' - Converting to CSV:
jq '.[] | [.foo, .bar] | @csv' -r - Parsing JSON within values:
jq 'with_entries(.value |= fromjson)' --sort-keys - Serializing JSON within values:
jq 'with_entries(.value |= tojson)' --sort-keys
jq in Shell Scripts
Integrate jq into your shell scripts for powerful JSON processing:
- URL Encode something:
date | jq -sRr @uri - Create proper JSON from shell variables:
jq -n --arg foobaz "$FOOBAZ" '{"foobaz":$foobaz}' - Fill environment variables from JSON object keys:
export $(jq -r '@sh "FOO=\(.foo) BAZ=\(.baz)"')