Module query 

Query language: tokenizer, AST, and recursive descent parser.

Implements the grammar from the project doc’s “Notes → Query language grammar” section, extended in v0.2.0 to support OR per the locked v0.2.0 scope (handoff doc + 2026-04-19 decisions log entry promising “OR ships in v2”).

This module owns only the parse step: &str → QueryNode. Translating a QueryNode into SQL and binding parameters is the executor’s job. Resolving relative time ranges like last 2h against wall-clock time is also the executor’s job; the AST just carries the raw spec.

Grammar (v0.2.0)

query     := or_expr
or_expr   := and_expr (OR and_expr)*
and_expr  := clause (AND clause)*
clause    := field OP value
           | field CONTAINS string
           | TIME_RANGE
field     := [a-zA-Z_][a-zA-Z0-9_.]*
OP        := "=" | "!=" | ">" | "<"
value     := string | number | bool
string    := '"' .* '"' | bare_word
TIME_RANGE := "last" duration | "since" datetime
duration  := number ("m" | "h" | "d")

AND binds tighter than OR, matching SQL convention. So level=error AND service=payments OR level=warn parses as (level=error AND service=payments) OR level=warn.

Explicit grouping with ( ) is not supported in v0.2.0 — users work with operator precedence only. Parens are a candidate for v0.3.

Structs

AndGroup

A conjunction of one or more clauses, joined by AND.

Duration

A relative duration parsed from last <N><unit>.

QueryParseError

Parse error with a byte offset into the original input.

Enums

Clause

A single clause — the atomic unit a query is built from.

CompareOp

Comparison operator for field OP value clauses.

DurationUnit

QueryNode

The top-level query: a disjunction of one or more AND-groups.

QueryValue

A literal value appearing on the right-hand side of a comparison.

Functions

parse

Parse a query string into a QueryNode.