QueryBuilder
A visual AND/OR predicate-tree builder — compose nested conditions over a set of fields and serialize them to JSON or a LINQ predicate.
When to Use
- Let users build advanced filters or saved searches over a dataset.
- Capture rules for report definitions, automation triggers, segmentation, or audience targeting.
- Produce a structured query you can send to a backend (the JSON shape) or run client-side (the LINQ predicate).
- For a single column's quick filter, prefer the DataGrid's built-in column filter; reach for QueryBuilder when conditions span multiple fields with nested AND/OR logic.
JSON
{
"combinator": "And",
"rules": [
{
"$type": "rule",
"field": "plan",
"operator": "=",
"value": "pro",
"value2": null
},
{
"$type": "rule",
"field": "isActive",
"operator": "=",
"value": true,
"value2": null
}
]
}and
API Reference
QueryBuilder
| Property | Type | Default | Description |
|---|---|---|---|
| Fields | IReadOnlyList<QueryField> | [] | The fields the user can build conditions against. Required. |
| Query | QueryGroup? | null | The query tree. Use with @bind-Query. When null on first render, an empty root group (And, no rules) is created. |
| QueryChanged | EventCallback<QueryGroup> | — | Fires whenever the tree changes (add/remove rule or group, combinator, field, operator, value). |
| ShowJsonPreview | bool | false | When true, renders a read-only JSON view of the query below the builder. |
| MaxDepth | int | 5 | Maximum group nesting depth. "Add group" is disabled at this depth. |
| AllowEmptyGroups | bool | true | When false, "Remove rule"/"Remove group" are hidden when removal would leave a group empty (the root may always be empty). |
| ValueEditorTemplate | RenderFragment<QueryRule>? | null | Optional override for a rule's value editor. When set, replaces the built-in per-type editor; the consumer binds to QueryRule.Value and notifies via the cascaded context. |
| Class | string? | null | Extra CSS classes for the root element. |
Static helpers: QueryBuilder.ToJson(query) · QueryBuilder.FromJson(json) · QueryBuilder.ToExpression<T>(query) (returns Expression<Func<T,bool>>? — null for an empty tree).
QueryField
| Property | Type | Description |
|---|---|---|
| Name | string | Stable key written to QueryRule.Field. Required. |
| Label | string? | Human-facing label in the field picker. Falls back to Name. |
| Type | QueryFieldType | Text, Number, Date, Boolean, or Select. Determines the default operator set and the built-in value editor. |
| Operators | IReadOnlyList<string>? | Allowed operator keys. Null = the default set for Type. |
| Options | IReadOnlyList<(string Value, string Label)>? | Options shown when Type is Select. |
QueryRule / QueryGroup / QueryNode
| Member | Type | Description |
|---|---|---|
| QueryNode | abstract | Base of the tree — either a QueryRule (leaf) or a QueryGroup (branch). |
| QueryRule.Field | string | The QueryField.Name this rule targets. |
| QueryRule.Operator | string | One of the field's allowed operator keys. |
| QueryRule.Value / Value2 | object? | The comparison value(s). Value2 is used only by range operators ("between"). |
| QueryGroup.Combinator | QueryCombinator | And or Or — applied across Rules. |
| QueryGroup.Rules | List<QueryNode> | Child rules and/or nested groups. |
| QueryGroup.CreateEmpty() | static | A new empty root group (And, no rules). |
Default operator sets
| Field type | Operators (key → label) |
|---|---|
| Text | = equals, != not equals, contains, notContains, startsWith, endsWith, isEmpty, isNotEmpty |
| Number | =, !=, < less than, <=, > greater than, >=, between, isNull, isNotNull |
| Date | =, !=, <, <=, >, >=, between, isNull, isNotNull |
| Boolean | =, != |
| Select | =, !=, in, notIn, isNull, isNotNull (in/notIn take a comma-separated value) |
isEmpty / isNotEmpty / isNull / isNotNull render no value editor; between renders two. Override the set per field via QueryField.Operators.