Search

The search request is a JSON object that may contain:

• limit – the maximum number of results to return (between 1 and 100, default 10);
• offset – the number of items to skip before starting to collect results (between 0 and 10^9, default 0);
• filter – filtering conditions, default no filtering;
• sort – sorting parameters, default desecnding by creation date.

Each of these fields is optional and may be omitted. However, the search request must include at least an empty object {}.

Filter

The filter consists of two object types: FilterCondition and FilterCombination.

FilterCondition

A FilterCondition represents a single search criterion. It includes the following fields:

• property – the field to filter by;
• operator – the comparison operator;
• value – the value to compare against.

INFO

Only strings are accepted as value.

FilterCombination

A FilterCombination is used to group multiple conditions or other combinations. It includes the following fields:

• items – an array of FilterCondition or FilterCombination objects;
• mode – the logical operator to apply (and or or).

This allows building nested and complex filtering logic. You can specify up to 10 items in one FilterCombination. Also, maximum depth level is 5.

Filtering

You can pass a single FilterCondition directly as the filter value, like this:

{
    "filter": {
        "property": "id",
        "operator": "eq",
        "value": "..."
    }
}

This will apply exactly one condition.

Alternatively, you can use a FilterCombination to group multiple FilterCondition or nested FilterCombination objects using logical operators (and, or). For example:

{
    "filter": {
        "mode": "and",
        "items": [
            {
                "mode": "or",
                "items": [
                    {
                        "property": "id",
                        "operator": "eq",
                        "value": "123"
                    },
                    {
                        "property": "id",
                        "operator": "eq",
                        "value": "456"
                    }
                ]
            },
            {
                "property": "color",
                "operator": "eq",
                "value": "blue"
            }
        ]
    }
}

In this case, the query will return all records where color is blue and the id is either 123 or 456.

Supported operators

The following operators are supported:

Operator	Description
eq	Equal to
neq	Not equal to
like	Contains substring (case-sensitive)
nlike	Does not contain substring (case-sensitive)
gt	Greater than
gte	Greater than or equal to
lt	Less than
lte	Less than or equal to

Supported combinations modes

Only two combination modes are supported:

• and (every condition must be true);
• or (at least one condition must be true).

Sort

sort is an array of SortEntry objects. Each SortEntry contains the following fields:

• property – the field to sort by
• direction – the sort order, either asc or desc

You can specify up to 10 sort entries.

Errors

The following are the possible errors that may occur when using search requests. We’ve provided detailed descriptions to help with debugging. However, feel free to contact us at care@widged.io if you need further assistance.

InvalidSearchError

Thrown when search request is invalid. With this error we also provide tree object targeting specific place where error happened.

UnsupportedFilterValueError

Thrown when a filter value is not supported for a given property and operator. For example, when you use evt_ id on records.

UnsupportedFilterOperatorError

Thrown when trying to use an operator that is not supported for a given property.

UnsupportedFilterPropertyError

Thrown when trying to filter by a property that does not support filtering.

UnsupportedSortPropertyError

Thrown when trying to sort by a property that does not support sorting.

UnsupportedSortDirectionError

Thrown when using an invalid sort direction for a property. Valid directions are asc and desc.

TooDeepFilterError

Thrown when the filter nesting depth exceeds the maximum allowed depth.

UnsupportedFilterCombinationModeError

Thrown when using an unsupported filter combination mode. Only and and or modes are supported.

InvalidFilterItemError

Thrown when a filter item cannot be parsed due to invalid format or structure. This occurs when the provided object is neither a FilterCondition nor a FilterCombination.

InternalError

An unexpected error occurred. Please contact care@widged.io for assistance.