Skip to main content

Filtering and sorting

Every connection โ€” root field or to-many relation โ€” takes a where argument for filtering and an order_by argument for sorting. Both are generated from your definitions, so the operators available on a field follow from that field's type.

The examples use the equipment and maintenance_request objects introduced in the overview.

Vehicle root connections (vehicle and concrete definition slugs) also accept search. It matches the canonical display_name as a case-insensitive literal substring; % and _ are ordinary characters. Input is limited to 256 characters, surrounding whitespace is trimmed, and a blank value adds no condition. Search is combined with where before totalCount, sorting and pagination, including backward pages. Relative-date filters continue to use the server clock and the workspace timezone. Object roots and nested connections do not expose this argument. See the Vehicle query example.

Operators by field typeโ€‹

Typed attribute / fieldOperators
system id_eq, _ne, _in, _gt, _lt, _gte, _lte
text, email, phone_eq, _ne, _in, _contains, _starts_with, _ends_with, _is_null
number, capacity, measure, currency, rating_eq, _ne, _in, _gt, _lt, _gte, _lte, _is_null
boolean_eq, _ne, _is_null
single select, state_eq, _ne, _in, _is_null
date, date_time_eq, _ne, _in, _gt, _lt, _gte, _lte, _is_null
multi select_in, _contains, _is_null
raw_json_is_null only; a required document has no filter field
rich_text_contains on the plain-text projection, _is_null
full_name_contains on the combined display, _is_null; order_by orders by last then first name
links_contains on labels and URLs, _is_null
relationship, tags, skillsNested target-object filter; see Filtering by a related record
locationNot directly filterable

Two of these are narrower than you might expect, and deliberately so:

  • ID has no _is_null. A record always has an id. It does have the ordering comparators, which exist so id can complete a compound cursor โ€” see exhaustive iteration.
  • Enum filter operands are strings. The output field is a generated GraphQL enum, but filters use quoted public values: _eq: "hvac" or _in: ["hvac", "ventilation"].
  • Required fields omit _is_null. A filter input advertises null checks only where the workspace schema permits the attribute to be unset.

Every operator on one field is combined with AND. { name: { _starts_with: "Chiller" }, operational: { _eq: true } } means both conditions.

urgent-open-requests.graphql
query UrgentOpenRequests {
maintenance_request(
where: {
resolved: { _eq: false }
priority: { _in: ["urgent"] }
reported_at: { _gte: "2026-03-01T00:00:00Z" }
}
order_by: [{ reported_at: desc }]
first: 20
) {
totalCount
edges {
node {
id
title
reported_at
}
}
}
}

Relative time windowsโ€‹

DateTime and Date operands accept a relative expression as well as an absolute timestamp. It is resolved when the query runs, so now-6h always means the last six hours โ€” a stored filter or a dashboard query written this way does not go stale.

recently-reported.graphql
query RecentlyReported {
maintenance_request(where: { reported_at: { _gte: "now-6h" } }) {
edges { node { id title reported_at } }
}
}

The syntax is now, an optional offset, and an optional snap to a unit boundary:

ExpressionMeans
nowthis instant
now-6hsix hours ago
now+30mthirty minutes from now
now/dstart of today
now-1d/dstart of yesterday
now/wstart of this week (Monday)
now-12Mtwelve months ago

Units are s, m (minutes), h, d, w, M (months), y โ€” case matters, m is minutes and M is months. Offsets are capped at 10000 units.

The offset applies first, then the snap, which is what makes now-1d/d the start of yesterday rather than this time yesterday. Combine two bounds for a closed window:

where: { reported_at: { _gte: "now-1d/d", _lt: "now/d" } }

Three things worth knowing:

  • Timezone. Snapping and offsets of a day or larger are evaluated in your workspace timezone, so "start of today" is your midnight, not UTC midnight. Offsets below a day are exact durations.
  • Calendar arithmetic above the hour. now-1M from 31 March is 28 February, not "30 days ago", and now-1d keeps its wall-clock time across a daylight-saving change. Use now-24h when you want an exact duration instead.
  • Where it applies. Comparison operators (_eq, _gt, _lt, _gte, _lte) on DateTime and Date fields. Time takes absolute values only โ€” an expression names an instant, not a time of day.

A malformed expression is rejected with an error naming this syntax, for example 'nowish' is not a valid relative time expression: โ€ฆ.

Text matchingโ€‹

Text matching is semantic and case-insensitive. Clients supply text, never SQL patterns:

OperatorMeaning
_containsThe field contains the operand anywhere.
_starts_withThe field begins with the operand.
_ends_withThe field ends with the operand.

Literal % and _ characters are matched as ordinary characters. This keeps database pattern syntax out of the public contract and gives REST and GraphQL identical behavior.

filter-contains.graphql
{ equipment(where: { name: { _contains: "chiller" } }, first: 10) { edges { node { name } } } }

Null checksโ€‹

_is_null: true matches records where the field is unset; _is_null: false matches those where it is set. This is separate from _eq: null, which is not supported. A multi-select without values counts as unset.

Unset values in negative conditionsโ€‹

A comparison never matches a record whose field is unset: _eq, _in, _gt, _contains and the other operators skip it. _ne and _not match every record the positive condition does not, so they include records where the field is unset. { status: { _ne: "retired" } } returns records with another status and records with no status. Add _is_null: false when you want to leave unset values out: { status: { _ne: "retired", _is_null: false } }.

This applies to Object, Vehicle and Task connections. On system_tour, _ne and _not still leave out Tours whose field is unset.

Multi-select fieldsโ€‹

A multi-select value is stored as a JSON array of stable choice IDs and exposed as current choice values. It is filtered by containment rather than scalar comparison:

OperatorMeaning
_inThe array contains at least one of the supplied public choice values.
_containsThe array contains every supplied public choice value.

Wrap _in in _not for records that have none of the values, including records with no value: _not: { certifications: { _in: ["TUV"] } }.

The operand is a non-empty GraphQL list of public choice values, not an encoded JSON string:

certifications-contains.graphql
{ equipment(where: { certifications: { _contains: ["TUV"] } }, first: 10) { edges { node { name } } } }

The typed API does not support arbitrary array or nested-object attributes. The only composite value, location, has a fixed output shape and no direct filter operators.

Combining conditionsโ€‹

_and: [Filter!]All of the given filters must match.
_or: [Filter!]At least one must match.
_not: FilterThe given filter must not match. A record whose field is unset counts as not matching.
neglected-or-critical.graphql
query NeglectedOrCritical {
equipment(
where: {
_or: [
{ operational: { _eq: false } }
{ _and: [{ category: { _in: ["hvac"] } }, { replacement_cost: { _gte: 20000 } }] }
]
_not: { asset_tag: { _starts_with: "TEMP-" } }
}
first: 25
) {
totalCount
edges { node { name asset_tag } }
}
}

Two edge cases are worth knowing because they are opposites:

  • _and: [] โ€” an empty list โ€” matches everything.
  • _or: [] matches nothing.

That follows from the logic (an empty conjunction is true, an empty disjunction is false), but it bites when a client builds the list dynamically: an _or whose conditions were all filtered out returns zero rows rather than being ignored. Omit the key entirely when you have no conditions.

Nesting limitโ€‹

A where argument may nest at most 4 levels. Each _and, _or, _not and each relationship sub-filter counts as one level. Exceeding it returns graphql/filter-too-deep, which reports both the depth you sent and the limit.

This limit is independent of the query-depth limit that bounds relation traversal โ€” they are separate controls with separate values. See Errors and limits.

A relation contributes a field to the filter input, named after the relation slug and typed as the other side's filter. It matches a parent when at least one related record matches:

equipment-with-urgent-requests.graphql
query EquipmentWithUrgentRequests {
equipment(
where: { maintenance_requests: { priority: { _in: ["urgent"] }, resolved: { _eq: false } } }
first: 20
) {
totalCount
edges { node { name } }
}
}

An empty relation filter matches a parent with at least one related record: { manufacturer: {} }. Wrap a relation filter in _not for parents where no related record matches: _not: { manufacturer: {} } returns equipment without a manufacturer, and _not: { manufacturer: { id: { _in: ["โ€ฆ"] } } } returns equipment linked to none of the given records, including equipment with no manufacturer at all. Inside a relation filter, a condition applies to an existing related record: { manufacturer: { id: { _ne: "โ€ฆ" } } } returns equipment linked to some other manufacturer, not equipment without one.

For a relationship to the system user object, the id filter also accepts me, the calling user: where: { team: { id: { _eq: "me" } } } returns the caller's projects, and _in: ["me", "โ€ฆ"] mixes it with other user IDs. Members without users:read can filter and order through a user relationship by id, firstname, lastname, active, and deleted_at, and select those fields plus display_name.

Note the semantics carefully: this returns equipment that has any unresolved urgent request. It does not filter the maintenance_requests connection itself. To do both โ€” select the equipment and narrow the requests you get back โ€” filter in both places:

filter-both-levels.graphql
{
equipment(where: { maintenance_requests: { resolved: { _eq: false } } }, first: 20) {
edges {
node {
name
maintenance_requests(where: { resolved: { _eq: false } }, first: 5) {
edges { node { title } }
}
}
}
}
}

The same nested shape applies to tags, required_skills, and provided_skills; their target is the platform tag or skill object. This applies to Object roots and concrete Vehicle/Task roots that declare the attribute. Provided and required skills filter their respective association roles. Aggregate Vehicle/Task roots retain their common-field filters. Target read permissions apply before filtering and counting. Managed reverse relationship attributes are filterable too, even though REST writes must go through the relationship's declaring owner side. Platform-internal hidden connector sides contribute no filter field.

Sortingโ€‹

order_by takes a list, and the list order is the sort precedence:

order-by-category-name.graphql
{
equipment(order_by: [{ category: asc }, { name: asc }], first: 50) {
edges { node { category name } }
}
}

Directions are asc and desc.

lock_version, display_name, tags, skills, and locations cannot be sorted directly. Stored scalar and select/state attributes can, as can the system fields id, created_at, and updated_at.

A to-one relationship supports exactly one ordering hop. This orders equipment by its manufacturer's name without asking the client to copy that name onto every equipment record:

order-by-related-manufacturer.graphql
{
equipment(order_by: [{ manufacturer: { name: asc } }], first: 50) {
edges { node { display_name manufacturer { display_name } } }
}
}

Chained relationship ordering and ordering a parent by a to-many collection are not exposed. To sort a to-many relationship's records, put order_by on that relationship connection itself. Ascending sorts place missing relationships or null target values last; descending sorts place them first.

Results are always in a total orderโ€‹

This matters more than it sounds, because it is what makes paging trustworthy. PostgreSQL guarantees no row order without an explicit sort, so an unordered query combined with a page window could return the same row on two pages and never return another.

So every query is given a total order:

  • Your order_by fields first, in the order you listed them.
  • Then created_at descending, if you supplied no sort at all โ€” so an unsorted list is newest-first rather than arbitrary.
  • Then id ascending, always, which breaks any remaining tie.

You never have to add a tiebreaker yourself, and two identical queries return pages that fit together.