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