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 operation available:
- Table operations: These allow you to create a comprehensive set of fields for filtering.
- Condition operations: These allow you to create a single filtering condition.
- Logic operations: These allow you to combine, merge, and nest conditions.
Table operation
Table operations allow you to filter based on app item fields with specific conditions. Each type of field can have its own way of setting conditions. The filter can combine fields and search conditions, returning only those app items that meet all the entered conditions.
To filter, add the tf parameter to your request.
Example:
{
"filter": {
"tf": {
"title": "white",
"description":"color with code"
}
}
}
For string fileds, you should specify the 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"
}
}
}
For number 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.
Example:
{
"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.
Example:
{
"filter": {
"tf": {
"weight": {
"min": 1,
"max": null
}
}
}
}
For date fields, specify the interval. Keep in mind that:
- TIme is specified in timezone +00.
- If field settings have been changed from Date to Time or vice versa, the data that had been enetered before may not meet the filter criteria. Before applying the filter you should 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 second one.
Example:
{
"filter": {
"tf": {
"__createdAt": {
"min": "2023-04-11T00:00:00Z",
"max": null
}
}
}
}
We recommend including the time in the filter 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"
}
}
}
}
For Yes/No fields, specify the value you are looking for: false or true.
Example:
{
"filter": {
"tf": {
"opened": true
}
}
}
For Phone fields, you should specify the string that is expected to be included in the app item field. It doesn't matter if the phone number has separators.
Example:
{
"filter": {
"tf": {
"phone": "7-999-11"
}
}
}
For Email fields, you should use the email address as string that is expected to be included in the app item field. The filter is case-insensitive.
Example:
{
"filter": {
"tf": {
"email": "admin@admin.com"
}
}
}
For Full Name fields, you should specify the 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": {
"fio": "Jerry"
}
}
}
For Status fields, specify the array with status numbers.
Example:
{
"filter": {
"tf": {
"__status": [2,3]
}
}
}
For User fields, specify the user's uuid.
Example:
{
"filter": {
"tf": {
"user": "47cfc3d3-279d-441e-a245-a27adaac81e8"
}
}
}
For Users field of the "many" type, also specfy just one user you are looking for.
Example:
{
"filter": {
"tf": {
"users": "47cfc3d3-279d-441e-a245-a27adaac81e8"
}
}
}
To search across fields of the App type, specify the item's identifier: uuid.
Example:
{
"filter": {
"tf": {
"myApp": {
"id":"7730e64b-551b-4eda-bb49-b0120e9712eb",
}
}
}
}
To search across fields of the Arbitraty app type, specify the item's identifiers: uuid, code, and namespace
Example:
{
"filter": {
"tf": {
"myRandomApp": {
"id":"7730e64b-551b-4eda-bb49-b0120e9712eb",
"code":"myApplication",
"namespace":"myNamespace",
"inTrash":false
}
}
}
}
To search across fields of the Catogory type, specify the code of the enumeration item:
{
"filter": {
"tf": {
"errStatus":"blocker"
}
}
}
Condition operations
These operations require two parameters:
- The first is the required
filedparameter, which specifies the name of the field that you want to filter by. - The second parameter specifies the condition. You can use the
constconstruction for a single condition, and thelistcondition for multiple conditions. If you need to specify an empty condition, use null.
Example of a single condition:
{
"eq": [
{"field": "weight"},
{"const": 5}
]
}
Example of a multiple 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
For strings, ecnlose the string in quotation marks.
Example:
{
"filter": {
"eq": [
{"field": "stringField"},
{"const": "MyStringValue"}
]
}
}
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}
]
}
}
For the Money data type, specify a number representing the smalles 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}
]
}
}
For fields with date and/or time, enclose the value in quotation marks. Keep in mind that:
- The time is specified in timezone +00.
- If field settings have been changed from date to time or vice versa, then data that had been enetered before may not meet the filter criteria. Before applying the filter you should analyze the stored data.
We recommend including the 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"}
]
}
}
For Yes/No fields, use true or false to specify the condition.
Example:
{
"filter": {
"eq": [
{"field": "boolField"},
{"const": true}
]
}
}
Fpr Phone fields, use the phone number as a string, with or without separators.
Example:
{
"filter": {
"eq": [
{"field": "phoneField"},
{ "const": "+71234566780"}
]
}
}
For Email fields, use the email address as a string.
Example:
{
"filter": {
"eq": [
{"field": "emailFiled"},
{"const": "example@example.example"}
]
}
}
For Full Name fields, specify the string. Since data stored in Full Name fields is not regular, the number of available operations is limited. We recommend using the like operator.
Example:
{
"filter": {
"like": [
{"field": "fioFiled"},
{"const": "Siobane"}
]
}
}
For Status fields, specify the number of the status.
Example:
{
"filter": {
"in": [
{"field": "__status"},
{ "list": [1,2]}
]
}
}
For User 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"}
]
}
}
For App type fields, use the string representation of the app item's uuid. Regardless of whether the field is of "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"]}
]
}
}
For Category fields, use the string code of the enumeration item.
Example:
{
"filter": {
"eq": [
{"field": "enumFiled"},
{"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 construction.
The "Inequality" operation allows you to set a filtering condition that is the opposite of the "Equality" operation. It is specified using the neqconstruction.
Example of using the equality operation for an integer:
{
"filter": {
"eq": [
{"field": "weight"},
{"const": 5}
]
}
}
Example of using the equality operation for an date:
{
"filter": {
"eq": [
{"field": "ttlEnd"},
{"const": "2023-04-12T11:11:45.367Z"}
]
}
}
Example of using the inequality operation for a Yes/No 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
]
}
}
Operations: "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 construction.
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 construction.
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 ltconstruction.
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 construction.
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 matching" operation
The "Substring matching" operation enables filtering based on partial matches by using the like construction.
Example of searching for a partial match for a string:
{
"filter": {
"like": [
{"field": "__name"},
{"const": "city"}
]
}
}
"Membership in Set" and "Non-membership in Set" operations
The "Membership in 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 inconstruction.
The "Non-membership in 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_inconstruction.
Example for searching based on membership of the field value in a list of allowed values:
{
"filter": {
"in": [
{"field": "weight"},
{ "list": [1, 11] }
]
}
}
Example for searching based on non-membership of a Category field value in a list of not allowed values:
{
"filter": {
"not_in": [
{"field": "enum"},
{ "list": ["Number1", "Number3", "Number5"] }
]
}
}
"Linked Collection" operation
The "Linked collection" operation allows for filtering based on whether a "many" App-type field belongs to a linked collection using the linkconstruction.
Example:
{
"filter": {
"link": [
{"field": "fewApps"},
{ "list": ["f5506c2b-0504-4420-9490-11a4f4d7f49d", "e20379bc-2f80-4b63-9e77-fbb3fa50e362"] }
]
}
}
"Set Membership" operation
The "Set membership" operation allows for filtering based on whether the value of a "many" field is a member of a set predefined as condition. The allconstruction is used.
Example of searching 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 operation
"Logical AND" operation
The "Logical AND" operation combines filter conditions, and only elements that satisfy all the conditions are returned. It is set using the andconstruction.
Example:
{
"filter": {
"and": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
}
]
}
}
"Logical OR" operation
The "Logical OR" operation also combines filter conditions, but elements that satisfy at least one of the conditions are returned. It is set using the or construction.
Example:
{
"filter": {
"or": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
}
]
}
}
Cobinations of logical operations
You can combine request operations for filtering.
Example:
{
"filter": {
"or": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"and": [
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
},
{
"eq": [
{"field": "field3"},
{"const": "value3"}
]
}
]
}
]
}
}