KelpQL Cheat Sheet
KelpQL is a JSON query language that is based on JMESPath. This cheat sheet provides a quick reference to all the important concepts and syntax of KelpQL. For a more comprehensive overview of the KelpQL specification, please refer to the KelpQL specification.
Need help? Join our Kelp community on Slack.
Navigation & Selectors
| Pattern | Purpose |
|---|---|
@ | Current node (the default input). |
$ | Root of the JSON document (useful inside deeply‑nested pipes). |
* | Wildcard – matches any key or array element. |
.<key> | Dot‑notation field lookup (user.name). |
"<key>" | Quoted identifier for keys with spaces / symbols. |
[<index>] | Positional array index (negative for reverse). |
[<start>:<end>:<step>] | Python‑style array slice. |
[*] | Projection – keep original structure. |
[] | Flatten one level (removes the outer array). |
[?<expr>] | Filter – include items where expression is truthy. |
Expression Building
| Operator / Form | Meaning |
|---|---|
<expr1>.<expr2> | Sub‑expression chaining. |
<expr1> | <expr2> | Pipe – pass the result of the left expr into the right; stops automatic projections. Precedence: lowest. |
(<expr>) | Parentheses to override precedence. |
<expr1> || <expr2> | Logical OR (returns first truthy value). |
<expr1> && <expr2> | Logical AND. |
!<expr> | Logical NOT. |
Comparison: == != < <= > >= | Compare scalars or arrays/objects (deep equality). |
Multi‑select list [expr1, expr2, …] | Return an array of results. |
Multi‑select hash {name: expr1, size: expr2} | Return an object with explicit keys. |
Literals & Constants
| Syntax | Example | Notes |
|---|---|---|
| Back‑tick JSON literal | `{"ok":true}` | Embed arbitrary JSON. |
| Raw string | 'C:\path\to\file' | No escaping apart from ' and \. |
Numbers / booleans / null | 42, true, null | Standard JSON scalars. |
Functions
Over 200 built‑in functions grouped by category (Array, Collection, Date, Lang, Math, Number, Object, String, Util). Pass another expression by reference with &expr (type expression) – great for comparators & iteratees.
Call syntax: func(arg1, arg2, …).
| Example | Notes |
|---|---|
map(users, &upper(name)) | Apply upper() to every user’s name. |
sort_by(files, &size) | Sort objects by “size” field. |
difference(arr1, arr2, &@.id) | Custom comparator based on id. |
Browse functions in the docs sidebar.
Falsy / Truthy rules
Falsy values: [] {} "" false null ( 0 is truthy, unlike some JS APIs). Everything else is truthy.
Operator Precedence (low → high)
| → || → && → ! → ] (inside bracketed selectors)
Quick Examples
| Expression | Result (given the comment JSON) |
|---|---|
@ | Entire input. |
people[*].name | Array of every person’s name. |
people[?age > 18].name | Names of adults. |
people[0:10:2].name | Names at even positions ≤ 9. |
people[?name == 'Alice'].{id: id, email: email} | Object for Alice with selected fields. |
files[].size | max(@) | Biggest file size (after flattening). |
orders[].items[] | group_by(&category) | Pipe plus function chaining. |
Need help?
- Full docs & interactive examples: Kelp QL
- Ask questions in the #kelp-ql channel → Kelp Slack community