Working with filters
When working with API for getting a list of app items, it is possible to set search conditions to filter the items.
Filering is performed by using filterparameter.
Example:
{
"filter": {
}
}
There are three types of filter operations available:
- Table operations. These operations allow you to create sets of conditions for filtering based on pre-defined condition options available for each field type.
- Condition operations. These operations allow you to create single filtering conditions in which you can set different kinds of criteria for fields of different types.
- Logic operations. These operations allow you to combine, merge, and nest conditions.
Table operation
In the filtering conditions, you need to specify items’ fields and criteria they have to meet. For each data type, there is a separate way to set the criteria.
You can set conditions for several fields within one filter. In this case, app items that meet all the criteria will be returned.
To filter, add the tf parameter to your request:
{
"filter": {
"tf": {
"title": "white",
"description":"color with code"
}
}
}
String
For string fields, specify a string that is expected to be included in the app item’s field. Search is case-insensitive, meaning that the register is not important.
Example:
{
"filter": {
"tf": {
"__name": "My object"
}
}
}
Number
For Number type fields, specify the interval that must include the value you are looking for.
Example:
{
"filter": {
"tf": {
"weight": {
"min": 10,
"max": 100
}
}
}
}
If you need to find an exact number, specify your target in both parameters:
{
"filter": {
"tf": {
"weight": {
"min": 100,
"max": 100
}
}
}
}
If you need to find a smaller or a larger number, specify one of the parameters and set null for the other:
{
"filter": {
"tf": {
"weight": {
"min": 1,
"max": null
}
}
}
}
Date/Time
For Date/Time type fields, specify the interval. Keep in mind that:
- Time is specified in the +00 time zone.
- If field settings have been changed from Date to Time or vice versa, the data that was entered before may not meet the filter criteria. Before applying the filter, analyze the stored data.
Example:
{
"filter": {
"tf": {
"__createdAt": {
"min": "2023-04-11T00:00:00Z",
"max": "2023-04-12T00:00:00Z"
}
}
}
}
If you need to find a date earlier or later than a particular one, you should specify one of the parameters and set null for the other:
{
"filter": {
"tf": {
"__createdAt": {
"min": "2023-04-11T00:00:00Z",
"max": null
}
}
}
}
We recommend that you always include time in the filter conditions to ensure consistent search results across different system settings and data storage options.
Here is an example of code that we do not recommend using:
{
"filter": {
"tf": {
"__createdAt": {
"min": "2023-04-01",
"max": "2023-04-17"
}
}
}
}
Yes/No switch
For Yes/No switch type fields, specify the value you are looking for: true or false.
Example:
{
"filter": {
"tf": {
"opened": true
}
}
}
Phone number
For Phone number type fields, specify a string that is expected to be included in the app item field. Separators in the phone number are irrelevant.
Example:
{
"filter": {
"tf": {
"phone": "7-999-11"
}
}
}
For Email type fields, specify a string that is expected to be included in the app item field. The filter is case-insensitive.
Example:
{
"filter": {
"tf": {
"email": "admin@admin.com"
}
}
}
Full Name
For Full Name type fields, specify a string that is expected to be included in the name of surname of the app item you are looking for. The filter is case-insensitive.
Example:
{
"filter": {
"tf": {
"full_name": "Jerry"
}
}
}
Status
For Status type fields, specify an array with status numbers.
Example:
{
"filter": {
"tf": {
"__status": [2,3]
}
}
}
Users
For Users type fields, specify the user’s UUID.
Example:
{
"filter": {
"tf": {
"user": "47cfc3d3-279d-441e-a245-a27adaac81e8"
}
}
}
For Users fields of the Many type, you need to specify only one user you are looking for.
Example:
{
"filter": {
"tf": {
"users": "47cfc3d3-279d-441e-a245-a27adaac81e8"
}
}
}
App
To search across fields of the App type, specify the item’s UUID.
Example:
{
"filter": {
"tf": {
"myApp": {
"id":"7730e64b-551b-4eda-bb49-b0120e9712eb",
}
}
}
}
Arbitrary app
To search across fields of the Arbitrary app type, specify the item’s identifiers: UUID, app code, and workspace code.
Example:
{
"filter": {
"tf": {
"myRandomApp": {
"id":"7730e64b-551b-4eda-bb49-b0120e9712eb",
"code":"myApplication",
"namespace":"myNamespace",
"inTrash":false
}
}
}
}
Category
To search across fields of the Category type, specify the code of the enumeration item.
Example:
{
"filter": {
"tf": {
"errStatus":"blocker"
}
}
}
Condition operations
These operations require two parameters:
- Field name. The required parameter
filed. - Condition. For a condition with a single value, use the
constparameter; for a condition with multiple values, thelistparameter. If you need to specify an empty condition, usenull.
Example of a single-value condition:
{
"eq": [
{"field": "weight"},
{"const": 5}
]
}
Example of a multiple-value condition:
{
"in": [
{"field": "values"},
{"list": [1,4]}
]
}
Example of an empty condition:
{
"eq": [
{"field": "title"},
null
]
}
The syntax of the condition depends on the field type that you are filtering by.
Conditions syntax for different data types
String
For String type fields, specify a string enclosed in quotation marks.
Example:
{
"filter": {
"eq": [
{"field": "stringField"},
{"const": "MyStringValue"}
]
}
}
Number
For numeric data types, specify a number.
Example for an integer:
{
"filter": {
"neq": [
{"field": "intField"},
{"const": 14}
]
}
}
Example for a decimal:
{
"filter": {
"neq": [
{"field": "floatField"},
{"const": 12.05}
]
}
}
Money
For Money type fields, specify a number representing the smallest units of the currency. For example, for 54 dollars and 45 cents, the number in the filter would be 5445.
Example:
{
"filter": {
"neq": [
{"field": "moneyField"},
{"const": 5445}
]
}
}
Date/Time
For fields with date or time, enclose the value in quotation marks. Keep in mind that:
- The time is specified in the +00 time zone.
- If field settings have been changed from Date to Time or vice versa, the data that was entered before may not meet the filter criteria. Before applying the filter, analyze the stored data.
We recommend that you always include time in the filter to ensure consistent search results across different system settings and data storage options.
Example:
{
"filter": {
"eq": [
{"field": "dateTimeField"},
{"const": "2023-04-17T04:54:39Z"}
]
}
}
Yes/No switch
For Yes/No switch type fields, use true or false to specify the condition.
Example:
{
"filter": {
"eq": [
{"field": "boolField"},
{"const": true}
]
}
}
Phone number
For Phone number type fields, use the phone number as a string, with or without separators.
Example:
{
"filter": {
"eq": [
{"field": "phoneField"},
{ "const": "+71234566780"}
]
}
}
For Email type fields, use the email address as a string.
Example:
{
"filter": {
"eq": [
{"field": "emailFiled"},
{"const": "example@example.example"}
]
}
}
Full Name
For Full Name type fields, specify the string. Since data stored in this type of fields fields is not standard, the number of available operations is limited. We recommend using the like operator.
Example:
{
"filter": {
"like": [
{"field": "full_name"},
{"const": "Sebastian"}
]
}
}
Status
For Status type fields, specify the sequential number of the status.
Example:
{
"filter": {
"in": [
{"field": "__status"},
{ "list": [1,2]}
]
}
}
Users
For Users type fields, use the lower-case string representation of the user’s UUID in quotation marks.
Example:
{
"filter": {
"eq": [
{"field": "__createdBy"},
{"const": "95806fe5-f8e8-460c-b2be-ce607068726c"}
]
}
}
App
For App type fields, use the string with the app item’s UUID. Regardless of whether the field is of the One or Many type, the data is stored as an array. Therefore, we recommend you use the link operator.
Example:
{
"filter": {
"link": [
{"field": "fieldApp"},
{"list": ["f5506c2b-0504-4420-9490-11a4f4d7f49d"]}
]
}
}
Category
For Category type fields, use the string code of the enumeration item.
Example:
{
"filter": {
"eq": [
{"field": "enumField"},
{"const": "enumValue1"}
]
}
}
Equality and inequality operations
The equality operation allows you to set a filtering condition based on a complete match. It is specified using the eq parameter.
The inequality operation allows you to set a filtering condition that is the opposite of the equality operation. It is specified using the neq parameter.
Example of using the equality operation for an integer:
{
"filter": {
"eq": [
{"field": "weight"},
{"const": 5}
]
}
}
Example of using the equality operation for a date:
{
"filter": {
"eq": [
{"field": "ttlEnd"},
{"const": "2023-04-12T11:11:45.367Z"}
]
}
}
Example of using the inequality operation for a Yes/No switch field:
{
"filter": {
"neq": [
{"field": "opened"},
{"const": true}
]
}
}
Example of checking for an empty value of the enum field for a Category field:
{
"filter": {
"neq": [
{"field": "enum"},
null
]
}
}
Greater than, greater than or equal to, less than, and less than or equal to
The Greater Than operation allows you to set a filtering condition based on finding a value greater than the specified threshold. It is specified using the gt parameter.
The Greater Than or Equal To operation allows you to set a filtering condition based on finding a value greater than or equal to the specified threshold. It is specified using the gte parameter.
The Less Than operation allows you to set a filtering condition based on finding a value less than the specified threshold. It is specified using the lt parameter.
The Less Than or Equal To operation allows you to set a filtering condition based on finding a value less than or equal to the specified threshold. It is specified using the lte parameter.
Example of searching for a status that is different from the initial one:
{
"filter": {
"gt": [
{"field": "__status"},
{"const": 1}
]
}
}
Example of searching within a time range for a field containing a date:
{
"filter": {
"and": [
{
"gte": [
{"field": "ttlEnd"},
{"const": "2023-04-10T11:11:45.367Z"}
]
},
{
"lte": [
{"field": "ttlEnd"},
{"const": "2023-04-12T11:11:45.367Z"}
]
}
]
}
}
Substring inclusion operation
The Substring inclusion operation enables filtering based on partial matches by using the like parameter.
Example of searching for a partial match for a string:
{
"filter": {
"like": [
{"field": "__name"},
{"const": "city"}
]
}
}
Included in the set and Not included in the set
The Included in the set operation allows you to set a filtering condition where the value of a single field is checked for membership in a set. It is specified using the in parameter.
The Not included in the set operation allows you to set a filtering condition where the value of a single field is checked for non-membership in a set. It is specified using the not_in parameter.
Example of search based on membership of the field value in a list of allowed values:
{
"filter": {
"in": [
{"field": "weight"},
{ "list": [1, 11] }
]
}
}
Example of search based on non-membership of a Category type field value in a list of values that are not allowed:
{
"filter": {
"not_in": [
{"field": "enum"},
{ "list": ["Number1", "Number3", "Number5"] }
]
}
}
Linked collection operation
The Linked collection operation allows you to filter items based on whether an App type field with the Many option is linked with a specific item. This operation is set using the link parameter. As the value, specify the app item’s ID.
Example:
{
"filter": {
"link": [
{"field": "fewApps"},
{ "list": ["f5506c2b-0504-4420-9490-11a4f4d7f49d", "e20379bc-2f80-4b63-9e77-fbb3fa50e362"] }
]
}
}
Includes the set operation
The Includes the set operation allows filtering based on whether a field with the Many/Multiple option the specified is included in a specified set. It is set using the all parameter.
Example of search by whether a field value belongs to a predefined list of users:
{
"filter": {
"all": [
{"field": "users"},
{ "list": ["95806fe5-f8e8-460c-b2be-ce607068726c", "f5506c2b-0504-4420-9490-11a4f4d7f49d"] }
]
}
}
Logical operations
AND logical operation
The AND logical operation combines filter conditions, and only items that satisfy all conditions are returned. It is set using the and parameter.
Example:
{
"filter": {
"and": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
}
]
}
}
OR logical operation
The OR logical operation also combines filter conditions, but returns items that satisfy at least one of the conditions. It is set using the or parameter.
Example:
{
"filter": {
"or": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
}
]
}
}
NOT logical operation
The NOT logical operation is used to invert the filtering condition. The result of the search will include items that don’t meet the nested conditions.
The operation is set using the not operator.
Example:
{
"filter": {
"not": {
"eq": [
{"field": "field1"},
{"const": "value1"}
]
}
}
}
Combination of logical operations
You can combine filtering request operations:
{
"filter": {
"not": {
"or": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"and": [
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
},
{
"eq": [
{"field": "field3"},
{"const": "value3"}
]
}
]
}
]
}
}
}