# Filtering

Filtering allows API consumers to only retrieve the desired records and not the whole data set. There are two ways to filter the data returned by the `/data` endpoint.

## Predefined Knowledge Model Filters

1. Apply filters pre-defined in the Knowledge Model by using the `filters` query parameter. 
`Filters:` A comma-separated list of filter ids.  

Note that:
  * The Celonis Platform Knowledge Model allows filters to be defined using the FILTER PQL operator as explained in the [Celonis Platform documentation](https://docs.celonis.com/en/knowledge-model---filters.html).
  * You can apply multiple filters by providing multiple filter ids separated by commas or use the `filters` parameter multiple times.
  * Remember this parameter is case sensitive. The filter ids must match the one returned by the filter schema endpoint (`/knowledge-models/{km_id}/filters`).


**Example:**


```
filters=not_null_orders,delayed_orders or filters=not_null_orders&filters=delayed_orders
```

## Ad-hoc Filter Expressions

1. Filter expression using the `filterExpr` query parameter.
This parameter allows filtering of record data using a provided value of a field through an expression.


### Legacy Filter Expressions

1. **First pattern `field operator value` where:**
  * `field` is a filterable attribute, augmented attribute or flag of a record. **This value is case-sensitive and should be equal to the attribute id.**
  * `operator` is a comparison operator. For this pattern, it is currently supported by following operators:
    * **`eq(=), gt(>), lt(<), ne(!=), ge(>=), le(<=), is(IS) and in(IN)`**
  * `value` is a constant, such as a Salesforce Opportunity ID or a number/text.
2. **Second pattern `operator(field,value)` where:**
  * `operator` is a string search operator,similar to the LIKE in the SQL clause. For this pattern, it is currently supported by following operators:
    * **`startswith, endswith and contains`**


It is also possible to combine filters with **logical operators `and, or, not` and parenthesis**.

* Example of the first pattern

```
filterExpr=field1 eq value,field2 ne value
```
* Example of the second pattern

```
filterExpr=startswith(field1,value),contains(field2,value)
```
* Example with first pattern, second pattern and `or`

```
filterExpr=startswith(field1,value) or filed3 eq value,contains(field2,value) or field3 eq value
```
* Example with `not`

```
filterExpr=not startswith(field1,value) or filed3 eq value,not (contains(field2,value) or field3 eq value)
```


**Example:**


```
{
    "page": 0,
    "pageSize": 100,
    "total": 1,
    "sort": [],
    "content": {
        "headers": [
            {
                "id": "description",
                "name": "Description",
                "type": "string",
                "aggregation": false,
        ===>    "filterable": true,  
                "sortable": true
            }
            {
                "id": "count",
                "name": "Count",
                "type": "integer",
                "aggregation": true,
        ===>    "filterable": false,
                "sortable": true
            }
        ],
        "data": [
            {
                "description": "total"
                "count": 50
            }
        ]
    }
}
```

You can apply multiple filters separated by commas or use the `filterExpr` parameter multiple times separated by “&”.

**Example:**

`filterExpr=opportunity_id eq AA00022475H, opportunity_value gt 50000`


```
filterExpr=opportunity_id eq AA00022475H& 
filterExpr=opportunity_value gt 50000
```

Important Note
If your `filterExpr` value contains special characters such as spaces, quotes, `&`, `(`, or `)`, make sure to URL-encode only the query parameter value (not the full URL) before sending the request.

For example, while `&` is used to separate query parameters, an unencoded `&` inside the filter expression will be interpreted as a parameter separator and break the request.

See [URL Encoding of Query Parameters](/process-intelligence-apis/knowledge-model-api/features/url-encoding) for examples.

### New strongly-typed filter expression syntax

Described in detail in [OData Filtering Syntax](/process-intelligence-apis/knowledge-model-api/features/filtering-odata-typed).

### Differences between legacy and new filter expression syntax

| New OData Syntax | Legacy Syntax |
|  --- | --- |
| String values should be single quoted `''` | String values can be unquoted |
| Date values should be in `ISO-8601` format | Date formatting follows [Celonis date format semantics](https://docs.celonis.com/en/using-the-pql-editor.html#UUID-0a810432-93c4-d090-4e7b-9194784fe28e_section-idm234427867703289) |
| Only logical operators `and`, `or`, `not` | Comma (`,`) can be used instead of `and` operator |