# Filtering

Filters allow to restrict the response of list endpoints. The available filter options for a supported list endpoint are returned by the filter options endpoint (e.g. /v3/assets/filter-options-v2).

## Get asset list

<mark style="color:green;">`POST`</mark> `https://api.akenza.io/v3/assets/list`

Filter the asset inventory

#### Query Parameters

| Name | Type     | Description                    |
| ---- | -------- | ------------------------------ |
| page | Interger | Page number (default 0)        |
| sort | String   | Sort string (field, direction) |

#### Request Body

| Name           | Type       | Description            |
| -------------- | ---------- | ---------------------- |
| organizationId | String     | Id of the organization |
| workspaceIds   | List       | List of workspace ids  |
| expression     | Expression | Filter expression      |
| search         | String     | Search string          |

{% tabs %}
{% tab title="200: OK List of assets" %}

{% endtab %}
{% endtabs %}

Endpoints that support the filter format described on this page:

* :white\_check\_mark: get asset list (/v3/assets/list)

## Filter options request

The filter options endpoint response contains information about the supported fields, their type, and supported predicates.

### Filter options

The filter options part contains all filterable fields. Each option provides the applicable filterTypes and can list available values.&#x20;

### Definitions

The definitions define the supported predicates based on the filterType.&#x20;

### Supported Predicates

The supported predicates contain the supported predicates by filterType.

### Predicates

Depending on the predicate a different amount of values are expected.

<table><thead><tr><th width="290">Predicate</th><th width="168">Number of values</th><th>Explanation</th></tr></thead><tbody><tr><td>EQUALS</td><td>1</td><td>This predicate checks for an exact match. For strings, it is case-insensitive</td></tr><tr><td>NOT_EQUALS</td><td>1</td><td>This predicate returns the inverse of EQUALS including null values</td></tr><tr><td>IN</td><td>1+</td><td>This predicate checks if one field value matches one of the values</td></tr><tr><td>NOT_IN</td><td>1+</td><td>This predicate returns the inverse of in</td></tr><tr><td>LESS_THAN</td><td>1</td><td>This predicate checks if the field value is less than the value</td></tr><tr><td>LESS_THAN_OR_EQUALS</td><td>1</td><td>This predicate checks if the field value is less than or equal to the value</td></tr><tr><td>LESS_THAN</td><td>1</td><td>This predicate checks if the field value is greater than the value</td></tr><tr><td>GREATER_THAN_OR_EQUALS</td><td>1</td><td>This predicate checks if the field value is greater than or equal to the value</td></tr><tr><td>BETWEEN</td><td>2</td><td>This predicate checks if the field value is between the two provided values. The order of values will automatically be ensured</td></tr><tr><td>CONTAINS_ALL</td><td>1+</td><td>This predicate checks that the list field value contains all values</td></tr><tr><td>CONTAINS_NONE</td><td>1+</td><td>Works like NOT_IN but is used for list fields</td></tr><tr><td>CONTAINS_ANY</td><td>1+</td><td>Works like IN but is used for list fields</td></tr><tr><td>CONTAINS</td><td>1</td><td>This predicate checks if a string contains a given value</td></tr><tr><td>STARTS_WITH</td><td>1</td><td>This predicate checks if a string starts with a given value</td></tr><tr><td>ENDS_WITH</td><td>1</td><td>This predicate checks if a string ends with a given value</td></tr><tr><td>BEFORE</td><td>1</td><td>checks if a date is before the given value</td></tr><tr><td>AFTER</td><td>1</td><td>checks if a date is after the given value</td></tr><tr><td>IS_NULL</td><td>0</td><td>checks if a field value is not set </td></tr><tr><td>IS_NOT_NULL</td><td>0</td><td>checks if a field value is set</td></tr></tbody></table>

## Filter Expressions

There are two constructs that can be set as an expression, the expression list and a Filter.

A filter is has three fields, the field name, a predicate and a list of values. The amount of values differ by the used predicate.

```json
{
    "field" : "id",
    "predicate" : "IN",
    "values": [
         "6600000000000000",
         "6600000000000001",
         "6600000000000002"
     ]
}
```

An expression list is used to combine multiple expressions and contains only two fields the operator and the a list of expressions. The operator which defines how the containing expressions are combined, it can be ether AND or OR. The expressions list has a max depth of 3.

```json
{
  "operator": "AND",
  "expressions": [
    {
      "operator": "OR",
      "expressions": [
        ...
      ]
    },
    {
      "operator": "FILTER",
      "field": "uplinkMetrics.timestamp",
      "predicate": "BETWEEN",
      "values": [
        1693815659321,
        1693815359321
      ]
    },
    ...
  ]
}
```

Example:

```json
{
    "search": "abc",
    "organizationId": "280000000000000",
    "expression": {
        "operator": "AND",
        "expressions": [
            {
                "field": "id",
                "predicate": "IN",
                "values": [
                    "0200000000000000",
                    "0200000000000001",
                    "0200000000000002"
                ]
            },
            {
                "operator": "OR",
                "expressions": [
                    {
                        "field": "name",
                        "predicate": "STARTS_WITH",
                        "values": [
                            "someething"
                        ]
                    },
                    {
                        "field": "name",
                        "predicate": "ENDS_WITH",
                        "values": [
                            "else"
                        ]
                    }
                ]
            },
            {
                "field": "customFields",
                "predicate": "EQUALS",
                "stringValues": ["Zurich"],
                "customFieldName": "Location"
            },
            {
              "field": "tags.name",
              "values": ["test"],
              "predicate": "CONTAINS_ALL"
            }
        ]
    }
}
```