Filter operators
Generated from
src/document/filter_compiler.crbymake gen-docs-filter-operators. Do not edit this file by hand.
Use this page to build a filter and check which operators a field type accepts.
List routes take filters as query parameters, for example filters[status__eq]=active.
A filter key is a field name with an operator suffix; a bare key is eq.
One table below covers each field-type family.
A bad filter fails with one of two codes:
unsupported_filter_operator— the field does not serve the operator.malformed_filter_value— the value has the wrong shape.
Both answer 422.
Comparison — most field types
Section titled “Comparison — most field types”Serves: any, color, data, date, datetime, dictionary, duration, enum, file, integer, longtext, object, phone, secret, string, url. Integer and duration values compare numerically; the other types compare as text.
| Operator | Value shape | Meaning |
|---|---|---|
between |
array | Stored value is inside the inclusive range. The value is a two-element array [start, end]. |
eq |
scalar | Stored value equals the given value (text equality). |
gt |
scalar | Stored value is greater than the given value. |
gte |
scalar | Stored value is greater than or equal to the given value. |
in |
array | Stored value equals one of the array entries, at most 100. |
lt |
scalar | Stored value is less than the given value. |
lte |
scalar | Stored value is less than or equal to the given value. |
match |
scalar | Stored value contains the given substring, case-insensitive. % and _ match literally. |
ne |
scalar | Stored value is not the given value. |
starts_with |
scalar | Stored value starts with the given prefix, case-insensitive. |
Array fields
Section titled “Array fields”Serves: array. Membership on the stored JSON array.
| Operator | Value shape | Meaning |
|---|---|---|
contains |
scalar or array | Same match as eq: the stored array contains all given elements. |
eq |
scalar or array | Stored array contains the given element, or every element of the given array. |
overlaps |
scalar or array | Stored array shares at least one element with the given array. |
Boolean fields
Section titled “Boolean fields”Serves: boolean. A boolean is a two-state field: equality only.
| Operator | Value shape | Meaning |
|---|---|---|
eq |
scalar | Value equals the given boolean. |
ne |
scalar | Value is not the given boolean. |
Money fields
Section titled “Money fields”Serves: money.
The comparison value is an amount string, optionally prefixed with the currency: USD 12.50. A bare amount compares across every currency.
| Operator | Value shape | Meaning |
|---|---|---|
between |
array | Amount is inside the inclusive range. The value is a two-element array; both bounds must carry the same currency. |
currency |
scalar | Stored currency ticker equals the given registered ticker. |
eq |
scalar | Amount equals the given value. |
gt |
scalar | Amount is greater than the given value. |
gte |
scalar | Amount is greater than or equal to the given value. |
lt |
scalar | Amount is less than the given value. |
lte |
scalar | Amount is less than or equal to the given value. |
Range fields (dateperiod, period)
Section titled “Range fields (dateperiod, period)”Serves: dateperiod, period.
The stored value is a {start, end} interval.
| Operator | Value shape | Meaning |
|---|---|---|
contains |
ISO-8601 string or array | Stored interval contains the given point (an ISO-8601 string) or the given [start, end] interval. |
eq |
array | Stored interval equals the given [start, end] interval. |
overlaps |
array | Stored interval and the given interval share at least one point. |
within |
array | Stored interval lies inside the given [start, end] interval. |
Reference fields
Section titled “Reference fields”Serves: reference. A reference is a two-state target: equality only.
| Operator | Value shape | Meaning |
|---|---|---|
eq |
scalar | Reference points at the given document. The bare id and the qualified {domain}.{Doctype}.{id} form both match. |
ne |
scalar | Reference does not point at the given document (same two forms). |
The id system column
Section titled “The id system column”id is the document id column on projections; it is not a doctype field.
| Operator | Value shape | Meaning |
|---|---|---|
between |
array | Document id is inside the inclusive range. The value is a two-element array. |
eq |
scalar | Document id equals the given id. |
gt |
scalar | Document id sorts after the given id. ULIDs sort by creation time, so the order is also chronological. |
gte |
scalar | Document id sorts after the given id or equals it. |
in |
array | Document id equals one of the array entries, at most 100. |
lt |
scalar | Document id sorts before the given id. |
lte |
scalar | Document id sorts before the given id or equals it. |
match |
scalar | Document id contains the given substring, case-insensitive. |
ne |
scalar | Document id differs from the given id. |
Timestamp system columns
Section titled “Timestamp system columns”Serves: created_at, updated_at, deleted_at.
deleted_at filters the trash listing (include_deleted: true); live rows carry NULL.
| Operator | Value shape | Meaning |
|---|---|---|
between |
array | Column is inside the inclusive range. The value is a two-element array of timestamps. |
eq |
scalar | Column equals the given timestamp. The value normalizes to UTC RFC 3339, so offsets are respected. |
gt |
scalar | Column is later than the given timestamp. |
gte |
scalar | Column is later than or at the given timestamp. |
lt |
scalar | Column is earlier than the given timestamp. |
lte |
scalar | Column is earlier than or at the given timestamp. |
ne |
scalar | Column differs from the given timestamp. |
Search
Section titled “Search”search is a keyword of the grammar, not a field.
Only the bare key is valid; a suffixed form (for example search__match) answers 422.
| Key | Value shape | Meaning |
|---|---|---|
search |
scalar | The document search text contains the given term, case- and accent-insensitive. |