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.

Filtering 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"
        }
    }
}

Email

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 const parameter; for a condition with multiple values, the list parameter. If you need to specify an empty condition, use null.

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"}
        ]
    }
}

Email

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"}
                            ]
                        }
                    ]
                }
            ]
        }
    }
}