Skip to main content

Filters

Synced from semantic-layer

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: status is the anchor's field, and customers.segment reaches another dataset over a link. See Metrics.
  • In a query it is the WHERE clause, 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}
opTakesMeansIn SQL
equals, not_equalsvalueequal, not equal=, <>
gt, gte, lt, ltevalueordered comparison>, >=, <, <=
contains, not_containsvaluesubstring, taken literally (% and _ are plain characters)CONTAINS(dataset.field, 'text'), NOT CONTAINS(…)
in, not_invaluesone of 1 to 500 valuesIN (…), NOT IN (…)
betweenlow, highinclusive rangeBETWEEN … AND …
is_null, not_nullnonenull testIS 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:

datatypeA bare value ('2026-01-01T09:00:00')A value with an offset (…+05:30)
DateTimeTzIn 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
DateTimecompared with the stored clock reading as writtenTYPE_MISMATCH
Date2026-01-01 only; a time of day is TYPE_MISMATCH, never truncatedTYPE_MISMATCH
Time10:30:00TYPE_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.