jql

Start

Getting started

A query is a sequence of tokens read left to right. Each token narrows what came before it, so a query describes a path through the document.

Keys are always double-quoted, because any string is a valid JSON key — including .valid, the empty string, and a lone quote. That means a query needs single quotes in a shell, so the double quotes survive.

echo '{ "name": "jql" }' | jql '"name"'

Read a file by passing it after the query, or pipe into it:

jql '"name"' package.json
cat package.json | jql '"name"'

Reference

The grammar

Every token, with an example you can paste into a shell. Each output below was produced by running against the input beside it.

• Object keys
• Arrays
• Objects
• Operators
• Pipes
• Lenses
• Groups
• Putting it together

Object keys

The key selector is the one you will use most. Write selectors next to each other to walk down the document.

Arrays

Arrays are addressed by index or by range. Both accept several values, in any order you like.

Objects

Objects can be addressed by name, and also by position — useful when you know the shape but not the keys.

Operators

Four operators reshape what a selector returned rather than descending into it.

Pipes

A pipe applies the tokens that follow to every element of an array, then optionally collapses the result back to a single value.

Lenses

A lens filters an array, keeping the elements that match. It is the only token that removes elements rather than selecting them.

Groups

A comma splits a query into sub-queries, each run against the same input, collected into an array.

Putting it together

Real queries chain these pieces, and reading one from left to right tells you the whole pipeline. Every example below runs against this document:

Using it

Many documents

Input may hold more than one JSON document. Each is evaluated on its own and produces its own result.

Flags

Eight flags, all short. The full list is in jql --help.

Shell integration

jql eats JSON and writes JSON back, so it composes with everything else in a pipeline.

Save the output

jql '"repos"' input.json > output.json

Assign a value to a variable

Combine --raw-string with --inline so the result arrives without quotes or newlines:

name=$(jql -r -i '"name"' package.json)

Keep the query in a file

Long queries are easier to read, and to version, when they live on disk:

jql --query ./select-repos.jql input.json

Follow a stream

Without --stream the whole input is read before anything is written, which is right for a file or a finished pipe. With it, each line is processed as it arrives — for output still being produced:

docker logs --follow my-container | jql --stream '"message"'

It expects one document per line. A document spread over several lines needs the default mode.

Check exit codes

jql --validate input.json && echo "valid"

Installation

Packaged for most platforms, or grab a prebuilt binary.

Prebuilt binaries for Linux, macOS and Windows are attached to every release.

Good to know

Errors say what went wrong

A failed selection reports the token that failed and the value it was applied to, rather than returning null and leaving you to guess.

It is not jq

There is no plan to align jql with jq or any similar tool. jql selects and reshapes; it has no expression language, no arithmetic and no user-defined functions, and that is deliberate.

Speed

Selection queries run against a simd-json tape, so only the part of the document a query actually selects is ever built. Measurements against jq live in PERFORMANCE.md.