A **Filter Definition** is a filter template that queries track events and profile properties. The filter definition defines a list of parameters, so multiple event segments can use same filter definition with different parameter values. Optimizely Profile Store has the following types of filter definitions.

• **Events Filter Definition** – Defines a [KQL query](🔗) template to query track events. The Events filter definition builds a list of device IDs from the matching events.

• **Profiles Filter Definition** – Defines an OData query template to query profiles. The device IDs are used in event segment  to match profiles.

## Filter Definition properties

The `FilterDefinitionPostRequest` is used in the **Create Filter Definition** endpoint. It contains the following property fields.

• `Name` – _Required_. Name of the filter definition; contains letters (a-z, A-Z) , numbers (0-9), period (.), underline (\_), and dash (-) only.

• `Description` – Description of the filter definition.

• `Query` – _Required_. The KQL query to find events, or OData query to find profiles. Query could contain Parameters. An example of query is:

  Text

  

• `Parameters` – The collection of parameter definitions which are used in the Query. Parameter name can contain letters (a-z, A-Z) only. A parameter supports the following types:

  • `bool` – Boolean type.

  • `datetime` – Date time type.

  • `guid` – Globally unique identifier type.

  • `int` – Integer type.

  • `long` –  64-bit integer type.

  • `double` – Double-precision floating-point format type.

  • `string` – String type.

  • `timespan` – Timespan type.

    An example of a parameterized query:

    Text

    

    Where `eventType` and takeTop are the KQL-defined parameters, and name and minimumVisits are OData parameters.

• `Category` – Filter definition category. `Category` can contain up to 50 characters of any string except backslash (\).

• `Type` – Filter definition type. Currently, it supports `Events` and `Profiles` type.

**Example**

The `FilterDefinitionPutRequest` is used in the **Replace Filter Definition** endpoint. It contains all the properties in `FilterDefinitionPostRequest` except the `Name` field.

## Filter Definition methods

### Get filter definition

Endpoint: **GET api/v2.0/filterdefinitions/{id}**

Returns HTTP 200 OK with the filter definition specified by {id}.

Example of response body:

### List filter definitions

Endpoint: **GET api/v2.0/filterdefinitions**

List all filter definitions in the current environment. The result window size is limited to the top 10,000 records.

📘

Note

Unlike profiles and events, there is no OData query support to match filter definitions with given conditions.

### Create filter definition

Endpoint: **POST api/v2.0/filterdefinitions**

Example of request body (FilterDefinitionPostRequest):

Example of response body:

📘

Note

Prefix fd\_ is added to the filter defintion name as the value of id property.

### Replace filter definition

Endpoint: **PUT api/v2.0/filterdefinitions/{id}**

📘

Note

A filter definition cannot be replaced if any segment is using it. By doing so, a list of affected segments return in the error response.

Remove all filters connected to the filter definition in the affected segments before replacing it.

Example of request body (`FilterDefinitionPutRequest`):

Example of response body:

### Delete filter definition

Endpoint: **DELETE api/v2.0/filterdefinitions/{id}**

📘

Note

You cannot delete a filter definition if any segment is using it. If you try to do so, a list of affected segments is returned in the error response. Before deleting a filter definition, remove the filters connected to it in the affected segments.

### Preview filter definition

Endpoint: **POST api/v2.0/filterdefinitions/{id}/preview **

You can preview a filter definition result, mainly to check if the result produced by a query is correct.

You should create a filter definition before previewing it. Then, request the preview endpoint with a request body.

Example of a filter definition:

Example of a request body (`FilterDefinitionPreviewRequest`):