Skip to content

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:

filter: .all[0].op: status doesn't support 'contains'

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, in and not_in on 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_contains and starts_with ignore case and treat % and _ as ordinary characters.
  • text with contains matches if the title, template or message id contains the text; with not_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_contains and not_within do 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 the not includes it. {"not": {"field": "agent_state", "op": "eq", "value": "running"}} includes signatures that never had a root-cause run.
  • Use is_null and not_null to 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:

{"field": "branch", "op": "contains", "value": "release/"}

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'