{{< partial "learn_x_header" >}}

**Quick Start:** Need to parse JSON from the command line? This jq cookbook shows you the essential commands and examples for filtering, transforming, and processing JSON data effectively. Master jq tutorial techniques with practical examples.

## jq Cookbook: What Will You Learn?

* What is jq?
* What are the use cases for jq?
* How do I parse a remote JSON file with jq?
* How do I parse a local JSON file with jq?
* How do I reformat a local JSON file with jq?

## The Basics

The [jq] command-line JSON parser is a welcome tool in any programmer's toolbelt. Use jq to parse JSON to simplify collecting essential information from JSON files.

### Primary Use Cases {#1-primary-use-cases}

* Parse JSON
* Query JSON
* Reformat parsed JSON

### Less Suitable Use Cases {#2-invalid-use-cases}

* Parsing raw text and XML

### When to Use jq?

Use jq when you need to parse JSON files. jq is a versatile tool that can meet a wide range of JSON parsing needs.

## jq Cookbook: Practical Examples

### Parse A Remote File

[Install curl] and [install jq].

Run this command to query a specific office name from [offices.json]. This jq tutorial example demonstrates basic JSON parsing.

```sh
curl --silent https://raw.githubusercontent.com/jeffabailey/learn/main/tools/jq/offices.json | jq '.[].name'
```

### Parse A Local File

Download [offices.json] and run these commands in your download folder. This jq cookbook example shows local file processing.

```sh
curl --silent https://raw.githubusercontent.com/jeffabailey/learn/main/tools/jq/offices.json > offices.json
jq '.[].name' < offices.json
```

Press the green run button to see the output of this command.

### Reformat A Local File

I am using the previously downloaded [offices.json] to run this command. This jq tutorial demonstrates advanced formatting techniques.

```sh
jq '.[] | {name,location} | join(" is in ")' < ./offices.json
```

Press the green run button to see the output of this command.

The join() function allows for quick formatting.

Try this command for ad-hoc string concatenation.

```sh
jq '.[] | .name + " is in " + .location' < ./offices.json
```

### Filtering JSON Data

Suppose you have a JSON file `employees.json` and you want to filter out employees who are older than 30 years.

```sh
jq '.employees[] | select(.age > 30)' < employees.json
```

### Transforming JSON Data

If you have a JSON file `products.json` and you want to create a new JSON array with only the product names and prices.

```sh
jq '[.products[] | {name: .name, price: .price}]' < products.json
```

## Learn jq - Beyond the Basics

* [jq manual]
* [jq tutorial]
* [jq cookbook]
* [jqplay]

## References

* [jq Cheat Sheet]
* [JSONPath Online Evaluator]
* [Guide to Linux jq Command for JSON Processing - Baeldung]
* [Online Generate Test Data] - Generate some JSON files to play with.
* [tput documentation] - Generates color in bash shells.
* [Add Color to Shell Scripts] - Take tput further for your use cases.

{{< partial "category_footer" >}}

[jq]: https://stedolan.github.io/jq/
[install curl]: https://curl.se/download.html
[install jq]: https://stedolan.github.io/jq/download/
[offices.json]: https://raw.githubusercontent.com/jeffabailey/learn/main/tools/jq/offices.json
[jq manual]: https://stedolan.github.io/jq/manual/
[jq tutorial]: https://stedolan.github.io/jq/tutorial/
[jq cookbook]: https://e.printstacktrace.blog/jq-cookbook/
[jqplay]: https://jqplay.org/
[jq cheat sheet]: https://lzone.de/#/LZone%20Cheat%20Sheets/jq
[jsonpath online evaluator]: https://jsonpath.com/
[guide to linux jq command for json processing - baeldung]: https://www.baeldung.com/linux/jq-command-json
[online generate test data]: https://www.convertcsv.com/generate-test-data.htm
[tput documentation]: https://linuxcommand.org/lc3_adv_tput.php
[add color to shell scripts]: https://blog.mccormack.tech/shell/2018/12/06/add-color-to-shell-scripts.html