Filters
Source: docs/guide/04-filters.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.
A filter keeps the rows that match a condition. It is written one way in a metric's definition and another way in a query, and both follow the same rules.
- In a metric it is part of the metric's meaning, written as a list of conditions relative to
the metric's anchor:
statusis the anchor's field, andcustomers.segmentreaches another dataset over a link. See Metrics. - In a query it is the
WHEREclause, over qualified fields:orders.channel IN ('web', 'app'). See Semantic SQL.
Either kind may name a field through a path, shipments.first_carrier.country
(Relationships).
Conditions
filters:
- {field: is_test, op: equals, value: false}
- {field: amount, op: gte, value: 100}
- any:
- {field: region, op: equals, value: EU}
- {field: region, op: is_null}
op | Takes | Means | In SQL |
|---|---|---|---|
equals, not_equals | value | equal, not equal | =, <> |
gt, gte, lt, lte | value | ordered comparison | >, >=, <, <= |
contains, not_contains | value | substring, taken literally (% and _ are plain characters) | CONTAINS(dataset.field, 'text'), NOT CONTAINS(…) |
in, not_in | values | one of 1 to 500 values | IN (…), NOT IN (…) |
between | low, high | inclusive range | BETWEEN … AND … |
is_null, not_null | none | null test | IS NULL, IS NOT NULL |
A list of conditions means all of them must hold. any is OR and all is AND, and they nest.
Negated conditions drop nulls. not_equals, not_in and not_contains exclude rows whose
field is null, as SQL does. To keep those rows, add an is_null branch under any.
Values must fit the field
Each value is checked against the field's datatype, and a misfit is TYPE_MISMATCH. That
includes a string for a number, an ordering operator (gt, lt, …) on a String, and a time of
day for a Date. A list longer than 500 is VALUES_LIMIT. A list that long is really a join, so model it
as a dataset instead.
A value on a temporal field is a string read by the field's type:
datatype | A bare value ('2026-01-01T09:00:00') | A value with an offset (…+05:30) |
|---|---|---|
DateTimeTz | In a query, read in the reporting time zone. In a metric's definition it is refused, because there is no zone to read it in. | that exact instant |
DateTime | compared with the stored clock reading as written | TYPE_MISMATCH |
Date | 2026-01-01 only; a time of day is TYPE_MISMATCH, never truncated | TYPE_MISMATCH |
Time | 10:30:00 | TYPE_MISMATCH |
In an Asia/Kolkata domain, bookings.booked_at >= '2026-01-01T09:00:00' on a DateTimeTz field
is the moment 03:30 UTC, and keeps a booking made at 09:30 in Kolkata.