Skip to the content
GigaJSON
All tools
Format and check
View and query
Convert
JSON to code
Encode and decode
Sample files
Guides Open GigaJSON

jq vs JSONPath vs JMESPath: the same 8 tasks in all three

· 6 min read · Updated · By Amir Badi

All three languages pull values out of JSON. They part ways in how much else they do, and you see that fastest by solving the same problems in each. Below are eight tasks on one data file. I ran every query with jq 1.7, the jsonpath-plus library for JSONPath, and jmespath.js.

Paste the sample into the JSONPath tester, the JMESPath playground or the jq playground and switch languages to try each line yourself.

GigaJSON jq playground filtering pending orders over 100 to return ord_002GigaJSON jq playground filtering pending orders over 100 to return ord_002 (dark theme)
Run a filter against a small example first, then adapt it to your data. Screenshots follow the page theme. Click to view full size.

Which one to use

  • Use JSONPath when a tool asks for it, or when all you need is to point at values: test assertions, config templates, kubectl -o jsonpath.
  • Use JMESPath when you're in the AWS or Azure CLI (--query), or when you want selection plus a bit of reshaping with a strict, portable spec.
  • Use jq for anything that computes or reshapes, and in shell scripts. Of the three, only jq is a programming language.

Learning one from scratch for your own work? I'd learn jq.

The sample data

{
  "orders": [
    { "id": "A-100", "customer": { "name": "Ana", "country": "PT" }, "status": "paid",
      "total": 120.5, "items": [ { "sku": "KB-01", "qty": 1 }, { "sku": "MS-02", "qty": 2 } ] },
    { "id": "A-101", "customer": { "name": "Ben", "country": "US" }, "status": "pending",
      "total": 35, "items": [ { "sku": "MS-02", "qty": 1 } ] },
    { "id": "A-102", "customer": { "name": "Chloe", "country": "PT" }, "status": "paid",
      "total": 410, "items": [ { "sku": "MN-27", "qty": 1 }, { "sku": "KB-01", "qty": 1 } ] }
  ]
}

Task 1: every customer name

Language Query Result
JSONPath $.orders[*].customer.name ["Ana","Ben","Chloe"]
JMESPath orders[*].customer.name ["Ana","Ben","Chloe"]
jq [.orders[].customer.name] ["Ana","Ben","Chloe"]

Nearly the same, with two differences already. JSONPath starts at $ and gives you a list of matches. jq gives you a stream of separate values: drop the outer brackets and you get three lines, "Ana", "Ben" and "Chloe", which suits a shell loop.

Task 2: orders over 100

Language Query
JSONPath $.orders[?(@.total > 100)].id
JMESPath orders[?total > `100`].id
jq [.orders[] | select(.total > 100) | .id]

Each returns ["A-100","A-102"]. JMESPath puts literals in backticks (`100`, `"x"`) and raw strings in single quotes ('paid'). Those backticks catch people out in shell scripts, where backticks run a command. Put the whole query in single quotes.

RFC 9535, the JSONPath standard since 2024, lets you drop the parentheses: $.orders[?@.total > 100].id. Plenty of libraries still expect the older ?(...) form (jsonpath-plus returns [] without the parentheses), and that older form works nearly everywhere.

Task 3: every SKU from nested arrays

Language Query
JSONPath $.orders[*].items[*].sku or $..sku
JMESPath orders[].items[].sku
jq [.orders[].items[].sku]

Result: ["KB-01","MS-02","MS-02","MN-27","KB-01"].

JSONPath's .. (recursive descent) finds a key at any depth, handy when you don't know the structure. In jq you'd write [.. | .sku? // empty].

Watch the JMESPath version. orders[*].items[*].sku keeps the nesting and returns [["KB-01","MS-02"],["MS-02"],["MN-27","KB-01"]]. [] flattens one level, while [*] projects and leaves the nesting alone. For one flat list, use [].

Task 4: count the orders

Language Query Result
JSONPath none in the standard
JMESPath length(orders) 3
jq .orders | length 3

JSONPath can't do this one. RFC 9535 has a length() function, but you can only use it inside a filter, never as the result. A few libraries return JavaScript's .length property for $.orders.length (jsonpath-plus gives [3]). That's an accident of how they're built, and I wouldn't depend on it.

Task 5: two conditions at once

Paid orders from Portugal:

Language Query
JSONPath $.orders[?(@.customer.country == "PT" && @.status == "paid")].id
JMESPath orders[?customer.country == 'PT' && status == 'paid'].id
jq [.orders[] | select(.customer.country == "PT" and .status == "paid") | .id]

Same answer from each: ["A-100","A-102"]. JSONPath and JMESPath use && and ||, and jq spells them and and or.

Task 6: orders that contain a given SKU

A filter on a nested array: which orders include KB-01?

Language Query
JSONPath (RFC 9535) $.orders[?@.items[?@.sku == 'KB-01']].id
JMESPath orders[?contains(items[].sku, `"KB-01"`)].id
jq [.orders[] | select(any(.items[]; .sku == "KB-01")) | .id]

JMESPath and jq both return ["A-100","A-102"]. The JSONPath query is valid RFC 9535 (a nested filter used as an existence test), but libraries disagree on it: jsonpath-plus returned []. A JSONPath library older than the RFC breaks on queries like this first. The usual way out is to select the orders and filter them in your own code.

Task 7: build new objects

Just the id and total of each order:

Language Query
JSONPath not possible
JMESPath orders[*].{id: id, total: total}
jq [.orders[] | {id, total}]

Both give [{"id":"A-100","total":120.5},{"id":"A-101","total":35},{"id":"A-102","total":410}]. In jq, {id, total} is short for {id: .id, total: .total}.

JSONPath only returns values that already exist. $.orders[*]['id','total'] gives ["A-100",120.5,"A-101",35,...]: one flat list, and you lose which total went with which id.

Task 8: sort, sum and find the maximum

What JMESPath jq
ids sorted by total sort_by(orders, &total)[*].id .orders | sort_by(.total) | map(.id)
sum of totals sum(orders[*].total) [.orders[].total] | add
id of the largest order max_by(orders, &total).id .orders | max_by(.total) | .id

Results: ["A-101","A-100","A-102"], 565.5, "A-102". JSONPath has no sorting or arithmetic at all.

The & in JMESPath makes an expression reference. It hands total to sort_by as the thing to sort by, unevaluated.

Beyond the eight: what only jq does

Grouping and aggregating, for a start. Here's the total quantity per SKU across all orders:

jq '[.orders[].items[]]
    | group_by(.sku)
    | map({sku: .[0].sku, qty: (map(.qty) | add)})' orders.json
[{"sku":"KB-01","qty":2},{"sku":"MN-27","qty":1},{"sku":"MS-02","qty":3}]

JMESPath has no group-by. jq also gives you variables (as $x), reduce, string interpolation, regular expressions, @csv/@tsv output, several input files at once, and --stream for files bigger than memory. All that explains why jq lives in shell scripts and CI pipelines, and why its syntax takes longer to learn.

Side by side

Feature JSONPath JMESPath jq
Specification RFC 9535 (2024); older libraries vary Formal spec with compliance tests The jq manual; one main implementation plus ports
Selects values Yes Yes Yes
Recursive search .. No ..
Builds new objects No Yes (multiselect hash) Yes
Sort, sum, min, max No Yes Yes
Group by, variables, reduce No No Yes
Typical home Test tools, Java/JS libraries, kubectl -o jsonpath aws --query, az --query, embedded in apps Shell, CI, data cleanup

Practical advice

Let the place the query runs decide. In the AWS CLI you're writing JMESPath, like it or not. If a test framework takes JSONPath, write JSONPath and keep the logic in code. At a terminal with a file, jq handles every case above and plenty more.

Stuck on a query? Run it on your real data, not a toy sample. A path that works on three records can hit a null, a missing key or a string-instead-of-number at record 40,000. JMESPath and JSONPath skip missing values without a word (orders[*].customer.nickname gives []), and jq gives null ([null,null,null]), so one mistake looks different in each language. For jq on log files, where one bad line can stop a whole run, see querying API responses and NDJSON logs.

The JSONPath tester and jq playground run all three languages in your browser, and your data stays on your machine. In the GigaJSON app, the Query tab runs JSONPath and JMESPath on documents of hundreds of megabytes. jq tops out at about 20 MB of input there, because the WebAssembly build of jq aborts past roughly 25 MB. For bigger files, run jq in a terminal.

Questions

Which is more powerful, jq or JSONPath?

jq. It's a full programming language with variables, functions, reduce and string formatting, so it can reshape, group and compute. JSONPath only selects values, and anything past that happens in your own code.

Why does the AWS CLI use JMESPath instead of jq?

JMESPath has a precise specification with a compliance test suite, so the same query gives the same result in every implementation, and it is small enough to embed in a CLI. AWS CLI and Azure CLI both accept JMESPath in their --query option.

JMESPath vs jq: which should I use?

JMESPath when the query runs inside a tool that accepts it, such as the AWS CLI, the Azure CLI, Ansible's json_query or n8n's $jmespath. None of those take jq. Use jq on the command line and in scripts, where you need variables, reduce, string formatting or CSV output. Most JMESPath queries have a short jq version; the reverse often isn't true.

Is there a JSONPath standard?

Yes, since February 2024: RFC 9535. Older libraries predate it and differ in details such as filter syntax, nested filters and what .length means, so check which behaviour your library follows.

Can I test jq, JSONPath and JMESPath queries online?

Yes. GigaJSON's JSONPath tester and jq playground run all three languages in your browser on data you paste or open, without uploading it.

More from the blog