Destination Filters

The Destination Filters API provides fine-grained controls that allow you to conditionally prevent data delivery to specific destinations. You can filter entire events (for example, selectively drop them) or block/allow individual fields in events before you send them. You can conditionally apply filters to each event based on the contents of that event’s payload. For example, you could apply a filter to Track events with a plan property equal to Professional, or you could apply a filter to events with a user email address that does not match *@example.com.

Use Destination Filters to:

• Reduce the delivery volume of events to a Destination to save on costs
• Filter out Personally Identifying Information (PII) from the events sent to a Destination that shouldn't receive or store PII
• Prevent internal user activity from reaching an analytics tool
• Send the events that you care about to an custom webhook

Destination Filters are available to all Business customers and support cloud-based (server-side) and web device-mode destinations. Mobile device-mode destinations are in beta and only support Swift, Kotlin, and React Native 2.0 libraries. S3 and Warehouse Destinations are not yet supported.

There are three filters that can be applied to events:

The allow_properties and drop_properties filters may only filter fields inside the following top-level fields of Segment events:

• properties
• context
• traits

Filters are applied in the following order for each event:

1. drop
2. sample
3. allow_properties
4. drop_properties

Filters can optionally be applied to an event by writing an "if" statement using Filter Query Language ("FQL"), Segment’s simple query language for streaming JSON. FQL statements evaluate to true or false based on the contents of each event, allowing you to only apply filters to specific events.

For example, given the following event payload:

{
  "event": "Button Clicked",
  "type": "track",
  "context": {
    "library": {
      "name": "analytics.js",
      "version": "1.0",
    }
  }
}

The following FQL statements will evaluate to "true", causing the filter to be applied:

• event = 'Button Clicked'
• event = 'Button Clicked' and type = 'track'
• match(context.library.version, '1.*')
• type = 'identify' or type = 'track'

And the following FQL statements will evaluate to "false", causing the filter to be skipped:

• event = 'Screen Tapped'
• context.path.path = '/login'
• match (context.library.version, '2.*')

For more detailed documentation including a list of all operators and functions, see the FQL Documentation.

To apply a filter to all events going to a destination, you can supply an "if" statement of "all". All actions in that filter will be applied to events before being delivered to that destination.

Destination Filters currently have the following limits:

• Each Destination may have no more than 10 filters.
• FQL "if" statements may be a maximum of 3Kb in size.
• Filters may have a maximum of 4 actions.
• Allow / Drop properties filters may target a maximum of 8 objects and each object may have a maximum of 64 fields in the allow or drop.
• The Preview API "input" payload may be a maximum of 128Kb.

If you would like any of these limits lifted, please reach out to Segment at friends@segment.com.

Filter

Drop

The drop action will cause the event to be dropped and not sent to the destination if the "if" statement evaluates to true.

Sample

The sample action will allow only a percentage of events through. It can sample randomly or, if given a path attribute, it can sample a percentage of events based on the contents of a field. This is useful for sampling all events for a percentage of users rather than a percentage of all events for all users.

Allow properties

The allow_properties action takes a list of nested objects (for example, context, properties.orderDetails) and a list of fields for each object that should be allowed, with all other fields in those objects dropped.

Drop properties

The drop_properties action takes a list of nested objects (for example, context, properties.orderDetails) and a list of fields for each object that should be dropped, with all other fields in those objects untouched.

Type property

Fields property

The type of fields property has been changed:

Field list

To migrate, replace any usages of the Config API endpoints with the Segment Public API counterparts, using the field mappings in the table above.