Trigger types reference（触发器类型参考）

Foundry supports arbitrary nesting of AND and OR triggers, enabling the creation of specific customized triggers.

Time trigger

A time trigger is a trigger that is satisfied at specified instants in time.

:::callout{theme="neutral"} A time trigger is only satisfied at the specified instants. After a specified instant has passed the time trigger is no longer satisfied. :::

Cron expression

A time trigger is defined using a cron expression ↗ and a time zone.

:::callout{theme="success" title="Tip"} The schedule editor provides an easy-to-use interface to define simple time triggers without having to write a cron expression.

More complex time triggers may require writing a custom cron expression. :::

The schedule editor uses the standard Unix cron expression format with five fields:

+--------- Minute
| +------- Hour
| | +----- Day of Month
| | | +--- Month
| | | | +- Day of Week
| | | | |
* * * * *

:::callout{theme="neutral"} Data Health uses the Quartz cron format ↗ (six-parameter), not the Unix cron format ↗ (five-parameter). Quartz implements an additional field for seconds, which is prepended to the standard Unix cron format. :::

The schedule editor allows the following values for each field:

Field	Allowed Values	Allowed Special Characters	Notes
Minute	0-59	* - / ,
Hour	0-23	* - / ,
Day of Month	1-31	* - / , L
Month	1-12 or JAN-DEC	* - / ,
Day of Week	0-6 or SUN-SAT	* - / , L #	7 is also Sunday

The meaning of the special characters is detailed below:

• Asterisk (*): Specifies all values.

Examples:

Minute	Meaning
*	Every minute

• Hyphen (-): Specifies a range of values.

Examples:

Minute	Meaning
10-20	The minutes between 10 and 20, inclusive

• Slash (/): Specifies a stepped range of values.

A stepped range may be defined using either a value or a range:

• When used with a value, the range is from the specified value to the maximum value for that field
• When used with a range, the range is the specified range

Examples:

Minute	Meaning
25/10	Every tenth minute beginning from 25 (25, 35, 45, and 55)
25-45/10	Every tenth minute between 25 and 45, inclusive (25, 35, and 45)

• Comma (,): Specifies a list of values, ranges, and/or stepped ranges.

Examples:

Minute	Meaning
10,20,30	Minutes 10, 20, and 30
10,20-30	Minute 10 and the minutes between 20 and 30, inclusive
10,25-45/10	Minute 10 and every tenth minute between 25 and 45, inclusive

• L (L): Specifies the last value.

The meaning of L is dependent on how it is used:

• When used in the Day of Month field, it specifies the last day of the month
• When used in the Day of Week field by itself, it specifies the last day of the week (Saturday)
• When used in the Day of Week field with a value, it specifies the latest day of the month with the specified day of week

Examples:

Day of Month	Meaning
L	Last day of the month

Day of Week	Meaning
L	Last day of the week (Saturday)
2L	Last Tuesday of the month

• Hash (#): Specifies the nth day of week of the month.

Examples:

Day of Week	Meaning
2#4	Fourth Tuesday of the month

The time trigger will be satisfied when the cron expression matches the current date and time.

:::callout{theme="neutral"} If both the Day of Month and Day of Week fields are not *, the trigger will be satisfied if either matches the current date and time. :::

Examples:

Cron Expression	Meaning
30 9 * * 1	9:30am on Monday
30 17 * 2 1	5:30pm on Monday in February
0 9-17 10 * *	Every hour from 9:00am to 5:00pm on the 10th of the month
0 9-17/2 10 * *	Every two hours from 9:00am to 5:00pm on the 10th of the month
0 9,17 10 * *	9:00am and 5:00pm on the 10th of the month
0/5 9-17 15 3 *	Every five minutes from 9:00am to 5:55pm on the 15th of March
0/5 9,17 15 3 *	Every five minutes from 9:00am to 9:55pm and from 5:00pm to 5:55pm on the 15th of March
0 9 L * *	9:00am on the last of the month
0 9 L 2 *	9:00am on the last of February
0 9 * * L	9:00am on Saturday
0 9 * * 2L	9:00am on the last Tuesday of the month
0 9 * 4 3#1	9:00am on the first Wednesday of April
0 9 20 * 4	9:00am on the 20th of the month and on Thursday

Time changes

All time triggers are evaluated using the wall-clock time in the specified time zone. A time trigger will be satisfied each time a wall-clock time occurs that satisfies the cron expression. Time changes are handled in the following way:

• If the time moves forward, a time trigger satisfied in between the time change will not be satisfied
• If the time moves backward, a time trigger satisfied in between the time change will be satisfied twice

Examples:

• If the time moves forward from 1:00am to 2:00am, a time trigger satisfied at 1:30am will not be satisfied because 1:30am never occurred
• If the time moves backward from 2:00am to 1:00am, a time trigger satisfied at 1:30am will be satisfied twice because 1:30am occurred twice

Event trigger

An event trigger is a trigger that is satisfied once a specified event has occurred.

:::callout{theme="neutral"} An event trigger remains satisfied after the event has occurred until the entire trigger is satisfied and the schedule is run. :::

Event types

The schedule editor currently supports the following event types:

• New logic: Occurs when the logic to compute a dataset is updated.
• Data updated: Occurs when a transaction is committed that updates a dataset.
• Job succeeded: Occurs when a job on a dataset is completed, regardless of whether a transaction was committed.
• Schedule ran successfully: Occurs when a scheduled build is completed successfully.

Compound trigger

A compound trigger is created by combining multiple component triggers using AND triggers and OR triggers.

• An AND trigger creates a trigger that is the conjunction of its component triggers.
• An OR trigger creates a trigger that is the disjunction of its component triggers.

Examples:

In the following examples, T1, T2 are time triggers and E1, E2 are event triggers.

Trigger	Meaning
AND(T1, E1)	Satisfied at T1 if E1 has occurred
OR(T1, E1)	Satisfied at T1 or when E1 occurs
AND(T1, T2) [1]	Satisfied at times that satisfy both T1 and T2
OR(T1, T2)	Satisfied at either T1 or T2
AND(E1, E2)	Satisfied when both E1 and E2 have occurred
OR(E1, E2)	Satisfied when either E1 and E2 have occurred
AND(T1, OR(E1, E2))	Satisfied at T1 if either E1 or E2 has occurred
OR(T1, AND(E1, E2))	Satisfied at T1 or when both E1 and E2 have occurred

[1] Creating an AND trigger with multiple time triggers will only be satisfied when all time triggers coincide. For example, an AND trigger with a daily trigger and an hourly trigger will only be satisfied once per day. Instead, a more specific single time trigger should be used. In the previous example, the AND trigger should be replaced with just the daily trigger.

---

中文翻译

触发器类型参考

Foundry 支持 AND 和 OR 触发器的任意嵌套，从而可以创建特定的自定义触发器。

时间触发器(Time trigger)

时间触发器是在指定时间点满足条件的触发器。

:::callout{theme="neutral"} 时间触发器仅在指定的时间点满足条件。一旦指定的时间点过去，时间触发器将不再满足条件。 :::

Cron 表达式

时间触发器使用 cron 表达式 ↗ 和时区来定义。

:::callout{theme="success" title="提示"} 调度编辑器提供了易于使用的界面来定义简单的时间触发器，无需编写 cron 表达式。

更复杂的时间触发器可能需要编写自定义 cron 表达式。 :::

调度编辑器使用包含五个字段的标准 Unix cron 表达式格式：

+--------- 分钟
| +------- 小时
| | +----- 月份中的日期
| | | +--- 月份
| | | | +- 星期中的日期
| | | | |
* * * * *

:::callout{theme="neutral"} Data Health 使用 Quartz cron 格式 ↗（六参数），而非 Unix cron 格式 ↗（五参数）。Quartz 实现了额外的秒数字段，该字段被添加到标准 Unix cron 格式之前。 :::

调度编辑器允许每个字段使用以下值：

字段	允许的值	允许的特殊字符	说明
分钟	0-59	* - / ,
小时	0-23	* - / ,
月份中的日期	1-31	* - / , L
月份	1-12 或 JAN-DEC	* - / ,
星期中的日期	0-6 或 SUN-SAT	* - / , L #	7 也表示星期日

特殊字符的含义如下：

• 星号 (*): 指定所有值。

示例：

分钟	含义
*	每分钟

• 连字符 (-): 指定值的范围。

示例：

分钟	含义
10-20	10 到 20 分钟（含）

• 斜杠 (/): 指定值的步进范围。

步进范围可以使用值或范围来定义：

• 与值一起使用时，范围从指定值到该字段的最大值
• 与范围一起使用时，范围即为指定的范围

示例：

分钟	含义
25/10	从 25 分钟开始，每 10 分钟一次（25、35、45 和 55）
25-45/10	25 到 45 分钟之间（含），每 10 分钟一次（25、35 和 45）

• 逗号 (,): 指定值、范围和/或步进范围的列表。

示例：

分钟	含义
10,20,30	第 10、20 和 30 分钟
10,20-30	第 10 分钟以及 20 到 30 分钟（含）
10,25-45/10	第 10 分钟以及 25 到 45 分钟之间（含），每 10 分钟一次

• L (L): 指定最后一个值。

L 的含义取决于其使用方式：

• 在"月份中的日期"字段中使用时，指定月份的最后一天
• 在"星期中的日期"字段中单独使用时，指定一周的最后一天（星期六）
• 在"星期中的日期"字段中与值一起使用时，指定该月中指定星期几的最后一天

示例：

月份中的日期	含义
L	月份的最后一天

星期中的日期	含义
L	一周的最后一天（星期六）
2L	月份中最后一个星期二

• 井号 (#): 指定月份中的第 n 个星期几。

示例：

星期中的日期	含义
2#4	月份中的第四个星期二

当 cron 表达式与当前日期和时间匹配时，时间触发器将满足条件。

:::callout{theme="neutral"} 如果"月份中的日期"和"星期中的日期"字段都不是 *，则只要其中一个与当前日期和时间匹配，触发器就会满足条件。 :::

示例：

Cron 表达式	含义
30 9 * * 1	星期一上午 9:30
30 17 * 2 1	二月份星期一下午 5:30
0 9-17 10 * *	每月 10 日上午 9:00 至下午 5:00 每小时一次
0 9-17/2 10 * *	每月 10 日上午 9:00 至下午 5:00 每两小时一次
0 9,17 10 * *	每月 10 日上午 9:00 和下午 5:00
0/5 9-17 15 3 *	3 月 15 日上午 9:00 至下午 5:55 每五分钟一次
0/5 9,17 15 3 *	3 月 15 日上午 9:00 至 9:55 和下午 5:00 至 5:55 每五分钟一次
0 9 L * *	每月最后一天上午 9:00
0 9 L 2 *	二月份最后一天上午 9:00
0 9 * * L	星期六上午 9:00
0 9 * * 2L	月份中最后一个星期二上午 9:00
0 9 * 4 3#1	四月份第一个星期三上午 9:00
0 9 20 * 4	每月 20 日和星期四上午 9:00

时间变更

所有时间触发器均使用指定时区的挂钟时间进行评估。每当出现满足 cron 表达式的挂钟时间时，时间触发器就会满足条件。时间变更的处理方式如下：

• 如果时间向前拨快，则在时间变更期间满足条件的时间触发器将不再满足条件
• 如果时间向后拨慢，则在时间变更期间满足条件的时间触发器将满足两次条件

示例：

• 如果时间从凌晨 1:00 拨快到凌晨 2:00，则在凌晨 1:30 满足条件的时间触发器将不再满足条件，因为凌晨 1:30 从未出现
• 如果时间从凌晨 2:00 拨慢到凌晨 1:00，则在凌晨 1:30 满足条件的时间触发器将满足两次条件，因为凌晨 1:30 出现了两次

事件触发器(Event trigger)

事件触发器是在指定事件发生后满足条件的触发器。

:::callout{theme="neutral"} 事件触发器在事件发生后保持满足条件，直到整个触发器满足条件且调度运行完毕。 :::

事件类型(Event types)

调度编辑器目前支持以下事件类型：

• 新逻辑(New logic): 当计算数据集的逻辑更新时发生。
• 数据更新(Data updated): 当提交更新数据集的事务时发生。
• 作业成功(Job succeeded): 当数据集上的作业完成时发生，无论是否提交了事务。
• 调度成功运行(Schedule ran successfully): 当计划构建成功完成时发生。

复合触发器(Compound trigger)

复合触发器通过使用 AND 触发器和 OR 触发器组合多个组件触发器来创建。

• AND 触发器创建其组件触发器的合取（与）条件。
• OR 触发器创建其组件触发器的析取（或）条件。

示例：

在以下示例中，T1、T2 是时间触发器，E1、E2 是事件触发器。

触发器	含义
AND(T1, E1)	在 T1 时刻满足条件，前提是 E1 已发生
OR(T1, E1)	在 T1 时刻或 E1 发生时满足条件
AND(T1, T2) [1]	在同时满足 T1 和 T2 的时刻满足条件
OR(T1, T2)	在 T1 或 T2 时刻满足条件
AND(E1, E2)	当 E1 和 E2 都发生时满足条件
OR(E1, E2)	当 E1 或 E2 发生时满足条件
AND(T1, OR(E1, E2))	在 T1 时刻满足条件，前提是 E1 或 E2 已发生
OR(T1, AND(E1, E2))	在 T1 时刻或 E1 和 E2 都发生时满足条件

[1] 使用多个时间触发器创建 AND 触发器仅在所有时间触发器同时满足时才会满足条件。例如，包含每日触发器和每小时触发器的 AND 触发器每天只会满足一次条件。相反，应使用更具体的单一时间触发器。在前面的示例中，应将 AND 触发器替换为仅每日触发器。