How to use the command jq (with examples)

The jq command is a powerful command-line JSON processor that allows you to manipulate and extract data from JSON files using a domain-specific language (DSL). It provides a simple and flexible way to work with JSON data in the command line.

Use case 1: Execute a specific expression

Code:

cat path/to/file.json | jq '.'

Motivation:

This use case is useful when you want to print the JSON output in a colored and formatted way. It helps you to better visualize the structure and content of the JSON file.

Explanation:

• cat path/to/file.json: Reads the content of the JSON file.
• |: Pipes the output of the previous command as input to the jq command.
• jq '.': Executes the expression . which represents the current object. It effectively prints the content of the JSON file in a colored and formatted output.

Example output:

{
  "key1": "value1",
  "key2": "value2",
  ...
}

Use case 2: Execute a specific script

Code:

cat path/to/file.json | jq --from-file path/to/script.jq

Motivation:

Sometimes, complex JSON data manipulation requires a more elaborate script. In such cases, you can pass the path to a script file using the --from-file option. This allows you to reuse and manage your scripts separately.

Explanation:

• cat path/to/file.json: Reads the content of the JSON file.
• |: Pipes the output of the previous command as input to the jq command.
• jq --from-file path/to/script.jq: Executes the script specified in the path/to/script.jq file.

Example output:

{
  ...
}

Use case 3: Pass specific arguments

Code:

cat path/to/file.json | jq --arg "name1" "value1" --arg "name2" "value2" ... '. + $ARGS.named'

Motivation:

When you need to pass specific arguments to the jq script, you can use the --arg option. This allows you to parameterize the script and provide dynamic values to it.

Explanation:

• cat path/to/file.json: Reads the content of the JSON file.
• |: Pipes the output of the previous command as input to the jq command.
• jq --arg "name1" "value1" --arg "name2" "value2" ...: Provides arguments to the jq script.
• '. + $ARGS.named': Concatenates the current object (.) with the values of the named arguments ($ARGS.named).

Example output:

{
  "key1": "value1",
  "key2": "value2",
  ...
}

Use case 4: Print specific keys

Code:

cat path/to/file.json | jq '.key1, .key2, ...'

Motivation:

In some cases, you may only be interested in printing specific keys from the JSON file. This use case helps you extract and display only the desired keys.

Explanation:

• cat path/to/file.json: Reads the content of the JSON file.
• |: Pipes the output of the previous command as input to the jq command.
• jq '.key1, .key2, ...': Prints the values of the specified keys, such as key1, key2, and so on.

Example output:

"value1"
"value2"
...

Use case 5: Print specific array items

Code:

cat path/to/file.json | jq '.[index1], .[index2], ...'

Motivation:

When dealing with JSON arrays, you may want to print only specific items from the array. This use case helps you extract and display only the desired array items.

Explanation:

• cat path/to/file.json: Reads the content of the JSON file.
• |: Pipes the output of the previous command as input to the jq command.
• jq '.[index1], .[index2], ...': Prints the values of the array items at the specified indices, such as index1, index2, and so on.

Example output:

"value1"
"value2"
...

Use case 6: Print all array items/object keys

Code:

cat path/to/file.json | jq '.[]'

Motivation:

If you want to extract and display all the array items or object keys, you can use this use case. It helps you iterate through all the elements and display each of them.

Explanation:

• cat path/to/file.json: Reads the content of the JSON file.
• |: Pipes the output of the previous command as input to the jq command.
• jq '.[]': Prints all the array items or object keys.

Example output:

"value1"
"value2"
...

Use case 7: Add/remove specific keys

Code:

cat path/to/file.json | jq '. +|- {"key1": "value1", "key2": "value2", ...}'

Motivation:

Sometimes, you may need to add or remove specific keys from the JSON file. This use case allows you to modify the JSON data by adding or removing the desired keys.

Explanation:

• cat path/to/file.json: Reads the content of the JSON file.
• |: Pipes the output of the previous command as input to the jq command.
• jq '. +|- {"key1": "value1", "key2": "value2", ...}': Adds or removes the specified keys and their corresponding values from the JSON data. The + sign adds keys and the | - sign removes keys.

Example output:

{
  "key1": "value1",
  "key2": "value2",
  ...
}

Conclusion:

The jq command is a versatile tool for working with JSON data in the command line. It provides various use cases, such as executing expressions and scripts, passing arguments, printing specific keys and array items, and modifying JSON data. It allows you to easily manipulate and extract the desired information from JSON files. Whether you need to format, filter, or transform JSON data, jq is a valuable tool to have in your command-line toolkit.