Test jq Filters on JSON
online, free & instant

Filter JSON in three steps

No account. No upload. No nonsense.

Related JSON tools

Common questions answered

What is jq?

jq is a command-line JSON processor for filtering, transforming, and formatting JSON in shell pipelines. Its syntax is concise: .users[] | select(.active) | .name extracts names of active users. jq is installed on many Linux distributions and is the standard for processing JSON in scripts and CI/CD pipelines.

This playground lets you test jq-style expressions in your browser without installing anything. jq supports object construction, array manipulation, conditionals, string interpolation, regular expressions, and user-defined functions. It is useful for ad-hoc data extraction from API responses, log files, and configuration dumps.

// Data
{"users":[
  {"name":"Alice","active":true},
  {"name":"Bob","active":false},
  {"name":"Charlie","active":true}
]}

// Query: .users[] | select(.active) | .name

"Alice"
"Charlie"

Get the most out of this tool

• Use .field to access a key, .[] to iterate an array, and | (pipe) to chain transformations — the core jq workflow.
• select(.field == "value") filters array elements by condition — equivalent to SQL WHERE clause.
• Use @csv or @tsv output formatters to convert JSON arrays directly into spreadsheet-compatible formats.

Understanding jq — the JSON command-line processor

jq is a lightweight, flexible command-line tool for processing JSON data, written by Stephen Dolan and released in 2012. Often described as "sed for JSON", jq enables field extraction, filtering, transformation, and aggregation of JSON data directly in the terminal. Unlike general-purpose scripting languages, jq's filter language is specialized for JSON manipulation, making common operations like field extraction, array mapping, and conditional filtering expressible in compact one-liners.

The identity filter . is jq's simplest expression — it outputs the input unchanged but with pretty-printing applied. This makes jq '.' the most common use of jq: formatting minified JSON from curl output into readable indented format. Combined with curl, curl -s https://api.example.com/data | jq '.' is a staple command for inspecting API responses in the terminal.

Field access in jq uses dot notation: .name accesses the name field of the root object, and .user.email navigates two levels deep. Array indexing uses bracket notation: .[0] accesses the first element. The .[] iterator (without index) expands an array or object, outputting each element on a separate line — fundamental for processing JSONL streams where each input is one array element.

The pipe operator | chains transformations. .users | .[] | .name takes the users array, iterates over its elements, and extracts each element's name field. This pipeline model allows complex transformations to be composed from simple, understandable steps. The select function select(condition) filters to elements matching a condition: .[] | select(.active == true) outputs only active elements.

jq's map() function transforms every element of an array. map(.price * .quantity) multiplies price by quantity for every element in an array. map(select(.status == "active")) is equivalent to filtering with select but preserves the array wrapper. map({name: .name, total: (.price * .quantity)}) creates new objects by projecting and computing fields from each element.

Aggregation with jq uses built-in functions like add, length, min, max, unique, and group_by. [.[] | .price] | add sums all prices in an array. group_by(.category) | map({category: .[0].category, count: length}) groups by category and counts items in each group. These patterns enable data analysis operations without leaving the terminal or writing a Python script.

JSONL (newline-delimited JSON) processing is a jq specialty. The --slurp (-s) flag collects all input lines into one array before applying the filter — useful for cross-record operations. Without --slurp, jq applies the filter to each input line independently — useful for per-record transformations. The --raw-output (-r) flag outputs string values without JSON double-quote wrapping, making extracted values usable directly in shell scripts.

Real-world uses for jq

jq usage pitfalls

• Using . when .[] is needed: . outputs the whole array as-is; .[] iterates over elements. If you want to apply a filter to each element, use .[] | filter or map(filter). A common mistake is writing . | .name expecting to get names from array elements — this fails because . is the entire array, which has no name field.
• Forgetting -r for string output in scripts: Without --raw-output (-r), jq wraps string values in double quotes in its output — "value" instead of value. Shell variable assignment will include the quotes: TOKEN="\"abc123\"". Always use -r when extracting string values for shell variable assignment or use in other commands.
• Null propagation surprises: jq propagates null silently. If a field doesn't exist, accessing it returns null, and further operations on null often also return null. Use // "default" (alternative operator) to provide fallback values: .name // "unknown" returns "unknown" if name is null or missing.
• Single quotes in shell on different platforms: jq filters should be wrapped in single quotes in shell to avoid shell interpolation of special characters. On Windows cmd.exe and PowerShell, single quotes are not string delimiters — use double quotes and escape internal double quotes. Use a jq playground tool to test filters before embedding them in cross-platform scripts.

Additional frequently asked questions