Cheatsheet & Examples: jq

The jq command is a powerful tool for processing and manipulating JSON data from the command line. It allows filtering, transforming, and extracting information from JSON inputs.

Filter JSON data by a key

Example Usage:
jq '.key' input.json
What it does:
Extracts the value associated with the specified key from the JSON object.
Command-line Arguments Explained:

• .key: Selects the value of the "key" field at the root level of the JSON object.
• input.json: The JSON file to process.

Extract specific fields from nested JSON

Example Usage:
jq '{name: .user.name, id: .user.id}' input.json
What it does:
Creates a new JSON object containing only the name and id fields from the user object.
Command-line Arguments Explained:

• {name: .user.name, id: .user.id}: Constructs a new object with specified fields.
• input.json: The JSON file to process.

Pretty-print JSON data

Example Usage:
jq '.' input.json
What it does:
Formats the JSON input with indentation and line breaks for readability.
Command-line Arguments Explained:

• .: Selects the entire JSON object or array.
• input.json: The JSON file to process.

Output raw text instead of JSON

Example Usage:
jq -r '.key' input.json
What it does:
Prints the value of the specified key as plain text, without JSON formatting.
Command-line Arguments Explained:

• -r: Outputs raw strings instead of JSON-encoded values.
• .key: Selects the value of the "key" field.
• input.json: The JSON file to process.

Transform JSON by adding or modifying fields

Example Usage:
jq '. + {newField: "value"}' input.json
What it does:
Adds a new field newField with the value "value" to the JSON object.
Command-line Arguments Explained:

• . + {newField: "value"}: Merges the existing JSON with a new key-value pair.
• input.json: The JSON file to process.

Filter JSON arrays by a condition

Example Usage:
jq 'select(.status == "active")' input.json
What it does:
Retrieves JSON array elements where the status field matches the specified value.
Command-line Arguments Explained:

• select(.status == "active"): Filters array elements based on a condition.
• input.json: The JSON file to process.

Iterate over array elements and extract values

Example Usage:
jq '.[] | .name' input.json
What it does:
Prints the name field from each element in the JSON array.
Command-line Arguments Explained:

• .[]: Iterates over each item in the array.
• .name: Selects the name field from each item.
• input.json: The JSON file to process.

Use command-line variables in filters

Example Usage:
jq --arg name "John" '{user: $name}'
What it does:
Injects a shell variable (name) into a JSON object using the --arg flag.
Command-line Arguments Explained:

• --arg name "John": Defines a variable name with the value "John" for use in the filter.
• {user: $name}: Constructs a JSON object with the variable plugged in.

Sort JSON objects by a specific field

Example Usage:
jq 'sort_by(.age)' input.json
What it does:
Sorts the JSON array elements based on the age field in ascending order.
Command-line Arguments Explained:

• sort_by(.age): Sorts the input array by the age field.
• input.json: The JSON file to process.

Combine multiple filters and transformations

Example Usage:
jq '. | {id: .id, details: .user | {name: .name, role: .role}}' input.json
What it does:
Nested filtering to extract and restructure complex JSON data.
Command-line Arguments Explained:

• . | {id: .id, details: ...}: Chains transformations to build a new structure.
• input.json: The JSON file to process.

Output compact JSON without pretty-printing

Example Usage:
jq -c '.key' input.json
What it does:
Prints the JSON output in a single line, without indentation or line breaks.
Command-line Arguments Explained:

• -c: Outputs compact JSON format.
• .key: Selects the value of the "key" field.
• input.json: The JSON file to process.

Process JSON from standard input

Example Usage:
echo '{"name": "Alice"}' | jq '.name'
What it does:
Extracts the name field from a JSON string provided via standard input.
Command-line Arguments Explained:

• echo '{"name": "Alice"}': Sends JSON to standard input.
• jq '.name': Processes the input and outputs the name value.

Use scripts from a file

Example Usage:
jq -f script.jq input.json
What it does:
Executes a pre-written jq filter script from a file (script.jq).
Command-line Arguments Explained:

• -f script.jq: Specifies the script file to use.
• input.json: The JSON file to process.

Count the number of elements in a JSON array

Example Usage:
jq 'length' input.json
What it does:
Returns the number of items in the JSON array at the root level.
Command-line Arguments Explained:

• length: Outputs the count of the input array.
• input.json: The JSON file to process.

Convert JSON to CSV format

Example Usage:
jq -r '.[] | .name, .id' input.json
What it does:
Converts a JSON array into a CSV-like format, printing name and id fields.
Command-line Arguments Explained:

• -r: Outputs raw text (no JSON quotes).
• .[] | .name, .id: Iterates over array elements and prints specified fields.
• input.json: The JSON file to process.