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.
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.
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.
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.
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.
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.
