Query Builder

Demo & usage

More examples

When to use

• Letting a user build an arbitrary AND/OR filter — support tooling, saved searches, audience/segment builders.
• You need the filter itself to be saved, shared or replayed (`svSerializeQuery()` / `svImportQuery()`), not just applied once — the JSON carries a schema version, so a query saved last release is migrated or refused with a reason rather than read as the current shape.
• For a single row of per-column filters ANDed together, a data-table's own column filters or `sv-filter-panel`'s facets are lighter weight — `SvDataQuery.filters` is deliberately flat, which is why this ships its own richer expression type.

Async states

• loading
• empty
• error
• retry

Saved state

Stored kinds

• sv-query-builder/query

What you will find under your own storage key. You choose the key; the blob names its own kind and schema version, so a component never reads state another one wrote.

Reading it back

Restore through the component's own restore… helper rather than casting the parsed JSON. A blob from an older release is migrated where it can be and refused with a reason where it cannot — so an upgrade never silently applies last month's shape to this month's fields.

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — it just saves you writing the debounce, the request guard and the retry policy by hand.

• `queryChange` carries an `SvDataQuery` — page, page size, sorts, filters, search and cursor in one object. One handler covers every way the user can change what they are asking for.
• `debounceMs` (default 300) collapses a burst of typing into one request. Set it to 0 only when the query is driven by clicks.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Five field types (string / number / date / enum / boolean), each with its own operator set and value editor (single, range, multi-select, or none for `is true`/`is empty`).
• Unlimited rules per group; groups nest up to `maxDepth`.
• `svImportQuery()` degrades gracefully when a saved query's field schema has drifted — an unknown field clears the whole rule, a field whose saved operator no longer fits keeps the field and clears only the operator/value — and reports both in `result.report` so the user can be told. `svParseQuery()` is the forgiving form for a caller with nowhere to show a message.
• **Operator/type pairing is enforced, not just offered.** The dropdown was the only thing obeying it, so `applyQueryAction` stored whatever it was handed and "age contains 5" round-tripped through export, import and `queryChange` as a real filter. An action that would put a rule in a state no field can hold is now a no-op — and a refused action emits nothing, because a query that did not change is not a reason to refetch. `isOperatorValidFor()` and `ruleProblem()` are exported for a host validating a query it built itself.
• **A plain-language preview** above the rows: "Reads as: Plan is “Pro” and Signed up after 1 Jun 2026." Enum values read by their label, dates as the day the user picked, a nested group bracketed only when it holds more than one condition, and an unfinished rule named rather than skipped — a preview that reads as a finished sentence while the query cannot run is a worse trap than none.

Best practices

• Do: Wire `(queryChange)` (already debounced) to a refetch, not `[(expression)]` directly — the model updates on every keystroke so the UI stays responsive, but a refetch should not.
• Do: Set `maxDepth` to whatever nesting your backend can actually translate — three levels covers nearly every real filter without becoming unreadable.
• Tip: The built-in Export/Import panel round-trips through the same `svSerializeQuery()` / `svImportQuery()` the package exports, so "save this search" and "load a saved search" need no extra code — and it shows what an import had to change, rather than accepting a query that now means something else.
• Do: **Translate through `svQueryToPredicate()`, and bind its `params`.** This component escapes nothing and produces no query language — that is the boundary it does not cross, and your translation is the other side of it, where a value the user typed becomes code. The predicate hands over your own field ids and a closed operator set (safe to map through your own lookup tables) separately from `params`, which are the user's raw input and must go into a placeholder — `?`, `$1`, a driver's parameter object. Concatenating `params` into SQL is an injection in a component whose whole job is collecting strings from a user.
• Do: Set `timeZone` to the zone your **data** is reckoned in whenever that is not the reader's own — a date rule is a calendar day and a stored row is an instant, so which day a row near midnight falls on depends on it. `svDateRuleWindow()` does the conversion with the same zone, and the preview names the zone in use so the user can see which calendar they are filtering in.
• Don't: Don't fetch on a query `svQueryToPredicate()` returned `null` for. An unfinished rule would translate to a comparison against the empty string — a filter that runs, matches nothing, and looks like an empty table rather than a mistake.

Accessibility

• Every field / operator / value control is a native `<select>`/`<input>`, so keyboard and screen-reader support come for free.
• Add/remove rule and group buttons are labelled buttons, not icon-only.
• Loading, error and empty states for `[fields]` follow the kit-wide async contract (`data-sv-state`) — the expression itself is always local, synchronous state.
• Nested AND/OR is the part of this component a non-technical user cannot check their own work on — the rails and indentation say where a group begins and nothing said what the whole query would *do*. The preview says it, in one sentence.
• An unfinished condition says what it needs **on the row**, and the row's field control is `aria-describedby` it, so the reason is read out with the control. The toolbar's "some conditions are incomplete" is true of the query and useless about the rule: in three nested groups it left the user checking every row by eye.
• The preview is deliberately not a live region — it restates the whole query, so `aria-live` would re-read every condition on each keystroke of a value.