Filter language¶
DV Forge uses one filter language everywhere you select signatures: the Triage page, saved searches, triage rule conditions and scopes, rule previews, CSV export, and the API. Because it's one language, a rule matches exactly what the same search shows. This page is the complete reference: the grammar, every field and operator, how values are written, how empty fields behave, the limits, and worked examples.
In the app you build filters with rows of field, operator and value (see Build a filter); this page shows the JSON the rows produce, which is also what the API accepts.
Grammar¶
A filter is a JSON object of one of four shapes:
| Shape | Meaning |
|---|---|
{"all": [expr, ...]} |
Every child holds. An empty list always holds. |
{"any": [expr, ...]} |
At least one child holds. An empty list never holds. |
{"not": expr} |
The child doesn't hold. |
{"field": "...", "op": "...", "value": ...} |
A condition on one field. value is omitted for is_null and not_null. |
Groups nest:
{"all": [
{"field": "status", "op": "in", "value": ["untriaged", "regressed"]},
{"not": {"field": "classification", "op": "eq", "value": "infra"}}
]}
Unknown keys, unknown fields, operators a field doesn't support, values of the wrong type and unknown enum values are all refused with a message that names the offending spot, for example:
Fields¶
| Field | Shown as | Kind | Operators | Values |
|---|---|---|---|---|
text |
Text | text | contains, not_contains |
Searches the title, template and message id together. |
title |
Title | text | text operators | |
template |
Template | text | text operators | The normalized error message the signature groups on. |
msg_id |
Message id | text | text operators | |
severity |
Severity | text | text operators | |
signature_key |
Signature key | text | text operators | |
bug_ref |
Bug | text | text operators | The linked bug key or URL. |
status |
Status | enum | eq, ne, in, not_in |
untriaged, investigating, root_caused, tracked, resolved, regressed, muted, not_a_bug, waived |
classification |
Classification | enum | eq, ne, in, not_in |
rtl, dv, infra, tool, unknown |
classification_source |
Classified by | enum | eq, ne, in, not_in |
rule (DV Forge's automatic classification), user (a person), triage_rule (one of your triage rules), agent (reserved; nothing sets it today) |
agent_state |
Agent | enum | eq, ne, in, not_in |
running, complete, failed (empty when no root-cause run was launched) |
failure_count |
Hits | int | number operators | |
regression_count |
Regressions | int | number operators | Regressions it was seen in. |
recurrence_count |
Recurrences | int | number operators | Times it came back after an absence. |
first_seen_at |
First seen | time | time operators | |
last_seen_at |
Last seen | time | time operators | |
last_recurred_at |
Last recurred | time | time operators | |
status_changed_at |
Status changed | time | time operators | |
created_at |
Created | time | time operators | |
assignee |
Assignee | user | eq, ne, in, not_in, is_null, not_null |
A member's user id, or "me". |
watcher |
Watcher | user | eq, ne, in, not_in |
A member's user id, or "me". |
label |
Label | related | related operators | A label id, or a label name (any case). |
branch |
Branch | related | related operators | Branch names of the regressions it was seen in. |
test |
Test | related | related operators | Names of the tests that hit it. |
component |
Component | related | related operators | Components recorded on the failing simulation jobs. |
regression |
Regression | related | related operators | Ids of the regressions it was seen in. |
Operator groups:
- text operators:
eq,ne,in,not_in,contains,not_contains,starts_with,is_null,not_null - number operators:
eq,ne,gt,gte,lt,lte - time operators:
before,after,within,not_within,is_null,not_null - related operators:
eq,ne,in,not_in,contains
GET /v1/filters/fields returns this catalog (field, label, kind, operators,
enum values) as JSON.
Operators¶
| Operator | Shown as | Value | Matches |
|---|---|---|---|
eq |
is | one value | Equal. For related fields: has this value. |
ne |
is not | one value | Not equal, including empty. For related fields: doesn't have this value. |
in |
is any of | non-empty list | Equal to one of the values (related: has one of them). |
not_in |
is none of | non-empty list | Equal to none of them, including empty (related: has none of them). |
contains |
contains | text | Contains the text, ignoring case. For related fields: any value contains it. |
not_contains |
doesn't contain | text | Doesn't contain the text, ignoring case, including empty. |
starts_with |
starts with | text | Starts with the text, ignoring case. |
is_null |
is empty | none | Has no value. |
not_null |
is set | none | Has a value. |
gt / gte |
more than / at least | integer | Greater than / greater than or equal. |
lt / lte |
fewer than / at most | integer | Less than / less than or equal. |
before / after |
before / after | ISO 8601 time | Strictly before / after the time. |
within |
in the last | duration | At or after now minus the duration. |
not_within |
not in the last | duration | Before now minus the duration, or empty. |
Matching details:
eq,ne,inandnot_inon text and related fields compare exactly, including case. Labels are the exception: a label value matches either the label's id or its name, ignoring case.contains,not_containsandstarts_withignore case and treat%and_as ordinary characters.textwithcontainsmatches if the title, template or message id contains the text; withnot_contains, if none of them do.
Values¶
| Kind | How to write it |
|---|---|
| Text, enum, related, user | A JSON string, up to 256 characters. contains, not_contains and starts_with need a non-empty string. |
| int | A JSON integer: 3, not "3". true/false are refused. |
time, with before / after |
An ISO 8601 time: "2026-11-01T00:00:00Z", "2026-11-01T09:30:00+01:00". A time without a zone is read as UTC. |
time, with within / not_within |
A duration: 1 to 4 digits and a unit, m (minutes), h (hours), d (days) or w (weeks). For example "30m", "12h", "7d", "2w". |
Lists (in, not_in) |
A non-empty JSON array of up to 100 values of the field's kind. |
Relative times¶
within and not_within count back from now. What now means depends on
where the filter runs:
- Triage page, Signatures API, CSV export, saved searches and rule previews: the current time.
- Triage rules: the start time of the regression that fired the trigger, so a rule evaluates the same way however late it runs. (For the root-cause run trigger, which has no regression, it's the time the rule runs.)
"me"¶
"me" on assignee or watcher means the signed-in person running the
search. It's resolved each time the search runs, so a shared saved search with
"me" shows each colleague their own signatures.
Rules run without a signed-in person, so rule conditions, and shared saved
searches that a rule scopes to, can't use "me". API tokens aren't a person
either: a filter with "me" sent with an API token is refused.
Labels by id or name¶
{"field": "label", "op": "eq", "value": "flaky"} matches a label named
flaky, Flaky or FLAKY. A label id works too, and keeps working if the
label is renamed. The app's builder stores label ids for that reason.
Empty fields¶
Many fields can be empty: no assignee, no bug, no root-cause run, never recurred. The rules:
- Positive operators (
eq,in,contains,starts_with,before,after,within, comparisons) never match an empty field. - The negative operators
ne,not_in,not_containsandnot_withindo match an empty field.{"field": "bug_ref", "op": "ne", "value": "HW-1"}includes signatures with no bug at all. - Under
not, an empty field counts as not matching the inner condition, so thenotincludes it.{"not": {"field": "agent_state", "op": "eq", "value": "running"}}includes signatures that never had a root-cause run. - Use
is_nullandnot_nullto ask about emptiness directly.
Limits¶
| Limit | Value |
|---|---|
| Nesting depth | 8 levels (the outer object is level 1) |
| Size | 64 nodes in total, counting conditions and all/any/not groups |
List values (in, not_in) |
100 |
| String values | 256 characters |
A filter in a URL (filter= parameter) |
8,192 characters |
| Rows in the app's filter builder | 20 (nested groups are kept as-is) |
Where it's used¶
| Where | How |
|---|---|
| Triage page | The Filter card builds it; the page URL carries it as /triage?filter=<JSON>. |
| Signatures API | GET /v1/signatures?filter=<JSON>, alongside the simple q, status and classification parameters. |
| CSV export | GET /v1/signatures/export.csv?filter=<JSON>, and Export CSV on the Triage page. |
| Saved searches | The filter of POST / PATCH /v1/saved-searches. |
| Triage rules | A rule's match (Conditions), and the saved search it scopes to. |
| Rule preview | POST /v1/triage-rules/preview, the editor's Would match N. |
Searches and exports only return live signatures: not merged into another, with at least one hit.
Examples¶
Open work (the Triage page's default view):
{"all": [{"field": "status", "op": "in",
"value": ["untriaged", "investigating", "root_caused", "tracked", "regressed"]}]}
My regressions:
{"all": [
{"field": "assignee", "op": "eq", "value": "me"},
{"field": "status", "op": "eq", "value": "regressed"}
]}
New and unowned in the last day:
{"all": [
{"field": "status", "op": "eq", "value": "untriaged"},
{"field": "assignee", "op": "is_null"},
{"field": "first_seen_at", "op": "within", "value": "24h"}
]}
Timeouts that aren't infrastructure:
{"all": [
{"field": "text", "op": "contains", "value": "timeout"},
{"field": "classification", "op": "ne", "value": "infra"}
]}
Seen on any release branch:
Keeps coming back: three or more recurrences, the latest this week.
{"all": [
{"field": "recurrence_count", "op": "gte", "value": 3},
{"field": "last_recurred_at", "op": "within", "value": "7d"}
]}
Noisy failures in one block:
{"all": [
{"field": "component", "op": "eq", "value": "dma"},
{"field": "failure_count", "op": "gt", "value": 10}
]}
Tracked but stale: tracked for more than two weeks.
{"all": [
{"field": "status", "op": "eq", "value": "tracked"},
{"field": "status_changed_at", "op": "not_within", "value": "14d"}
]}
Ready for a root-cause run: RTL, not labeled flaky, no run in progress
(including signatures that never had one).
{"all": [
{"field": "classification", "op": "eq", "value": "rtl"},
{"field": "label", "op": "ne", "value": "flaky"},
{"not": {"field": "agent_state", "op": "eq", "value": "running"}}
]}
Resolved since a date, in either of two tests:
{"all": [
{"field": "status", "op": "eq", "value": "resolved"},
{"field": "status_changed_at", "op": "after", "value": "2026-11-01T00:00:00Z"},
{"field": "test", "op": "in", "value": ["dma_burst_test", "dma_wrap_test"]}
]}
Passing one to the API (let curl do the URL encoding):
curl -s -G "https://api.daruur.cloud/v1/signatures" \
-H "Authorization: Bearer $DVF_TOKEN" \
--data-urlencode 'filter={"all":[{"field":"status","op":"eq","value":"regressed"}]}' \
--data-urlencode 'limit=50'