Destination Filter Query Language

Destination Filter Reference documentation can be found in the main Config API reference docs.

The Transformations API uses Filter Query Language (FQL) to filter JSON objects and conditionally apply transformations. You can use FQL statements to:

• Apply filters that evaluate to true or false based on the contents of each Segment event. If the statement evaluates to true, the transformation is applied, and if it is false the transformation is not applied.
• Define new properties based on the result of an FQL statement.

In addition to boolean and equality operators like and and >=, FQL has built-in functions that make it more powerful such as contains( str, substr ) and match( str, pattern ).

Examples

Given the following JSON object:

{
  "event": "Button Clicked",
  "type": "track",
  "context": {
    "library": {
      "name": "analytics.js",
      "version": "1.0"
    }
  },
  "properties": {
    "features": ["discounts", "dark-mode"]
  }
}

The following FQL statements will evaluate as follows:

Field Paths

FQL statements may refer to any field in the JSON object including top-level properties like userId or event as well as nested properties like context.library.version or properties.title using dot-separated paths. For example, the following fields can be pointed to by the associated field paths:

{
  "type": "...",       // type
  "event": "...",      // event
  "context": {         // context
    "library": {       // context.library
      "name": "..."    // context.library.name
    },
    "page": {          // context. page
      "path": "...",   // context.page.path
    }
  }
}

Escaping Field Paths

If your field name has a character not in the set of {a-z A-Z 0-9 _ -}, you must escape it using a \ character. For example, the nested field below can be referred to by properties.product\ 1.price:

{
  "properties": {
    "product 1": {
      "price": "19.99"
    }
  }
}

Operators

Boolean

Unary

Comparison

Subexpressions

You can use parentheses to group subexpressions for more complex “and / or” logic as long as the subexpression evaluates to true or false:

Functions

Functions handle null with sensible defaults to make writing FQL more concise. For example, you can write length( userId ) > 0 instead of typeof( userId ) = 'string' and length( userId ) > 0.

match( string, pattern )

The match( string, pattern ) function uses “glob” matching to return true if the given string fully matches a given pattern. Glob patterns are case sensitive. If you only need to determine if a string contains another string, you should use contains().

Error Handling

If your FQL statement is invalid (for example userId = oops"), your Segment event will not be sent on to downstream Destinations. Segment defaults to not sending the event to ensure that invalid FQL doesn’t cause sensitive information like PII to be incorrectly sent to Destinations.

For this reason, Segment recommends that you use the Destination Filters “Preview” API to test your filters without impacting your production data.