Skip to content

Add search_json(): query a JSON document given as a string, with optional native accelerator - #368

Open
SereinCin wants to merge 1 commit into
jmespath:developfrom
SereinCin:add-native-accelerator-search-json
Open

Add search_json(): query a JSON document given as a string, with optional native accelerator#368
SereinCin wants to merge 1 commit into
jmespath:developfrom
SereinCin:add-native-accelerator-search-json

Conversation

@SereinCin

@SereinCin SereinCin commented Aug 24, 2026

Copy link
Copy Markdown

Summary

Adds jmespath.search_json(expression, data) — search a JSON document given as a string.

The common workflow for CLI tools, streams and HTTP handlers is:

import json, jmespath
jmespath.search(expr, json.loads(body))

search_json() does exactly that, and when the optional native accelerator aero-jmespath is installed it runs the whole parse + eval + serialize pipeline in native code, skipping the Python-object round-trip:

jmespath.search_json(expr, body)

This is purely additive and backward compatible: without the accelerator the function falls back to json.loads() + search(), so no behaviour changes and no new dependency is required. Error behaviour is identical in both paths (ValueError for bad JSON, ParseError for a bad expression).

Benchmark

One-shot string-input pipeline (parse + eval + serialize per call), query servers[?status == \active`].instances[0].id on a synthetic server fleet, Windows 11 / Python 3.12. Fully reproducible with the public benchmark repo [aero-jmespath-bench](https://github.com/SereinCin/aero-jmespath-bench) (python run_all.py`):

document jmespath: json.loads + compiled.search search_json with aero-jmespath speedup
0.71 MB 6.47 ms 4.42 ms 1.46x
3.57 MB 42.63 ms 24.71 ms 1.72x
7.19 MB 100.50 ms 51.18 ms 1.96x

The speedup grows with document size. Beyond this one-shot case the accelerator also offers a batch path (aero_jmespath.multi) that parses one document once and evaluates many expressions against it (~1.75x in the benchmark), and its native JSON parser measures ~180 MB/s, faster than orjson (1.36x) and json.loads (1.70x) on the same document.

The accelerator is a native (Aero-compiled) JMESPath kernel that passes all 578 official compliance tests.

Tests

tests/test_search.py gains a TestSearchJson case class covering field access, projections, empty documents, invalid JSON, and matching search() on parsed documents. Full suite: 997 passed.

search_json(expression, data) queries a JSON document given as a string. When the optional aero-jmespath native accelerator is installed it runs parse + eval + serialize in native code; otherwise it falls back to json.loads() + search(). Purely additive: error behaviour is unchanged and no new dependency is required. Adds TestSearchJson coverage.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant