Filter Definition

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:

    Events | take 10​
  

• 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:

      KQL: Events | where EventType == {{eventType}} and EventTime >= (now()-300d) | take {{takeTop}}
      OData: Name eq {{name}} AND Visits gt {{minimumVisits}}
    

    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

{
      "Name"        : "string",
      "Description" : "string",
      "Query"       : "string",
      "Category"    : "string",
      "Type"        : "Events",
      "Parameters"  : {
                        "Parameter1" : "string",
                        "Parameter2" : "string"
                      }
    }

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:

{
      "Id"          : "fd_TopEvents",
      "Name"        : "TopEvents",
      "Description" : "Loads top events for a event type.",
      "Query"       : "Events | where EventType == {{eventType}} and EventTime >= (now()-300d) | take {{takeTop}}",
      "Category"    : "TopEvents",
      "Type"        : "Events",
      "Parameters"  : {
                        "eventType" : "string",
                        "takeTop"   : "int"
                      }
    }

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):

{
      "Name"        : "TopEvents",
      "Description" : "Loads top events for a event type.",
      "Query"       : "Events | where EventType == {{eventType}} and EventTime >= (now()-300d) | take {{takeTop}}",
      "Category"    : "TopEvents",
      "Type"        : "Events",
      "Parameters"  : {
                        "eventType" : "string",
                        "takeTop"   : "int"
                      }
    }

Example of response body:

{
      "Id"          : "fd_TopEvents",
      "Name"        : "TopEvents",
      "Description" : "Loads top events for a event type.",
      "Query"       : "Events | where EventType == {{eventType}} and EventTime >= (now()-300d) | take {{takeTop}}",
      "Category"    : "TopEvents",
      "Type"        : "Events",
      "Parameters"  : {
                        "eventType" : "string",
                        "takeTop"   : "int"
                      }
    }

📘

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):

{
      "Description" : "Loads top events for a event type.",
      "Query"       : "Events | where EventType == {{eventType}} and EventTime >= (now()-300d) | take {{takeTop}}",
      "Category"    : "TopEvents",
      "Type"        : "Events",
      "Parameters"  : {
                        "eventType" : "string",
                        "takeTop"   : "int"
                      }
    }

Example of response body:

{
      "Id"          : "fd_TopEvents",
      "Name"        : "TopEvents",
      "Description" : "Loads top events for a event type.",
      "Query"       : "Events | where EventType == {{eventType}} and EventTime >= (now()-300d) | take {{takeTop}}",
      "Category"    : "TopEvents",
      "Type"        : "Events",
      "Parameters"  : {
                        "eventType" : "string",
                        "takeTop"   : "int"
                      }
    }

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:

{
      "Id"         : "fd_filterdefinitionid", 
      "Name"       : "filterdefinitionname", 
      "Query"      : "Events | where DeviceId == stringParameter | take intParameter", //KQL Query
      "Parameters" : { 
                       "stringParameter": "string",
                       "intParameter": "int", 
                     },
      "Type"       : "Events"
    }

Example of a request body (FilterDefinitionPreviewRequest):

{
      "Take"       : 100, //optional, maximum to 1000 records
      "Parameters" : {
                       "stringParameter" : "value1",
                       "intParameter"    : 1
                     }
    }