Skip to content

Commit c390703

Browse files
ChigalaChigala
committed
updated the eventfilter doc based on the requested changes
1 parent 26f5bab commit c390703

File tree

1 file changed

+96
-152
lines changed

1 file changed

+96
-152
lines changed

‎docs/documentation/guides/event-filter.mdx‎

Lines changed: 96 additions & 152 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,55 @@
11
---
22
title: "Event Filters"
3-
description: "A guide to using event filters to create more precise and tailored job triggers."
3+
description: "They are declarative pattern-matching rules, modeled after [AWS EventBridge patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html)."
44
---
55

6-
## What are Event Filters?
6+
Given the following custom event payload:
77

8-
Event filters provide a powerful way to define specific conditions that determine when a job should be triggered based on incoming events. Filters allow you to narrow down event processing to only those events that match certain criteria, ensuring that your jobs are executed in a targeted manner.
8+
```json
9+
{
10+
"uid": "jexAgaeJFJsrGfans1pxqm",
11+
"type": "15 Min Meeting",
12+
"price": 0,
13+
"title": "15 Min Meeting between Eric Allam and John Doe",
14+
"length": 15,
15+
"status": "ACCEPTED",
16+
"endTime": "2023-01-25T16:00:00Z",
17+
"bookingId": 198052,
18+
"organizer": {
19+
"id": 32794,
20+
"name": "Eric Allam",
21+
"email": "eric@trigger.dev",
22+
"language": { "locale": "en" },
23+
"timeZone": "Europe/London"
24+
}
25+
}
26+
```
927

10-
we will cover the various types of event filters and how they can be used to create more precise triggers.
28+
The following event filter would match the event:
1129

12-
### Event Filter Types
30+
```json
31+
{
32+
"type": ["15 Min Meeting"],
33+
"status": ["ACCEPTED", "REJECTED"],
34+
"organizer": {
35+
"name": ["Eric Allam"]
36+
}
37+
}
38+
```
1339

14-
#### 1. String Filters
40+
For an event pattern to match an event, the event must contain all the field names listed in the event pattern. The field names must also appear in the event with the same nesting structure.
41+
42+
The value of each field name in the event pattern must be an array of strings, numbers, or booleans. The event pattern matches the event if the value of the field name in the event is equal to any of the values in the array.
43+
44+
Effectively, each array is an OR condition, and the entire event pattern is an AND condition.
45+
46+
So the above event filter will match because `status == "ACCEPTED"`, and it would also match if `status == "REJECTED"`.
47+
48+
### String Filters
1549

1650
String filters are used to match string values within the event payload. You can filter events based on exact string matches, case-insensitive matches, starts-with, ends-with, and more.
1751

18-
**Examples of string filters:**
52+
**Examples:**
1953

2054
- `name: ["John"]`: Triggers the job if the name field in the event payload is exactly "John".
2155
- `name: [{ $startsWith: "Jo" }]`: Triggers the job if the name field starts with "Jo".
@@ -64,11 +98,11 @@ client.defineJob({
6498
});
6599
```
66100

67-
### 2. Boolean Filters
101+
### Boolean Filters
68102

69103
Boolean filters are used to filter events based on boolean values within the event payload.
70104

71-
**_Examples of boolean filters:_**
105+
**Examples:**
72106

73107
- `paidPlan: [true]`: Triggers the job if the `PaidPlan` field in the event payload is `true`.
74108
- `isAdmin: [false]`: Triggers the job if the `isAdmin` field in the event payload is `false`.
@@ -116,17 +150,19 @@ client.defineJob({
116150
});
117151
```
118152

119-
### 3. Number Filters
153+
### Number Filters
120154

121-
Number filters are used to filter events based on numeric values within the event payload.
155+
Number filters are used to filter events based on numeric values within the event payload. It can also be used to perform numeric comparisons on values within the event payload.
122156

123-
**_Examples of number filters:_**
157+
**Examples:**
124158

125159
- `age [18]`: Triggers the job if the `age` field in the event payload is equal to `18`.
126160
- `score: [{ $gt: 90 }]` : Triggers the job if the score field is greater than `90`.
127161
- `score: [{ $gte: 90 }]` : Triggers the job if the score field is greater than or equal to `90`.
128162
- `score: [{ $lt: 90 }]` : Triggers the job if the score field is less than `90`.
129163
- `score: [{ $lte: 90 }]` : Triggers the job if the score field is less than or equal to `90`.
164+
- `age: [{ $gt: 20 }, { $lt: 40 }]`: Triggers the job if the `age` field is greater than 20 and less than 40.
165+
- `score: [{ $between: [90, 110] }]`: Triggers the job if the `score` field is between 90 and 110.
130166

131167
#### Examples of number filters used in a Trigger.
132168

@@ -168,9 +204,47 @@ client.defineJob({
168204
});
169205
```
170206

171-
### 4. Content Filters
207+
```ts
208+
client.defineJob({
209+
id: "send-discount-code",
210+
name: "Send Discount Code",
211+
version: "1.0.0",
212+
trigger: eventTrigger({
213+
name: "user.purchase",
214+
schema: z.object({
215+
userId: z.string(),
216+
age: z.number(),
217+
}),
218+
filter: {
219+
age: [{ $gt: 18 }, { $lt: 30 }], // Only trigger for users aged between 18 and 30
220+
},
221+
}),
222+
run: async (payload, io, ctx) => {},
223+
});
224+
```
225+
226+
```ts
227+
client.defineJob({
228+
id: "update-user-level",
229+
name: "Update User Level",
230+
version: "1.0.0",
231+
trigger: eventTrigger({
232+
name: "user.scoreUpdated",
233+
schema: z.object({
234+
userId: z.string(),
235+
score: z.number(),
236+
}),
237+
filter: {
238+
score: [{ $between: [50, 100] }], // Only trigger for scores between 50 and 100 (inclusive)
239+
},
240+
}),
241+
run: async (payload, io, ctx) => {},
242+
});
243+
```
172244

173-
Content filters are used to filter events based on the content of arrays within the event payload.
245+
### Array Filters
246+
247+
Array filters are used to filter events based on the content of arrays within the event payload.
174248

175249
**Examples:**
176250

@@ -199,7 +273,7 @@ client.defineJob({
199273
});
200274
```
201275

202-
### 5. Existence Filters
276+
### Existence Filters
203277

204278
Existence filters are used to filter events based on the presence or absence of certain keys within the event payload.
205279

@@ -249,58 +323,9 @@ client.defineJob({
249323
});
250324
```
251325

252-
### 6. Comparison Filters
253-
254-
Comparison filters are used to perform numeric comparisons on values within the event payload.
255-
256-
**Examples:**
257-
258-
- `age: [{ $gt: 20 }, { $lt: 40 }]`: Triggers the job if the `age` field is greater than 20 and less than 40.
259-
- `score: [{ $between: [90, 110] }]`: Triggers the job if the `score` field is between 90 and 110.
260-
261-
#### Examples of comparison filters being used in a Trigger.
262-
263-
```ts
264-
client.defineJob({
265-
id: "send-discount-code",
266-
name: "Send Discount Code",
267-
version: "1.0.0",
268-
trigger: eventTrigger({
269-
name: "user.purchase",
270-
schema: z.object({
271-
userId: z.string(),
272-
age: z.number(),
273-
}),
274-
filter: {
275-
age: [{ $gt: 18 }, { $lt: 30 }], // Only trigger for users aged between 18 and 30
276-
},
277-
}),
278-
run: async (payload, io, ctx) => {},
279-
});
280-
```
281-
282-
```ts
283-
client.defineJob({
284-
id: "update-user-level",
285-
name: "Update User Level",
286-
version: "1.0.0",
287-
trigger: eventTrigger({
288-
name: "user.scoreUpdated",
289-
schema: z.object({
290-
userId: z.string(),
291-
score: z.number(),
292-
}),
293-
filter: {
294-
score: [{ $between: [50, 100] }], // Only trigger for scores between 50 and 100 (inclusive)
295-
},
296-
}),
297-
run: async (payload, io, ctx) => {},
298-
});
299-
```
300-
301-
### 7. Combining Filters
326+
### Combining Filters
302327

303-
Filters can be combined to create more complex conditions for triggering jobs. For example:
328+
Filters can be combined to create more complex conditions for triggering jobs.
304329

305330
**Examples:**
306331

@@ -355,55 +380,9 @@ client.defineJob({
355380
});
356381
```
357382

358-
### Other examples
359-
360-
Given the following custom event payload:
361-
362-
```json
363-
{
364-
"uid": "jexAgaeJFJsrGfans1pxqm",
365-
"type": "15 Min Meeting",
366-
"price": 0,
367-
"title": "15 Min Meeting between Eric Allam and John Doe",
368-
"length": 15,
369-
"status": "ACCEPTED",
370-
"endTime": "2023-01-25T16:00:00Z",
371-
"bookingId": 198052,
372-
"organizer": {
373-
"id": 32794,
374-
"name": "Eric Allam",
375-
"email": "eric@trigger.dev",
376-
"language": { "locale": "en" },
377-
"timeZone": "Europe/London"
378-
}
379-
}
380-
```
381-
382-
The following event filter would match the event:
383+
### Stripe Trigger with Event Filter
383384

384-
```json
385-
{
386-
"type": ["15 Min Meeting"],
387-
"status": ["ACCEPTED", "REJECTED"],
388-
"organizer": {
389-
"name": ["Eric Allam"]
390-
}
391-
}
392-
```
393-
394-
For an event pattern to match an event, the event must contain all the field names listed in the event pattern. The field names must also appear in the event with the same nesting structure.
395-
396-
The value of each field name in the event pattern must be an array of strings, numbers, or booleans. The event pattern matches the event if the value of the field name in the event is equal to any of the values in the array.
397-
398-
Effectively, each array is an OR condition, and the entire event pattern is an AND condition.
399-
400-
So the above event filter will match because status == "ACCEPTED", and it would also match if status == "REJECTED".
401-
402-
## Other types of triggers that can also support event filters.
403-
404-
#### 1. Stripe Trigger with Event Filter
405-
406-
**Here is an example of a Stripe Trigger with an Event Filter:**
385+
Here is an example of a Stripe Trigger with an Event Filter:
407386

408387
```ts
409388
client.defineJob({
@@ -425,9 +404,9 @@ The job is triggered by the `onCustomerSubscriptionCreated` event from Stripe. I
425404

426405
- Currency: Only subscriptions with the currency "USD" will trigger this job.
427406

428-
#### 2. Supabase trigger with Event Filter
407+
### Supabase trigger with Event Filter
429408

430-
**Here is an example of a Supabase Trigger with an Event Filter:**
409+
Here is an example of a Supabase Trigger with an Event Filter:
431410

432411
```ts
433412
client.defineJob({
@@ -457,42 +436,7 @@ client.defineJob({
457436
openai,
458437
supabase,
459438
},
460-
run: async (payload, io, ctx) => {
461-
if (!payload.record.name) {
462-
return;
463-
}
464-
465-
const {
466-
data: { publicUrl },
467-
} = supabase.native.storage.from("example_bucket").getPublicUrl(payload.record.name);
468-
469-
// Use the native supabase client to get a signed url
470-
const { error, data } = await io.supabase.client.storage
471-
.from("example_bucket")
472-
.createSignedUrl(payload.record.name, 60);
473-
474-
if (error) {
475-
throw error;
476-
}
477-
478-
const imageVariation = await io.openai.createImageVariation("variation-image", {
479-
image: data.signedUrl,
480-
n: 2,
481-
response_format: "url",
482-
size: "512x512",
483-
});
484-
485-
const imageEdit = await io.openai.createImageEdit("edit-image", {
486-
image: publicUrl,
487-
prompt:
488-
"Fill in the background to make it seem like the cat is on the moon with a beautiful view of the earth.",
489-
n: 2,
490-
response_format: "url",
491-
size: "512x512",
492-
});
493-
494-
// return imageEdit;
495-
},
439+
run: async (payload, io, ctx) => {},
496440
});
497441
```
498442

0 commit comments

Comments
 (0)