jq Playground: Learn jq Filters with Instant In-Browser Results

Once you start noticing jq, you cannot stop seeing it. It hides inside CI scripts that summarize test results, shell one-liners that reshape curl responses, AWS CLI output delivered as a wall of nested JSON, and GitHub Actions logs trimmed with expressions like .jobs[].name. jq is the de facto standard for pulling structured values out of JSON on the command line, so nearly every developer touches it eventually.

The catch is that jq's syntax is dense. A stray bracket or a missing pipe produces an error, and the only reliable way to learn is to iterate: paste JSON, write a filter, inspect the output, adjust. Doing that loop in a terminal means installing jq first, juggling sample files, and re-running commands over and over.

The jq Playground removes all of that friction. Paste a JSON document, type a filter expression, and see the formatted result instantly — no install, no account, and nothing leaves your browser. This guide covers the tool and, more importantly, the small set of jq filters that handle most real-world work.

Why Use jq Playground?

• Zero installation — jq runs on Linux, macOS, and Windows, but locked-down machines often lack it. The playground needs only a browser tab, so you can learn and prototype anywhere.
• Instant feedback loop — every keystroke re-evaluates the filter against your JSON. A terminal round trip of edit, save, and re-run is many times slower.
• Syntax errors with positions — invalid filters report what is wrong and where, so you fix the bracket instead of staring at a generic shell message.
• Reusable built-in examples — preset query expressions, from the identity filter to select() and aggregation, show correct syntax you can adapt in one click.
• Completely client-side — evaluation happens in your browser, so pasting internal API responses, config snippets, or log excerpts sends nothing anywhere.
• Formatted output — results are pretty-printed, making the shape of the output (one value or a stream of many) obvious at a glance.

Key Features

Two details deserve emphasis:

• Minified input is fine. Payloads copied from a curl command or an API log are often one long line; the playground handles them exactly like formatted JSON.
• The output panel shows streams. When a filter emits multiple values you see each one, which quietly builds the correct mental model of how jq actually works.

How to Use jq Playground

1. Paste your JSON. Copy an API response, CI log, or config file into the input area. Malformed input is flagged right away.
2. Start with the identity filter. Type . and confirm the parsed document appears in the output; this verifies the JSON itself is valid before you filter it.
3. Narrow down with field access. Replace . with .repo or .items[] to pull out a single field or iterate over an array.
4. Compose stages with pipes. Chain operations — iterate, select, transform — and check the output after each stage; if a syntax error appears, the reported position shows which stage broke.
5. Copy the working filter into your script. Once the expression returns exactly what you want, paste it into your shell one-liner, CI step, or runbook.

jq Filters Worth Memorizing

Before the examples, one idea explains almost everything about jq: every filter transforms a stream of input values into a stream of output values. A single JSON document is a stream of one value. The iteration suffix [] explodes an array into one value per element, and a pipe sends each value produced so far through the next stage. Read filters this way and complex expressions stop being intimidating.

Use this realistic CI result as the payload for all three examples:

{
  "repo": "forge/web-tools",
  "branch": "main",
  "items": [
    { "name": "build-api", "status": "passed", "duration_ms": 1840 },
    { "name": "build-web", "status": "passed", "duration_ms": 2210 },
    { "name": "e2e-suite", "status": "failed", "duration_ms": 9870 }
  ]
}

Identity and field access. The filter . returns the input unchanged, .repo returns "forge/web-tools", and .items[0].name returns "build-api". A missing field returns null rather than an error, which is convenient when payloads vary between versions.

Iteration. .items[] replaces the single input value with three values, one per check. Add a field access: .items[] | .name streams build-api, build-web, and e2e-suite as three separate outputs.

Example 1 — find the failing checks. Pipe the stream into select(), which passes through only the values where a condition holds:

.items[] | select(.status == "failed") | .name

The output is a single value, e2e-suite. Change the condition to .status != "passed" and the same shape answers a different question.

Example 2 — build a readable summary line. String interpolation embeds values inside text using \(...):

.items[] | "\(.name) finished in \(.duration_ms / 1000) seconds"

Each stream value produces one readable sentence — exactly the kind of line you drop into a notification step or a build report.

Example 3 — aggregate back into one value. Streams are great, but scripts often need a single result. Wrap the iteration in brackets to collect the stream into an array, then reduce it:

[.items[].duration_ms] | add / 1000

That returns the total runtime, 13.92. The iterate-transform-collect pattern, [.items[] | ...], is one of the most reused shapes in production jq code.

Inventory builtins. keys lists an object's fields, values lists its values, and length counts array elements, object keys, or string characters. The expression .items | length answers "how many checks ran?" in four characters.

Practical Use Cases for jq

Parsing GitHub and API JSON in Shell Scripts

Most jq usage lives inside pipelines: curl -s https://api.example.com/runs | jq '.items[] | select(.status == "failed") | .name'. Writing that blind against a live endpoint is risky — save one sample response, paste it into the playground, confirm the output, then embed the filter in your script. Your CI steps stop failing on filter typos.

Log and Event Extraction

GitHub Actions summaries, cloud service events, and application logs are all structured JSON. During an incident, paste a chunk of the stream and answer triage questions in seconds: which steps failed, how long each took, and whether a value appears anywhere in the payload.

Config and Manifest Inspection

Lockfiles, Kubernetes manifests, and infrastructure state files are all JSON. Instead of scrolling through thousands of lines, run keys to see the top-level structure, length to size up arrays, and targeted field access to pull the one entry you need.

Teaching jq to Teammates

In a code review or pairing session, paste the real payload and build the filter live while the preset examples show the canonical patterns. Teammates who see streams and select() demonstrated once usually stop reaching for ad hoc Python scripts to do the same job.

Best Practices for Working with jq

• Prototype here first, then paste into scripts. Iterating in the playground is faster and safer than testing filters against production endpoints or cron jobs.
• Quote keys with special characters. Fields like user-id need .["user-id"] syntax — plain .user-id is parsed as subtraction.
• Remember the stream. A filter that emits several values is not broken; it is iteration. Wrap the expression in [...] only when you truly need one array back.
• Keep a realistic sample payload. Filters that work on toy data often break on real shapes with optional fields, so save one representative response per API.
• Orient with builtins before drilling in. keys, length, and the identity filter reveal more in five seconds than guessing field paths ever will.
• Read the error position, not just the message. jq errors point near the offending character, and the playground surfaces that position.

Ready to Put jq to Work?

Open the jq Playground, paste the ugliest JSON response you dealt with this week, and rebuild one filter you already use. Ten minutes of practice against real data does more for your jq fluency than any cheat sheet — and everything runs locally in your browser.

Related Tools You Might Like:

• JSON Formatter — pretty-print and validate messy JSON before you write filters against it
• JMESPath Tester — practice JMESPath, the query language behind AWS CLI --query parameters
• GraphQL Formatter — format and review GraphQL queries and responses alongside your JSON tooling

Happy filtering!

Frequently Asked Questions

Q: Is my JSON uploaded to a server?

A: No. jq Playground evaluates filters entirely in your browser with JavaScript. Nothing you paste is transmitted, stored, or logged, which makes it safe for internal payloads and config snippets.

Q: Do I need jq installed to use the playground?

A: No. The tool implements jq filter evaluation client-side, so you can learn and prototype in any browser and only install jq later, when a script actually needs it.

Q: Does what I learn here transfer to the command-line jq?

A: Yes. The syntax — field access, [] iteration, pipes, select(), and builtins like length and keys — is standard jq, so a filter that works in the playground behaves the same way in your terminal or CI script.

Q: The output shows several values instead of one array. Is that a bug?

A: No. Iteration with [] produces a stream of values. If you need a single array, wrap the expression in brackets, for example [.items[] | .name].