You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/connections/destinations/destination-filters.md
+63-60Lines changed: 63 additions & 60 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,100 +3,102 @@ title: Destination Filters
3
3
rewrite: true
4
4
---
5
5
6
-
Destination Filters allow you to control the data flowing into each specific destination by conditionally preventing data from being sent to cloud-mode destinations. You can filter out entire events, or just specific fields in the properties, traits, or in the context of your events.
6
+
Destination Filters let you prevent certain data from flowing into a destination.
7
7
8
-
With Destination Filters, you can:
8
+
Using Destination Filters, you can conditionally filter out event properties, traits, and fields, or even filter out the event itself.
9
9
10
-
- Control your event volume by sampling or dropping unnecessary events for
11
-
specific destinations.
12
-
- Manage PII (personally identifiable information) by blocking fields from
13
-
reaching certain destinations.
14
-
- Increase the relevance of the data in your destinations by removing unused or unwanted data.
15
-
- Prevent test or internally-generated events from reaching your production tools.
10
+
Common use cases for Destination Filters include the following:
11
+
12
+
- Managing PII (personally identifiable information) by blocking fields from
13
+
reaching certain destinations
14
+
- Controlling event volume by sampling or dropping unnecessary events for
15
+
specific destinations
16
+
- Increasing data relevance in your destinations by removing unused or unwanted data
17
+
- Preventing test or internally-generated events from reaching your production tools
16
18
17
19
> note ""
18
-
> **Note**: Destination Filters are currently available to Business Tier customers only.
20
+
> **Note**: Destination Filters are available to Business Tier customers only.
19
21
20
22
### Destination Filtering Limitations
21
23
22
-
- Destination Filters can only be applied to Cloud-mode ("server-side") streaming destinations. Device-mode destinations aren't supported.
24
+
Keep the following limitations in mind when you use Destination Filters:
25
+
26
+
- Destination Filters can only be applied to cloud-mode (server-side) streaming destinations. Device-mode destinations aren't supported.
23
27
- You can't apply Destination Filters to Warehouses or S3 destinations.
24
28
- Each filter can only apply to one source-destination pair.
25
29
26
-
If you have a compelling use case for these unsupported options, [contact Segment](https://segment.com/help/contact/).
30
+
[Contact Segment](https://segment.com/help/contact/) if these limitations impact your use case.
27
31
28
32
## Create a Destination Filter
29
-
To create a Destination Filter:
33
+
34
+
To create a Destination Filter, follow these steps:
35
+
30
36
1. Go to **Connections > Destinations** and select your destination.
31
37
2. Click on the **Filters** tab of your destination.
32
38
3. Click **+ New Filter**.
33
39
4. Configure the rules for your filter.
34
-
5.*(Optional)* Click **Load Sample Event** to test your filter to see if the event passes through your filter.
40
+
5.*(Optional)* Click **Load Sample Event** to see if the event passes through your filter.
35
41
6. Click **Next Step**.
36
42
7. Name your filter and click the toggle to enable it.
37
-
6. Click **Save**.
43
+
8. Click **Save**.
38
44
39
45
## Destination Filters API
40
46
41
-
The Destination Filters API provides more power than the Destination
42
-
Filters settings in the Segment dashboard. You can create complex filters
43
-
that are conditionally applied using Segment's "Filter Query Language" (FQL).
47
+
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).
44
48
45
-
The Destination Filters API offers these 4 different types of filters:
49
+
The Destination Filters API offers four different filter types:
46
50
47
-
Filter | Details
48
-
------ | -------
49
-
`drop_event` | Don't send matched events to the destination.
50
-
`sample_event` | Send only a percentage of events through to the destination.
51
-
`whitelist_fields` | Only send whitelisted properties to the destination.
52
-
`blocklist_fields` | Don't send blocklisted properties to the destination.
|`drop_event`| Don't send matched events to the destination.|
54
+
|`sample_event`| Send only a percentage of events through to the destination.|
55
+
|`whitelist_fields`| Only send whitelisted properties to the destination.|
56
+
|`blocklist_fields`| Don't send blocklisted properties to the destination.|
53
57
54
-
Read more in the[Destination Filters API docs](https://reference.segmentapis.com/#6c12fbe8-9f84-4a6c-848e-76a2325cb3c5).
58
+
To learn more, read Segment's[Destination Filters API docs](https://reference.segmentapis.com/#6c12fbe8-9f84-4a6c-848e-76a2325cb3c5).
55
59
56
60
## Examples
57
61
62
+
The following examples illustrate common Destinations Filters use cases.
63
+
58
64
### PII Management
59
65
60
66
Example: Remove email addresses from `context` and `properties`:
61
67
62
-
Property-level whitelisting is available using Segment's API. Use this to perform actions like only send certain traits you know have no PII to a destination, and block
63
-
all other traits in the context or property fields.
68
+
Property-level allowlisting is available with Segment's API. Using Destination Filters, you can configure a rule that removes email addresses from `context` and `properties`. As a result, Segment only sends traits without PII to the destination.
69
+
64
70
65
71
66
72
67
73
### Control Event Volume
68
74
69
-
Example: Only send user signed up and demo requested events:
75
+
This example shows a filter that controls event volume by only sending `User Signed Up`and `Demo Requested` events.
70
76
71
77
72
78
73
79
### Cleaner Data
74
80
75
-
Example: Only send events - only send track calls to Google Analytics:
81
+
This example shows a rule that only sends track calls to Google Analytics.
76
82
77
83
78
84
79
85
### Remove Internal and Test Events From Production Tools
80
86
81
-
Example: Don't send events when the email contains `@segment.com`:
87
+
This rule targets email addresses with internal domains to stop test events from reaching Destinations.
Using the [Destination Filters API](https://reference.segmentapis.com/#6c12fbe8-9f84-4a6c-848e-76a2325cb3c5), you can create a rule to randomly sample video heartbeat events.
95
98
96
99
### Drop Events
97
100
98
-
[This video](https://www.youtube.com/watch?v=47dhAF1Hoco) shows an example of
99
-
filtering events sent to a destination based on the name of the event.
101
+
[Watch this Destination Filters walkthrough](https://www.youtube.com/watch?v=47dhAF1Hoco) to learn how to use event names to filter events sent to destinations.
100
102
101
103
## Important Notes
102
104
@@ -108,49 +110,50 @@ In the example in the video above, if you have a Destination Filter that filters
108
110
109
111
**Error handling**
110
112
111
-
Segment makes effort to ensure that Destination Filters handle unexpected
112
-
situations. For example, if you use the `contains()` FQL function on
113
-
a field and that field is `null`, Segment returns `false` instead of returning an error. If Segment can't reasonably infer your intent, Segment logs an internal error, and drops the event. Segment defaults to this behavior to prevent sensitive information, for example from a PII filter, from getting through.
113
+
Segment makes effort to ensure that destination filters handle unexpected situations. For example, if you use the `contains()` FQL function on `null` field, Segment returns `false` instead of returning an error. If Segment can't infer your intent, Segment logs an internal error and drops the event. Segment defaults to this behavior to prevent sensitive information, like a PII filter, from getting through.
114
114
115
-
Errors aren't exposed in the Event Deliverability tab of your Destination. For help diagnosing unexpectedly missing events when using Destination Filters, [contact Segment](https://segment.com/help/contact/).
115
+
Errors aren't exposed in your Destination's Event Deliverability tab. For help diagnosing missing destination filter events, [contact Segment](https://segment.com/help/contact/).
116
116
117
117
## FAQ
118
118
119
-
**Q: How does destination filters work with array properties?**
119
+
**How do destination filters work with array properties?**
120
120
121
-
Destination Filters can filter properties out of objects nested in an array. For
122
-
example, you can filter out the `price` property of every object in an array at `properties.products`. You can also filter out an entire array from the payload. However, you can't drop nested objects in an array, or filter properties out of a single object in an array.
121
+
Destination filters can filter properties out of objects nested in an array. For example, you can filter out the `price` property of every object in an array at `properties.products`. You can also filter out an entire array from the payload. However, you can't drop nested objects in an array or filter properties out of a single object in an array.
123
122
124
-
In order to block a specific property from all of the objects within a properties array, set the filter following the format: `<propertyType>.<arrayName>.<arrayElementLabel>`.
123
+
To block a specific property from all of the objects within a properties array, set the filter using the following the format: `<propertyType>.<arrayName>.<arrayElementLabel>`.
125
124
126
125
For example, the `properties.products.newElement` filter blocks all `newElement` property fields from each `products` object of an array within the `properties` object of a Track event.
If you want to block the Identify event trait `products.newElement`, select the option under the **User Traits** list instead. If you want to block a context object field `products.newElement`, select it from the **Context Fields** list.
129
+
To block the Identify event trait `products.newElement`, select the option under the **User Traits** list instead. To block a context object field `products.newElement`, select it from the **Context Fields** list.
130
+
131
+
**How many filters can I create?**
132
+
133
+
Segment supports 10 filters per destination. If you need help consolidating filters or would like to discuss your use case, [contact Segment](https://segment.com/help/contact/).
134
+
135
+
**How many properties can I view in the filter dropdown?**
131
136
132
-
**Q: How many filters can I create?**
137
+
Segment displays the most recent 15,000 properties. To find a property not in the filter dropdown, enter the property manually.
133
138
134
-
You are limited to 10 filters per destination. If you need help
135
-
consolidating filters or would like to discuss your use case, [contact Segment](https://segment.com/help/contact/)!
139
+
**How can I filter out warehouse events?**
136
140
137
-
**Q: When will you support warehouses?**
141
+
To filter out events from warehouses, use Selective Sync.
138
142
139
-
If you want to filter out events from warehouses, the best way to do that is with the existing Selective Sync feature.
143
+
**I don't see a `name` property at the top level of my events to filter on "event name".**
140
144
141
-
**Q: I don't see a "name" property at the top level of my events to filter on "event name".**
145
+
Generally, only Track calls have "name" properties, which correspond to the "Event" field in an event.
142
146
143
-
Generally, only Track calls have "name" properties, which corresponds to the
144
-
"Event" field in an event.
147
+
**How can I find out when new Destination Filters have been added or removed?**
145
148
146
-
**Q: How can I find out when new filters have been added or removed from a destination?**
149
+
The activity feed shows the action, date, and user who performed the action when a Destination Filter is created, modified, enabled, disabled, or deleted. You can also subscribe to notifications for any of these changes in the Activity Feed settings page.
147
150
148
-
The Activity Feed shows the action, date, and user who performed the action when a Destination Filter is created, modified, enabled, disabled, or deleted. You can also subscribe to notifications for any of these changes in the **Activity Feed** settings page.
151
+
The Activity Feed shows the user, date, and action performed when a Destination Filter is created, modified, enabled, disabled, or deleted.
149
152
150
-
**Q: Why am I getting a permissions denied error when trying to save a filter?**
153
+
**Why am I getting a permissions denied error when I try to save a filter?**
151
154
152
-
Anyone with `read`access on the source can view and test filters, but only users with `write`access can edit filters.
155
+
You must have write access to save and edit filters; read permission allows viewing and testing access only.
153
156
154
-
**Q: How can I test that my filter is working?**
157
+
**How can I test my filter?**
155
158
156
-
Use the Destination Filter tester (in the destination filter set up screens) to test if you are filtering out the right events. Filtered events still show up in the schema page, but aren't counted in the Event Deliverability graphs.
159
+
Use the Destination Filter tester during setup to verify that you're filtering out the right events. Filtered events show up on the schema page but aren't counted in event deliverability graphs.
0 commit comments