Space Filters

The Space Filters API provides fine-grained controls that allow you to conditionally prevent data delivery to spaces to ensure only relevant events and profile data are processed, stored and activated on. A space filter applies to events coming from all sources connected to a space. 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.

Space Filters API are available to all Unify and Engage customers.

Note: The Filters API is currently in a Private Beta. If you are interested in joining the Private Beta, please reach out to your customer success manager or friends@segment.com

Either an “Identity admin” or “Profiles and Engage admin” role is required to be able to create, update and delete filters. “Profiles and Engage Read-only” and “Profiles Read-only, Engage User” roles are restricted to preview, get and list filters operations. For more details, see the Segment Roles Documentation

There are three filters that can be applied to events:

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

• properties
• context
• traits

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 space, you can supply an "if" statement of "all". All actions in that filter will be applied to events before being delivered to that space.

Filters currently have the following limits:

• Each Space may have no more than 10 filters.

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

Filter

To simulate the application of a Space filter to a provided JSON payload, please use the Preview Destination Filter endpoint.