Learn how query expressions can be used to filter results returned from our APIs.
Wristband APIs that return a list of items often support filtering the returned results using a query expression. APIs that support the use of query expressions will have query query parameter. In the sections below, we'll go over how to write query expressions that can be passed to the query query parameter.
Query Syntax
Query expressions must follow this syntax:
<attribute> <comparison_operator> <value> [<logical_operator> ...]
Some example query expressions are listed below:
email eq "[email protected]"givenName eq "Alice" or givenName eq "Bob"
In the next sections, we'll dive deeper into the different parts of a query expression.
Attributes
The attribute in a query expression specifies which entity attribute will be compared by the operator. The attributes you can use depend on the API being called. Refer to the Query Filter Attributes section in each API's description for a list of supported attributes.
Case Sensitivity
Attribute values are case-insensitive, so email and EMAIL are treated as equivalent.
Comparison Operators
The table below lists all supported comparison operators.
| Operator | Description |
|---|---|
| eq | Equals |
| ne | Not Equals |
| sw | Starts With |
| lt | Less Than |
| le | Less Than or Equal |
| gt | Greater Than |
| ge | Greater Than or Equal |
| in | Multi-value comparison operator that resolves to true if an attribute’s value matches one of the values specified in the in value expression. The in value expression must be formatted as follows: (<attribute_value>, <attribute_value>, ...). |
| nin | Multi-value comparison operator that resolves to true if an attribute’s value does not match one of the values specified in the nin value expression. The nin value expression must be formatted as follows: (<attribute_value>, <attribute_value>, ... <attribute_value>"). |
Not all attributes support the same comparison operators. To see which operators are available for a given attribute, refer to the Query Filter Attributes section in the API's description.
Case Sensitivity
Comparison operator values are case-insensitive, so eq and EQ are treated as equivalent.
Attribute Values
The expected format of each attribute value depends on the type of the attribute. Currently, the following attribute types are supported:
- String
- Boolean
In the sections below, we'll provide a detailed overview of each attribute type.
String Attributes
String type attributes must have their values enclosed in double quotes (""). For example, if you wanted to filter users by their email, you would need to enclose the email value in double quotes, like the following:
email eq "[email protected]"
Escaping Special Characters
If you need to include special characters in the string value (such as double quotes), you'll have to escape them using the backslash (\) character. For example, if you wanted to include double quotes when querying by given name, you would need to escape the double quotes, like the following:
givenName eq "A \"Quoted\" String".
Case Sensitivity
The case sensitivity of the string value depends on the attribute being queried. To check the case sensitivity of an attribute, refer to the Query Filter Attributes section in the API's description.
Boolean Attributes
Boolean attributes must have a value of either true or false. Other truthy and falsy variations are not supported.
Null Values
If you want to query for attributes that don't have a value assigned, you can use null as the value. For example, if you wanted to filter for users that don't have a given name defined, you could use the following query:
givenName eq null.
Logical Operators
Logical operators can be used to combine predicate expressions in the query. Below is a table listing all the supported logical operators.
| Logical Operator | Description |
|---|---|
| and | Logical "AND" operation. |
| or | Logical "OR" operation. |
Case Sensitivity
Logical operator values are case-insensitive, so or and OR are treated as equivalent.
Order of Precedence
When multiple logical operators are used in a query expression and operators will evaluate first, followed by or operators. For example, if we had the following query expression:
email eq "[email protected]" and givenName eq "mike" or lastName eq "smith"
First the email eq "mike@email" and givenName eq "mike"expression would be evaluated. Then the result of that expression would be combined with the lastName eq "smith"predicate using a logical or operator.
Grouping Operators
Parentheses can be used in queries to change the order of precedence when evaluating the expression. For example, if we had the following query expression:
email eq "[email protected]" and (givenName eq "mike" or lastName eq "smith")
First the givenName eq "mike" or lastName eq "smith"expression would be evaluated. Then the result of that expression would be combined with the email eq "[email protected]"predicate using a logical and operator.
Example Queries
Query for Users by Email and Status
email eq "[email protected]" and status eq "ACTIVE"
Query for Users by Email and Email Verified Status
email eq "[email protected]" and emailVerified eq true
Query for Users by Email or Username and Family Name
email eq "[email protected]" or username eq "bsmith" and familyName eq "Smith"
Query for Users by Email Using in Operator
in Operatoremail in ("[email protected]", "[email protected]", "[email protected]")
Query for Users Whose Given Name is Null
givenName eq null
Query Entities Created After a Certain Datetime
metadata.creationTime gt "2021-06-13T19:00:00.000Z"