StepQL — the Query Language

Query any step's output to inspect a run — "which entities scored above 0.5", "count rows by type", "which rows did the next step drop". Queries are written in StepQL, a small YAML query language that compiles to JSONata:

from: entities
where: { field: score, gte: 0.5 }
sort: [{ field: score, dir: desc }]
select: [name, score]

Out of entities, keep rows scoring ≥ 0.5, sort by score descending, project name and score.

Why YAML

Raw JSONata is powerful but cryptic to author — $[type='Actor']{type:$count($)} isn't something you guess at. The YAML form turns each piece of a query into a named field, so the structure is obvious and the only invalid combinations are the ones the schema rejects up front. Humans and agents read the same shape, and the dashboard's editor offers query-keyword completion.

When the structured form isn't enough, drop into raw JSONata via the jsonata: field or --jsonata on the CLI. Same engine either way.

What's in this section

A query is a single object with up to eleven optional fields. The rest of this section walks through them:

• The query AST — every field, what it accepts, the two query modes, and the order stages run in.
• Filtering, sorting & projection — where and its operators, select shapes, sort, limit, distinct.
• Grouping & aggregation — groupBy, aggregate, having.
• Cross-step queries — reference other steps: membership sub-queries and relational joins.
• Raw JSONata & saved queries — the jsonata: escape hatch and how saved queries persist.

Each example shows the query, the JSONata it compiles to, and the result it returns against sample data.

Where to use it

• The q CLI command. YAML inline (the default) or a .yaml/.yml file; --jsonata for raw JSONata, --explain to see the compiled output. See the q reference.
• The dashboard's Query panel. A Monaco editor in YAML mode with query-keyword completion; raw JSONata via the jsonata: field. See The Dashboard.
• As a library. @stepbook/query exports compileQuery(source, lang?, baseStep?), which returns { kind: 'ok', jsonata } or { kind: 'error', message }. See Public API.