Mastering jq: 10 Practical Commands to Transform and Query JSON Efficiently

Working with JSON data is a daily task for developers, data analysts, and DevOps engineers. Whether you're parsing API responses, cleaning up configuration files, or transforming datasets, navigating through raw JSON can quickly become tedious and error-prone.

That's where jq comes in.

jq is a lightweight and powerful command-line JSON processor. It allows you to query, filter, transform, and reshape JSON data efficiently right from your terminal. Instead of writing custom scripts for every task, you can often achieve what you need with a single jq command.

In this guide, we'll dive into 10 practical jq commands you can actually use in your daily work. We'll focus on real-world examples, clear explanations, and tips to help you avoid common pitfalls.

Let's get started.

What is jq and Why It Matters

jq is often described as the "sed" or "awk" for JSON. It's designed to handle structured JSON data with the same speed and efficiency that traditional Unix tools bring to plain text.

Key reasons to learn jq:

• Speed: Quickly filter and transform JSON without custom scripts.
• Power: Handle complex transformations with concise syntax.
• Portability: Available on Mac, Linux, and Windows.
• Simplicity: Once you learn the basics, most operations are intuitive.

If you deal with JSON regularly, learning jq will save you countless hours.

Installing jq

Installing jq is straightforward.

• macOS:

brew install jq

• Ubuntu/Linux:

sudo apt install jq

• Windows: Download from the official releases page.

Once installed, you can verify it with:

jq --version

10 Practical jq Commands (With Real Examples)

Below are 10 essential jq commands you should know.

Each example includes:

• A real-world problem
• The input JSON
• The jq command
• The output

Let's dive in.

1. Pretty-Print and Validate JSON

Problem: You have a minified or messy JSON file and want to make it readable.

Command:

jq . data.json

Input:

{ "name": "Alice", "age": 25, "city": "London" }

Output:

{
  "name": "Alice",
  "age": 25,
  "city": "London"
}

Tip: jq also validates the JSON structure. If the JSON is invalid, jq will throw an error.

2. Select a Single Field

Problem: You want to extract a specific field.

Command:

jq '.name' data.json

Input:

{
  "name": "Alice",
  "age": 25,
  "city": "London"
}

Output:

"Alice"

3. Select Multiple Fields

Problem: You want to create a subset with only selected fields.

Command:

jq '{name, city}' data.json

Output:

{
  "name": "Alice",
  "city": "London"
}

4. Work with Arrays

Problem: You want to process items inside a JSON array.

Command:

jq '.users[]' users.json

Input:

{
  "users": [{ "name": "Alice" }, { "name": "Bob" }]
}

Output:

{"name": "Alice"}
{"name": "Bob"}

5. Map and Transform Data

Problem: You want to rename fields while iterating.

Command:

jq '.users[] | {username: .name}' users.json

Output:

{"username": "Alice"}
{"username": "Bob"}

6. Filter by Conditions

Problem: Select objects based on a condition.

Command:

jq '.products[] | select(.price > 20)' products.json

Input:

{
  "products": [
    { "name": "Book", "price": 15 },
    { "name": "Pen", "price": 5 },
    { "name": "Headphones", "price": 50 }
  ]
}

Output:

{ "name": "Headphones", "price": 50 }

7. Delete Fields

Problem: You want to remove sensitive information.

Command:

jq 'del(.password)' user.json

Input:

{
  "username": "alice",
  "password": "secret"
}

Output:

{
  "username": "alice"
}

8. Compact Output

Problem: You want minified JSON for API requests.

Command:

jq -c . data.json

Output:

{ "name": "Alice", "age": 25, "city": "London" }

9. Combine Filters and Pipes

Problem: You need multiple operations together.

Command:

jq '.users[] | select(.active == true) | {id, name}' users.json

Explanation:

• .users[]: iterate over users
• select(.active == true): filter only active users
• {id, name}: pick only id and name fields

Output:

{
  "id": 1,
  "name": "Alice"
}

10. Using jq in Shell Scripts

Problem: Automate JSON processing from APIs.

Command:

curl -s https://api.example.com/data | jq '.items[] | .name'

Explanation:

• Fetch data via curl
• Pipe it directly into jq
• Extract item names

This is especially powerful for automating daily scripts.

Bonus: Running jq Commands Visually

While jq is extremely powerful in the command line, sometimes it's easier to visualize your data and transformations.

If you want to apply jq filters visually, ToDiagram lets you:

• Paste or upload your JSON, YAML, or CSV
• Run jq commands directly on the structured data
• See immediate results on an interactive diagram

It's a great way to experiment with complex queries without losing track of your data structure.

JSON diagram

Conclusion

jq is one of those rare tools that can drastically improve your productivity once you master the basics. Whether you're dealing with massive API responses, nested JSON structures, or cleaning datasets, jq gives you the flexibility and control you need — all from the command line.

Start by practicing these 10 commands, and you'll quickly build the confidence to tackle even more complex transformations. The more you use jq, the more you'll appreciate its elegance and power.

Happy querying!