package query-json

query-json is a faster, simpler and more portable implementation of the jq language in OCaml distributed as a binary, but also distributed as a JavaScript package via js_of_ocaml.

query-json allows you to write small programs to operate on top of json files with a concise syntax.

Purpose

It was created with mostly two reasons in mind, learning and having fun

• Learn how to write a programming language with the OCaml stack using menhir, sedlex and friends and try to make great error messages.
• Create a CLI tool in OCaml and being able to distribute it to twoo different platforms: as a binary (for performance) and as a JavaScript library (for portability).

What it brings

• Great Performance: Fast, small footprint and minimum runtime. Consistently 1.5x to 4.5x faster than jq depending on file size and operation. See Performance section for detailed benchmarks.

• Delightful errors:

  • Better errors when json types and operation don't match:

        $ query-json '.esy.release.wat' esy.json
    Error:  Trying to ".wat" on an object, that don't have the field "wat":
    { "bin": ... }

  • debug prints the tokens and the AST.
  • verbose flag, prints each operation in each state and it's intermediate states. (Work in progress...)
• Improved API: Snake_case function names, helpful aliases, and convenient additions. See jq Compatibility for details.
• Small: Lexer, Parser and Interpreter are just 1300 LOC

jq compatibility

query-json implements most of jq 1.8's functionality with some intentional improvements:

Improvements

Better naming - snake_case instead of alllowercase:

• to_number / to_string (instead of tonumber / tostring)
• starts_with / ends_with (instead of startswith / endswith)
• is_nan (instead of isnan)

Extra conveniences:

• filter(expr) - alias for map(select(expr))
• flat_map(expr) - map and flatten in one operation
• find(expr) - find first matching element
• some(expr) - check if at least one element matches
• unique - accepts both unique and uniq (jq only has uniq)
• JSON comments - supports comments in JSON input

Implemented features

• All basic filters (., .foo, .[], .[0], .[1:3], etc.)
• Operators (+, -, *, /, %, ==, !=, <, >, <=, >=, and, or, not)
• Conditionals (if-then-else)
• Pipes (|), comma (,), alternative (//)
• Core functions (map, select, length, keys, has, in, add, reverse, etc.)
• Array operations (sort, sort_by, unique, unique_by, group_by, flatten, min, max, etc.)
• String operations (split, join, startswith, endswith, contains, explode, implode)
• Type operations (type, to_number, to_string)
• Math functions (abs, floor, sqrt, ceil, round, sin, cos, tan, log, exp, etc.)
• Object operations (to_entries, from_entries, with_entries)
• Path operations (path, paths, getpath, setpath, del)
• Control flow (while, until, recurse, walk, limit, try-catch, reduce)
• Regex support (test, match, scan, capture, sub, gsub)

Not supported

User-defined functions (def), modules (import, include), format strings (@text, @csv, @base64), and running tests (--run-tests).

For a complete reference, see the jq manual.

Installation

Using a bash script

Check the content of scripts/install.sh before running anything in your local. Friends don't let friends curl | bash.

curl -sfL https://raw.githubusercontent.com/davesnx/query-json/master/scripts/install.sh | bash

Using npm

npm install --global @davesnx/query-json

Download zip files from GitHub

Usage

I recommend to write the query in single-quotes inside the terminal, since writting JSON requires double-quotes for accessing properties.

query a json file

query-json '.' pokemons.json

query from stdin

cat pokemons.json | query-json '.'
query-json '.' <<< '{ "bulvasur": { "id": 1, "power": 20 } }'

query a json inlined

query-json '.' '{ "bulvasur": { "id": 1, "power": 20 } }'

query without colors

query-json '.' pokemons.json --no-colors

query with raw output (strings without quotes)

query-json -r '.name' pokemon.json
# Output: Pikachu
# Instead of: "Pikachu"

More examples

Check out docs/examples.md for a walkthrough of common use cases.

Performance

query-json consistently outperforms jq 1.8.1 across most file sizes and operations, with performance improvements ranging from 1.5x to 4.5x faster depending on the file size and operation:

• Small files (< 10KB): 2.4-3x faster
• Medium files (100-500KB): 2-4.5x faster
• Large files (> 500KB): 1.6-3.3x faster
• Huge files (> 50MB): 1.5-1.8x faster

Why is query-json faster?

1. Native compilation: Compiled to optimized machine code with OCaml
2. Simpler runtime: Implementing a focused subset allows for optimization decisions not possible with jq's full feature set. The biggest missing pieces that might affect performance:

• User-defined functions (def) - intentional tradeoff for better performance
• Modules (import, include) - not implemented
• Format strings (@text, @csv, @base64, etc.) - not implemented
• Running tests - --run-tests

1. Tail-recursive architecture: OCaml optimizes piped recursive operations into tight loops
2. Fast parser: Uses Menhir, a high-performance LR(1) parser generator

For detailed benchmarks and methodology, see benchmarks/README.md.

Contributing

Contributions are what make the open source community such an amazing place to be, learn, inspire, and create. Any contributions you make are greatly appreciated. If you have any questions just contact me on x or email dsnxmoreno at gmail dot com.

Support

I usually hang out at discord.gg/reasonml feel free to DM.

Setup

Requirements: opam

git clone https://github.com/davesnx/query-json
cd query-json
make init # creates opam switch, installs ocaml deps and npm deps
make dev-core # compiles query-json "core" only
make test # runs unit tests and snapshots tests
dune exec query-json # Run binary

Running the playground

# In different terminals
make dev # compiles all packages "query-json" "query-json-js" and "query-json-playground", and runs the bundler
make web-dev # Runs bundler and the web server