Filter Values and Logic
This page is the reference for how to write attribute-filter conditions: the value format of every operator, how dates and time zones are handled, how picklist, user, reference, and boolean fields are filtered, which names to use for built-in attributes, and how conditions and groups combine.
It applies to filters you configure in Design Studio and to conditions sent to the Query Builder API. All values are text.
Each condition has:
- Attribute name: a type attribute, or a built-in attribute (see Built-in attributes).
- Condition (operator): the comparison.
- First value and, for Between only, second value.
- Connector: how the condition is joined to the next one (And, Or, or None for the last).
Operators
| Operator | Meaning |
|---|---|
Equals, NotEquals | Same as, or different from, the value. |
Contains, NotContains | Contains, or does not contain, the text (or, for multi-value fields, the value). |
StartsWith, EndsWith | Begins or ends with the text. |
GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual | Comparisons for numbers and dates. |
Between | Between two values, both inclusive. |
In, NotIn | In, or not in, a list of values. |
IsEmpty, IsNotEmpty | The attribute has no value, or has a value. |
ContextUser | The user attribute is the user running the query. |
Today, LastOneWeek, LastOneMonth, LastOneYear, NextWeek, NextOneMonth, NextOneYear | Relative date ranges. |
Value format per operator
| Operator | Value format |
|---|---|
| In, NotIn | A list in the first value, separated by new lines (or tabs). A comma is not a separator. Blank items are ignored. For numeric attributes, items are normalized and invalid numbers are ignored. For a reference attribute, the items are the names of the referenced instances. If no valid item remains, the condition matches nothing (database read) or is ignored (search index read). Items are not quoted, so an item that contains a space can be split into several terms: prefer single-word items, or use several Equals conditions joined with Or. |
| Between | First value is the lower bound, second value is the upper bound. Both bounds are included. Both values are required. |
| IsEmpty, IsNotEmpty, ContextUser, Today, Last..., Next... | No value. |
| Equals, NotEquals, Contains, NotContains, StartsWith, EndsWith, comparisons | One value in the first value. Text is matched literally: characters such as %, _, and [ have no wildcard meaning. An empty value for Contains, StartsWith, or EndsWith matches every record. |
Example of a list value for In (each item on its own line):
Alpha
Beta
Gamma
Dates and time zones
- Send dates in ISO 8601.
- Date attributes:
2026-01-31(a full ISO timestamp is also accepted). - DateTime attributes, and the built-in
Created,Modified, andLastAccessedDate:2026-01-31T09:30:00Z, with 0 to 7 fractional digits. - Any other format is rejected as invalid, except a date mnemonic.
- Date attributes:
- The value is treated as that point in time (UTC) and converted to the tenant time zone and format configured in tenant settings.
- Day boundaries, and the Today, Last..., and Next... ranges, use the tenant time zone: not the caller's time zone and not UTC.
- Relative presets are half-open ranges: the start is included and the end is excluded. NextWeek extends 8 calendar days by design. See Relative Date Presets for the full semantics.
- Dates in results are returned as UTC ISO timestamps.
Date mnemonics
A date mnemonic is a relative date that is calculated each time the query runs, so the filter never goes out of date. Use it as the first or second value of a Date or DateTime attribute condition, instead of an ISO 8601 date.
$StartOfToday()
$StartOfToday(-2d)
$StartOfMonth(+2w)
Syntax: $Mnemonic() or $Mnemonic(operator number specifier).
| Part | Allowed values |
|---|---|
| Mnemonic | StartOfToday, StartOfWeek, StartOfMonth, StartOfYear |
| Operator | + (add) or - (subtract) |
| Number | A whole number |
| Specifier | d days, w weeks, m months, y years |
| Mnemonic | Base date |
|---|---|
$StartOfToday() | The start of the current day |
$StartOfWeek() | Monday of the current week (see the note below about Sundays) |
$StartOfMonth() | The first day of the current month |
$StartOfYear() | 1 January of the current year |
| Example | Meaning |
|---|---|
$StartOfToday(-2d) | Two days before today |
$StartOfToday(+3d) | Three days after today |
$StartOfWeek(+7d) | The start of next week |
$StartOfMonth(+2w) | Two weeks after the start of the current month |
$StartOfYear(+1y) | The start of next year |
- The base date is calculated in the tenant time zone, then converted for matching.
- A mnemonic is used instead of a date in the value. It is not combined with other text.
- Use a mnemonic with a comparison such as GreaterThanOrEqual, LessThan, or Between. For common ranges such as "last week" or "next month", the ready-made operators (LastOneWeek, NextOneMonth, and so on) are simpler.
- Hours, minutes, and
Noware not available in a query filter. - Example: reviewed in the last 7 days, using a DateTime attribute
ReviewDate: condition GreaterThanOrEqual with first value$StartOfToday(-7d).
$StartOfWeek() is calculated as "Monday minus the current weekday". On Monday to Saturday this gives the Monday of the current week. On a Sunday it gives the following Monday (tomorrow), not the Monday six days earlier. Avoid relying on $StartOfWeek() for filters that run on Sundays, or use $StartOfToday(-6d) for "the last seven days including today".
Expressions in filter values
A filter value can contain an expression that reads a value from an instance or from the current user, instead of a typed value.
| Expression | Resolves to |
|---|---|
@Instance.AttributeName | An attribute of the source instance. |
@User.AttributeName | An attribute of the user running the query. |
@Relation... | A value reached by navigating a relation from the source instance. See Relation Navigation in Expressions. |
Expression evaluation in a query is an opt-in setting:
- It is controlled by the configuration key
EnableExpressionsInInstanceQuery, which is off by default. It is also applied when a query uses a connectable-instance query that validates the destination type only. - When it is off, a value that contains
@Instance,@User, or@Relationis treated as plain text and is not evaluated. - When it is on, the expressions in the first and second values of attribute conditions, and in the attribute conditions of parent filters, are evaluated before the query runs. The source instance for
@Instanceand@Relationis the one given in the query's connectable-instance setting (sourceInstanceId). - If an expression cannot be evaluated, the request fails with the message "An error occurred while evaluating the filter expression. Please contact your administrator."
- If
@Instanceor@Relationis used and no source instance is available, the request fails with a message that the expression "contains attribute values that cannot be resolved before saving" the instance. - A value that evaluates to nothing is replaced with an empty value.
These expressions are written in the filter value. The expressions of query parameters are a separate mechanism and are evaluated by the application, not by the server.
Picklist fields
- Use the option display name (the picklist option's name). The option's internal identifier is not accepted. Matching is exact and case-sensitive.
- To match several options, separate the names with commas, for example
High,Critical(where the operator supports a list, see below). - A name that does not match any option is silently dropped. The value becomes empty and the condition no longer filters as intended: Equals then matches records that have any value, and NotEquals matches records that have none. A typo therefore returns wrong data instead of an error, so copy option names exactly from the attribute.
| Picklist kind | Operators and meaning |
|---|---|
| Single-select (one value per record) | Equals and NotEquals with one name. For "any of several", add one Equals per name and join them with Or. |
| Multi-select (several values per record) | Contains matches records that have any of the given names. Equals matches records that have all of them. NotContains and NotEquals are the negations. |
Use In or NotIn on a picklist only with a single-select picklist and exactly one name. With several names on a single-select picklist the query fails, and on a multi-select picklist the result is not meaningful. Use Equals with Or, or Contains, instead.
User fields
- Use the user's identifier, not the user name.
- For multi-select user attributes, separate several identifiers with commas: Contains matches any of them, Equals matches all of them.
Creator,Modifier, andLastAccessedByare user fields and use the same format.- To mean "the user running the query", use ContextUser; it needs no value.
- An identifier that does not belong to a user matches nothing.
Boolean fields
Use true or false with Equals or NotEquals.
Reference fields
- Equals, NotEquals, and Contains compare against the referenced instance.
- In and NotIn take the names of the referenced instances, one per line.
Built-in attributes
Use the exact, case-sensitive name below as the attribute name.
| Field | Attribute name | Value |
|---|---|---|
| Name | Name | Text |
| Tracking Id | TrackingId | Text |
| Created | Created | ISO 8601 date and time |
| Modified | Modified | ISO 8601 date and time |
| Last accessed | LastAccessedDate | ISO 8601 date and time |
| Creator | Creator | User identifier |
| Modifier | Modifier | User identifier |
| Last accessed by | LastAccessedBy | User identifier |
| State | State | State name |
| Lifecycle | Lifecycle | Lifecycle name |
| Others | Description, TrackingInfo, Geolocation, TypeName, VersionNumber, QRCode, GeofenceCenter, GeofenceRadius | As stored |
Id is not a built-in filter attribute. Using it fails with an error that the attribute is not associated with the type. To find a known instance, filter on Name or TrackingId.
State
A state can be filtered in two ways, and both work:
| Way | Use |
|---|---|
State filter (stateFilter) | Preferred. A list of state names; a record matches when it is in any of them. |
Attribute condition on State | Equals, NotEquals, or In with a state name. Useful when the state must be combined with other conditions inside one group. |
Always use state names, not display names.
An attribute name that is neither a built-in attribute nor an attribute of the type is rejected.
And, Or, and None
Conditions are grouped into expressions (groups). Inside an expression, and between expressions, you pick a connector.
"attributeFilterExpressions": [
{
"operator": "And",
"orderIndex": 0,
"attributeFilterConditions": [
{ "attributeName": "Priority", "condition": "Equals", "firstValue": "High", "operator": "Or", "orderIndex": 0 },
{ "attributeName": "Priority", "condition": "Equals", "firstValue": "Critical", "operator": "None", "orderIndex": 1 }
]
},
{
"operator": "None",
"orderIndex": 1,
"attributeFilterConditions": [
{ "attributeName": "DueDate", "condition": "LessThan", "firstValue": "2026-12-01", "operator": "None", "orderIndex": 0 }
]
}
]
This reads as (Priority = High OR Priority = Critical) AND DueDate < 2026-12-01.
| Rule | Detail |
|---|---|
| Connector direction | A condition's connector joins it to the next condition in the same expression. An expression's connector joins it to the next expression. |
| Last item | The connector of the last condition, and of the last expression, is not used. Set it to None. |
| Non-last items | Must be And or Or. None is not a valid joiner between two items: the database read fails with an invalid query, and the search-index read gives no defined result. Always use And or Or. |
orderIndex | Not used when a query is executed through the API: items are evaluated in the order they appear in the list. Set it sequentially anyway; it is used when a query definition is saved. |
| Parentheses | Each expression is evaluated as one parenthesized unit. |
| Precedence between expressions | When read from the database, expressions are chained with normal precedence (And binds tighter than Or). When read from the search index, they are applied strictly left to right. |
Because the two read paths chain expressions differently, avoid using both And and Or between three or more expressions. Put mixed logic inside one expression with a single connector, or split it into two queries.
In the Design Studio screen the builder shows the same idea with AND / OR switches and + Add Group: rows in a group use the connector you select between them, and groups are joined the same way.