Skip to content

Commit 93306d9

Browse files
markzegarellistayseesong
markzegarelli
and
stayseesong
authored
Linking to FQL from Destination Filters doc (#2421)
* Linking to FQL from Destination Filters doc * Update src/connections/destinations/destination-filters.md Co-authored-by: stayseesong <[email protected]> Co-authored-by: stayseesong <[email protected]>
1 parent 5e13839 commit 93306d9

File tree

2 files changed

+46
-65
lines changed

2 files changed

+46
-65
lines changed

‎src/config-api/fql.md

Lines changed: 44 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,12 @@
11
---
22
title: Destination Filter Query Language
3-
hidden: true
43
---
54

65
Destination Filter Reference documentation can be found in the [main Config API reference docs](https://reference.segmentapis.com/#6c12fbe8-9f84-4a6c-848e-76a2325cb3c5).
76

8-
Filter Query Language ("FQL") is a simple language for filtering JSON objects
9-
used by the Transformations API to conditionally apply transformations. In the
10-
Transformations API, FQL statements evaluate to `true` or `false` based on the
11-
contents of each Segment event. If the statement evaluates to `true`, the
12-
transformation is applied, and if it is `false` the transformation is not applied.
7+
Filter Query Language ("FQL") is a simple language for filtering JSON objects used by the Transformations API to conditionally apply transformations. In the Transformations API, FQL statements 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.
138

14-
In addition to boolean and equality operators like `and` and `>=`, FQL has
15-
built-in functions that make it more powerful such as `contains( str, substr )`
16-
and `match( str, pattern )`.
9+
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 )`.
1710

1811
## Examples
1912

@@ -53,7 +46,7 @@ properties like `userId` or `event` as well as nested properties like
5346
`context.library.version` or `properties.title` using dot-separated paths. For
5447
example, the following fields can be pointed to by the associated field paths:
5548

56-
```
49+
```json
5750
{
5851
"type": "...", // type
5952
"event": "...", // event
@@ -70,9 +63,7 @@ example, the following fields can be pointed to by the associated field paths:
7063

7164
### Escaping Field Paths
7265

73-
If your field name has a character not in the set of `{a-z A-Z 0-9 _ -}`, you
74-
must escape it using a `\` character. For example, the nested field
75-
below can be referred to by `properties.product\ 1.price`:
66+
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`:
7667

7768
```json
7869
{
@@ -96,7 +87,7 @@ below can be referred to by `properties.product\ 1.price`:
9687
### Unary
9788

9889
| Operator | Right Side | Result |
99-
|----------|------------|------------------------------|
90+
| -------- | ---------- | ---------------------------- |
10091
| `!` | `bool` | Negates the right-hand side. |
10192

10293
### Comparison
@@ -112,30 +103,29 @@ below can be referred to by `properties.product\ 1.price`:
112103

113104
## Subexpressions
114105

115-
You can use parentheses to group subexpressions for more complex "and / or"
116-
logic as long as the subexpression evaluates to true or false:
106+
You can use parentheses to group subexpressions for more complex "and / or" logic as long as the subexpression evaluates to true or false:
117107

118-
| FQL |
119-
| ------------------------------------------------------------------------------------------------------------------------------ |
120-
| `type = 'track' and ( event = 'Click' or match( 'Button *', event ) )` |
121-
| `( type = 'track' or type = 'identify' ) and ( properties.enabled or match( traits.email, '*@company.com' ) )` |
108+
| FQL |
109+
| -------------------------------------------------------------------------------------------------------------- |
110+
| `type = 'track' and ( event = 'Click' or match( 'Button *', event ) )` |
111+
| `( type = 'track' or type = 'identify' ) and ( properties.enabled or match( traits.email, '*@company.com' ) )` |
122112

123113
## Functions
124114

125-
| Function | Return Type | Result |
126-
| ----------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
127-
| `contains( s string, sub string )` | `bool` | Returns `true` if string `s` contains string `sub`. |
115+
| Function | Return Type | Result |
116+
| ----------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
117+
| `contains( s string, sub string )` | `bool` | Returns `true` if string `s` contains string `sub`. |
128118
| `length( list or string )` | `number` | Returns the number of elements in a list or number of bytes (not necessarily characters) in a string. For example, `a` is 1 byte and`ア` is 3 bytes long. |
129-
| `lowercase( s string )` | `string` | Returns `s` with all uppercase characters replaced with their lowercase equivalent. |
130-
| `typeof( value )` | `string` | Returns the type of the given value: `"string"`, `"number"`, `"list"`, `"bool"`, or `"null"`. |
131-
| `match( s string, pattern string )` | `bool` | Returns `true` if the glob pattern `pattern` matches `s`. See below for more details about glob matching. |
119+
| `lowercase( s string )` | `string` | Returns `s` with all uppercase characters replaced with their lowercase equivalent. |
120+
| `typeof( value )` | `string` | Returns the type of the given value: `"string"`, `"number"`, `"list"`, `"bool"`, or `"null"`. |
121+
| `match( s string, pattern string )` | `bool` | Returns `true` if the glob pattern `pattern` matches `s`. See below for more details about glob matching. |
132122

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

137127
| Function | Result |
138-
|----------------------------|----------|
128+
| -------------------------- | -------- |
139129
| `contains( null, string )` | `false` |
140130
| `length( null )` | `0` |
141131
| `lowercase( null )` | `null` |
@@ -144,39 +134,30 @@ For example, you can write `length( userId ) > 0` instead of `typeof( userId ) =
144134

145135
### `match( string, pattern )`
146136

147-
The `match( string, pattern )` function uses "glob" matching to return `true` if
148-
the given string fully matches a given pattern. Glob patterns are case
149-
sensitive. If you only need to determine if a string contains a given substring,
150-
you should use `contains()`.
151-
152-
| Pattern | Summary |
153-
| ------- | -------------------------------------------------------------------------------------------------------------- |
154-
| `*` | Matches zero or more characters. |
155-
| `?` | Matches one character. |
156-
| `[abc]` | Matches one character in the given list. In this case, `a`, `b`, or `c` will be matched. |
157-
| `[a-z]` | Matches a range of characters. In this case, any lowercase letter will be matched. |
158-
| `\x` | Matches the character `x` literally. This is useful if you need to match `*`, `?` or `]` literally. E.g. `\*`. |
159-
160-
| Pattern | Result | Reason |
161-
| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
162-
| `match(` `'abcd', 'a*d' )` | `true` | `*` matches zero or more characters. |
163-
| `match( '', '*' )` | `true` | `*` matches zero or more characters. |
164-
| `match( 'abc', 'ab' )` | `false` | The pattern must match the full string. |
165-
| `match( 'abcd', 'a??d' )` | `true` | `?` matches one character only. |
166-
| `match( 'abcd', '*d' )` | `true` | `*` matches one or more characters even at the beginning or end of the string. |
167-
| `match( 'ab*d', 'ab\*d' )` | `true` | `\*` matches the literal character `*`. |
168-
| `match( 'abCd', 'ab[cC]d' )` | `true` | `[cC]` matches either `c` or `C`. |
169-
| `match( 'abcd', 'ab[a-z]d' )` | `true` | `[a-z]` matches any character between `a` and `z`. |
170-
| `match( 'abcd', 'ab[A-Z]d' )` | `false` | `[A-Z]` matches any character between `A` and `Z` but `c` is not in that range because it is lowercase. |
171-
172-
## Errata
173-
174-
### Error Handling
175-
176-
If your FQL statement is invalid (for example `userId = oops"`), your Segment
177-
event will not be sent on to downstream Destinations. We default to not sending
178-
the event to ensure that invalid FQL doesn't cause sensitive information like
179-
PII to be incorrectly sent to Destinations.
180-
181-
For this reason, we strongly recommend that you use the Destination Filters
182-
"Preview" API to test your filters without impacting your production data.
137+
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 a given substring, you should use `contains()`.
138+
139+
| Pattern | Summary |
140+
| ------- | ---------------------------------------------------------------------------------------------------------------------- |
141+
| `*` | Matches zero or more characters. |
142+
| `?` | Matches one character. |
143+
| `[abc]` | Matches one character in the given list. In this case, `a`, `b`, or `c` will be matched. |
144+
| `[a-z]` | Matches a range of characters. In this case, any lowercase letter will be matched. |
145+
| `\x` | Matches the character `x` literally. This is useful if you need to match `*`, `?` or `]` literally. For example, `\*`. |
146+
147+
| Pattern | Result | Reason |
148+
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
149+
| `match(` `'abcd', 'a*d' )` | `true` | `*` matches zero or more characters. |
150+
| `match( '', '*' )` | `true` | `*` matches zero or more characters. |
151+
| `match( 'abc', 'ab' )` | `false` | The pattern must match the full string. |
152+
| `match( 'abcd', 'a??d' )` | `true` | `?` matches one character only. |
153+
| `match( 'abcd', '*d' )` | `true` | `*` matches one or more characters even at the beginning or end of the string. |
154+
| `match( 'ab*d', 'ab\*d' )` | `true` | `\*` matches the literal character `*`. |
155+
| `match( 'abCd', 'ab[cC]d' )` | `true` | `[cC]` matches either `c` or `C`. |
156+
| `match( 'abcd', 'ab[a-z]d' )` | `true` | `[a-z]` matches any character between `a` and `z`. |
157+
| `match( 'abcd', 'ab[A-Z]d' )` | `false` | `[A-Z]` matches any character between `A` and `Z` but `c` is not in that range because it is lowercase. |
158+
159+
## Error Handling
160+
161+
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.
162+
163+
For this reason, Segment recommends that you use the Destination Filters "Preview" API to test your filters without impacting your production data.

‎src/connections/destinations/destination-filters.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Common use cases for Destination Filters include the following:
1515
- Preventing test or internally-generated events from reaching your production tools
1616

1717
> note ""
18-
> **Note**: Destination Filters are available to Business Tier customers only.
18+
> Destination Filters are available to Business Tier customers only.
1919
2020
### Destination Filtering Limitations
2121

@@ -42,7 +42,7 @@ To create a Destination Filter, follow these steps:
4242

4343
## Destination Filters API
4444

45-
The Destination Filters API provides more power than the Segment dashboard's Destination Filters settings. With the API, You can create complex filters that are conditionally applied using Segment's Filter Query Language (FQL).
45+
The Destination Filters API provides more power than the Segment dashboard's Destination Filters settings. With the API, you can create complex filters that are conditionally applied using Segment's [Filter Query Language (FQL)](/docs/config-api/fql).
4646

4747
The Destination Filters API offers four different filter types:
4848

0 commit comments

Comments
 (0)