Skip to content

Filter operators

Generated from src/document/filter_compiler.cr by make 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.

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.

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.

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.

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.

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.

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).

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.

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 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.