Experimental JSONPath engine for querying massive streamed datasets.
The rsonpath
crate provides a JSONPath parser and a query execution engine rq
,
which utilizes SIMD instructions to provide massive throughput improvements over conventional engines.
Benchmarks of rsonpath
against a reference no-SIMD engine on the
Pison dataset. NOTE: Scale is logarithmic!
To run a JSONPath query on a file execute:
rq '$..a.b' ./file.json
If the file is omitted, the engine reads standard input. JSON can also be passed inline:
$ rq '$..a.b' --json '{"c":{"a":{"b":42}}}'
42
For details, consult rq --help
or the rsonbook.
The result of running a query is a sequence of matched values, delimited by newlines.
Alternatively, passing --result count
returns only the number of matches, which might be much faster.
For other result modes consult the --help
usage page.
See Releases for precompiled binaries for all first-class support targets.
Easiest way to install is via cargo
.
$ cargo install rsonpath
...
If maximum speed is paramount, you should install rsonpath
with native CPU instructions support.
This will result in a binary that is not portable and might work incorrectly on any other machine,
but will squeeze out every last bit of throughput.
To do this, run the following cargo install
variant:
$ RUSTFLAGS="-C target-cpu=native" cargo install rsonpath
...
Check out the relevant chapter in the rsonbook.
The project is actively developed and currently supports only a subset of the JSONPath query language. A query is a sequence of segments, each containing one or more selectors.
Segment | Syntax | Supported | Since | Tracking Issue |
---|---|---|---|---|
Child segment (single) | [<selector>] |
โ๏ธ | v0.1.0 | |
Child segment (multiple) | [<selector1>,...,<selectorN>] |
โ | ||
Descendant segment (single) | ..[<selector>] |
โ๏ธ | v0.1.0 | |
Descendant segment (multiple) | ..[<selector1>,...,<selectorN>] |
โ |
Selector | Syntax | Supported | Since | Tracking Issue |
---|---|---|---|---|
Root | $ |
โ๏ธ | v0.1.0 | |
Name | .<member> , [<member>] |
โ๏ธ | v0.1.0 | |
Wildcard | .* , ..* , [*] |
โ๏ธ | v0.4.0 | |
Index (array index) | [<index>] |
โ๏ธ | v0.5.0 | |
Index (array index from end) | [-<index>] |
โ | ||
Array slice (forward, positive bounds) | [<start>:<end>:<step>] |
โ | #152 | |
Array slice (forward, arbitrary bounds) | [<start>:<end>:<step>] |
โ | ||
Array slice (backward, arbitrary bounds) | [<start>:<end>:-<step>] |
โ | ||
Filters โ existential tests | [?<path>] |
โ | #154 | |
Filters โ const atom comparisons | [?<path> <binop> <atom>] |
โ | #156 | |
Filters โ logical expressions | && , || , ! |
โ | ||
Filters โ nesting | [?<expr>[?<expr>]...] |
โ | ||
Filters โ arbitrary comparisons | [?<path> <binop> <path>] |
โ | ||
Filters โ function extensions | [?func(<path>)] |
โ |
The crate is continuously built for all Tier 1 Rust targets, and tests are continuously ran for targets that can be ran with GitHub action images. SIMD is supported only on x86/x86_64 platforms.
Target triple | nosimd build | SIMD support | Continuous testing | Tracking issues |
---|---|---|---|---|
aarch64-unknown-linux-gnu | โ๏ธ | โ | โ | #21, #115 |
i686-unknown-linux-gnu | โ๏ธ | โ๏ธ | โ๏ธ | |
x86_64-unknown-linux-gnu | โ๏ธ | โ๏ธ | โ๏ธ | |
x86_64-apple-darwin | โ๏ธ | โ๏ธ | โ๏ธ | |
i686-pc-windows-gnu | โ๏ธ | โ๏ธ | โ๏ธ | |
i686-pc-windows-msvc | โ๏ธ | โ๏ธ | โ๏ธ | |
x86_64-pc-windows-gnu | โ๏ธ | โ๏ธ | โ๏ธ | |
x86_64-pc-windows-msvc | โ๏ธ | โ๏ธ | โ๏ธ |
SIMD support is enabled on a module-by-module basis. Generally, any CPU released in the past decade supports AVX2, which enables all available optimizations.
Older CPUs with SSE2 or higher get partial support. You can check what exactly is enabled
with rq --version
โ check the SIMD support
field:
$ rq --version
rq 0.8.3
Commit SHA: be6abb7fc8a3a9342876d01cad2388c10f5751e3
Features: default,simd
Opt level: 3
Target triple: x86_64-unknown-linux-gnu
Codegen flags: link-arg=-fuse-ld=lld
SIMD support: avx2;fast_quotes;fast_popcnt
The fast_quotes
capability depends on the pclmulqdq
instruction,
and fast_popcnt
on the popcnt
instruction.
Not all selectors are supported, see the support table above.
The engine assumes that every object in the input JSON has no duplicate keys. Behavior on duplicate keys is not guaranteed to be stable, but currently the engine will simply match the first such key.
$ rq '$.key' --json '{"key":"value","key":"other value"}'
"value"
The engine does not parse unicode escape sequences in member names.
This means that a key "a"
is different from a key "\u0041"
, even though semantically they represent the same string.
This is actually as-designed with respect to the current JSONPath spec.
Parsing unicode sequences is costly, so the support for this was postponed
in favour of high performance. This is tracked as #117.
The gist is: fork, implement, make a PR back here. More details are in the CONTRIBUTING doc.
The dev workflow utilizes just
.
Use the included Justfile
. It will automatically install Rust for you using the rustup
tool if it detects there is no Cargo in your environment.
$ just build
...
$ just test
...
Benchmarks for rsonpath
are located in a separate repository,
included as a git submodule in this main repository.
Easiest way to run all the benchmarks is just bench
. For details, look at the README in the submodule.
We have a paper on rsonpath
to be published at ASPLOS '24! You can read it
here.
This project was conceived as my thesis. You can read it for details on the theoretical background on the engine and details of its implementation.
Showing direct dependencies, for full graph see below.
cargo tree --package rsonpath --edges normal --depth 1
rsonpath v0.8.3 (/home/mat/rsonpath/crates/rsonpath)
โโโ clap v4.4.6
โโโ color-eyre v0.6.2
โโโ eyre v0.6.8
โโโ log v0.4.20
โโโ rsonpath-lib v0.8.3 (/home/mat/rsonpath/crates/rsonpath-lib)
โโโ simple_logger v4.2.0
[build-dependencies]
โโโ rustflags v0.1.4
โโโ vergen v8.2.5
[build-dependencies]
cargo tree --package rsonpath-lib --edges normal --depth 1
rsonpath-lib v0.8.3 (/home/mat/rsonpath/crates/rsonpath-lib)
โโโ cfg-if v1.0.0
โโโ log v0.4.20
โโโ memmap2 v0.9.0
โโโ nom v7.1.3
โโโ smallvec v1.11.1
โโโ static_assertions v1.1.0
โโโ thiserror v1.0.49
โโโ vector-map v1.0.1
clap
โ standard crate to provide the CLI.color-eyre
,eyre
โ more accessible error messages for the parser.log
,simple-logger
โ diagnostic logs during compilation and execution.cfg-if
โ used to support SIMD and no-SIMD versions.memmap2
โ for fast reading of source files via a memory map instead of buffered copies.nom
โ for parser implementation.smallvec
โ crucial for small-stack performance.static_assertions
โ additional reliability by some constant assumptions validated at compile time.thiserror
โ idiomaticError
implementations.vector_map
โ used in the query compiler for measurably better performance.
cargo tree --package rsonpath --edges normal
rsonpath v0.8.3 (/home/mat/rsonpath/crates/rsonpath)
โโโ clap v4.4.6
โ โโโ clap_builder v4.4.6
โ โ โโโ anstream v0.6.4
โ โ โ โโโ anstyle v1.0.4
โ โ โ โโโ anstyle-parse v0.2.2
โ โ โ โ โโโ utf8parse v0.2.1
โ โ โ โโโ anstyle-query v1.0.0
โ โ โ โ โโโ windows-sys v0.48.0
โ โ โ โ โโโ windows-targets v0.48.1
โ โ โ โ โโโ windows_aarch64_gnullvm v0.48.0
โ โ โ โ โโโ windows_aarch64_msvc v0.48.0
โ โ โ โ โโโ windows_i686_gnu v0.48.0
โ โ โ โ โโโ windows_i686_msvc v0.48.0
โ โ โ โ โโโ windows_x86_64_gnu v0.48.0
โ โ โ โ โโโ windows_x86_64_gnullvm v0.48.0
โ โ โ โ โโโ windows_x86_64_msvc v0.48.0
โ โ โ โโโ anstyle-wincon v3.0.1
โ โ โ โ โโโ anstyle v1.0.4
โ โ โ โ โโโ windows-sys v0.48.0 (*)
โ โ โ โโโ colorchoice v1.0.0
โ โ โ โโโ utf8parse v0.2.1
โ โ โโโ anstyle v1.0.4
โ โ โโโ clap_lex v0.5.1
โ โ โโโ strsim v0.10.0
โ โ โโโ terminal_size v0.3.0
โ โ โโโ rustix v0.38.15
โ โ โ โโโ bitflags v2.4.0
โ โ โ โโโ errno v0.3.4
โ โ โ โ โโโ errno-dragonfly v0.1.2
โ โ โ โ โ โโโ libc v0.2.148
โ โ โ โ โ [build-dependencies]
โ โ โ โ โ โโโ cc v1.0.83
โ โ โ โ โ โโโ libc v0.2.148
โ โ โ โ โโโ libc v0.2.148
โ โ โ โ โโโ windows-sys v0.48.0 (*)
โ โ โ โโโ libc v0.2.148
โ โ โ โโโ linux-raw-sys v0.4.8
โ โ โ โโโ windows-sys v0.48.0 (*)
โ โ โโโ windows-sys v0.48.0 (*)
โ โโโ clap_derive v4.4.2 (proc-macro)
โ โโโ heck v0.4.1
โ โโโ proc-macro2 v1.0.67
โ โ โโโ unicode-ident v1.0.12
โ โโโ quote v1.0.33
โ โ โโโ proc-macro2 v1.0.67 (*)
โ โโโ syn v2.0.37
โ โโโ proc-macro2 v1.0.67 (*)
โ โโโ quote v1.0.33 (*)
โ โโโ unicode-ident v1.0.12
โโโ color-eyre v0.6.2
โ โโโ backtrace v0.3.69
โ โ โโโ addr2line v0.21.0
โ โ โ โโโ gimli v0.28.0
โ โ โโโ cfg-if v1.0.0
โ โ โโโ libc v0.2.148
โ โ โโโ miniz_oxide v0.7.1
โ โ โ โโโ adler v1.0.2
โ โ โโโ object v0.32.1
โ โ โ โโโ memchr v2.6.4
โ โ โโโ rustc-demangle v0.1.23
โ โ [build-dependencies]
โ โ โโโ cc v1.0.83 (*)
โ โโโ eyre v0.6.8
โ โ โโโ indenter v0.3.3
โ โ โโโ once_cell v1.18.0
โ โโโ indenter v0.3.3
โ โโโ once_cell v1.18.0
โ โโโ owo-colors v3.5.0
โโโ eyre v0.6.8 (*)
โโโ log v0.4.20
โโโ rsonpath-lib v0.8.3 (/home/mat/rsonpath/crates/rsonpath-lib)
โ โโโ cfg-if v1.0.0
โ โโโ log v0.4.20
โ โโโ memmap2 v0.9.0
โ โ โโโ libc v0.2.148
โ โโโ nom v7.1.3
โ โ โโโ memchr v2.6.4
โ โ โโโ minimal-lexical v0.2.1
โ โโโ smallvec v1.11.1
โ โโโ static_assertions v1.1.0
โ โโโ thiserror v1.0.49
โ โ โโโ thiserror-impl v1.0.49 (proc-macro)
โ โ โโโ proc-macro2 v1.0.67 (*)
โ โ โโโ quote v1.0.33 (*)
โ โ โโโ syn v2.0.37 (*)
โ โโโ vector-map v1.0.1
โ โโโ contracts v0.4.0 (proc-macro)
โ โ โโโ proc-macro2 v1.0.67 (*)
โ โ โโโ quote v1.0.33 (*)
โ โ โโโ syn v1.0.109
โ โ โโโ proc-macro2 v1.0.67 (*)
โ โ โโโ quote v1.0.33 (*)
โ โ โโโ unicode-ident v1.0.12
โ โโโ rand v0.7.3
โ โโโ getrandom v0.1.16
โ โ โโโ cfg-if v1.0.0
โ โ โโโ libc v0.2.148
โ โ โโโ wasi v0.9.0+wasi-snapshot-preview1
โ โโโ libc v0.2.148
โ โโโ rand_chacha v0.2.2
โ โ โโโ ppv-lite86 v0.2.17
โ โ โโโ rand_core v0.5.1
โ โ โโโ getrandom v0.1.16 (*)
โ โโโ rand_core v0.5.1 (*)
โ โโโ rand_hc v0.2.0
โ โโโ rand_core v0.5.1 (*)
โโโ simple_logger v4.2.0
โโโ colored v2.0.4
โ โโโ is-terminal v0.4.9
โ โ โโโ hermit-abi v0.3.3
โ โ โโโ rustix v0.38.15 (*)
โ โ โโโ windows-sys v0.48.0 (*)
โ โโโ lazy_static v1.4.0
โ โโโ windows-sys v0.48.0 (*)
โโโ log v0.4.20
โโโ time v0.3.29
โ โโโ deranged v0.3.8
โ โโโ itoa v1.0.9
โ โโโ libc v0.2.148
โ โโโ num_threads v0.1.6
โ โ โโโ libc v0.2.148
โ โโโ time-core v0.1.2
โ โโโ time-macros v0.2.15 (proc-macro)
โ โโโ time-core v0.1.2
โโโ windows-sys v0.42.0
โโโ windows_aarch64_gnullvm v0.42.2
โโโ windows_aarch64_msvc v0.42.2
โโโ windows_i686_gnu v0.42.2
โโโ windows_i686_msvc v0.42.2
โโโ windows_x86_64_gnu v0.42.2
โโโ windows_x86_64_gnullvm v0.42.2
โโโ windows_x86_64_msvc v0.42.2
[build-dependencies]
โโโ rustflags v0.1.4
โโโ vergen v8.2.5
โโโ anyhow v1.0.75
โโโ rustc_version v0.4.0
โ โโโ semver v1.0.19
โโโ time v0.3.29
โโโ deranged v0.3.8
โโโ itoa v1.0.9
โโโ libc v0.2.148
โโโ num_threads v0.1.6 (*)
โโโ time-core v0.1.2
[build-dependencies]
โโโ rustversion v1.0.14 (proc-macro)