elementary.freshness_anomalies

是 Elementary Data 提供的一个 dbt 测试，用于监控表的“新鲜度”异常，即数据更新的时间间隔是否出现异常延迟。下面是该测试的全部配置参数详细说明： --- ### 必填参数 - timestamp_column 指定用于计算新鲜度的时间戳字段。 示例：

yaml   timestamp_column: updated_at

--- ### 可选参数 - where_expression 只对满足条件的行进行新鲜度检测。 示例：

yaml   where_expression: "status = 'active'"

- anomaly_sensitivity 控制异常检测的灵敏度。数值越高，检测越敏感。 示例：

yaml   anomaly_sensitivity: 3

- detection_period 检测周期，指定最近多少个时间段（如天、小时等）作为异常检测的窗口。 示例：

yaml   detection_period:     period: day     count: 2

- training_period 训练周期，指定用于建模的历史时间段数量。 示例：

yaml   training_period:     period: day     count: 14

- time_bucket 数据分桶的时间粒度，默认按天分桶。 示例：

yaml   time_bucket:     period: day     count: 1

- detection_delay 检测延迟，允许在检测异常前有一定的延迟窗口。 示例：

yaml   detection_delay:     period: hour     count: 1

- ignore_small_changes 忽略小幅度变化的阈值设置。 示例：

yaml   ignore_small_changes:     spike_failure_percent_threshold: 20     drop_failure_percent_threshold: 10

- anomaly_exclude_metrics 指定 SQL 表达式，排除某些指标不参与异常检测。 示例：

yaml   anomaly_exclude_metrics:     - "metric_name = 'some_metric'"

--- ### 默认行为 - 默认只检测“延迟”异常（spike），即数据更新变慢或停止时报警。 - 默认检测周期为最近2天，训练周期为14天，分桶为每天。 --- ### 配置示例

yaml models:   - name: my_table     tests:       - elementary.freshness_anomalies:           timestamp_column: updated_at           where_expression: "status = 'active'"           anomaly_sensitivity: 2           detection_period:             period: day             count: 2           training_period:             period: day             count: 14           time_bucket:             period: day             count: 1           ignore_small_changes:             spike_failure_percent_threshold: 20             drop_failure_percent_threshold: 10

--- 详细参数说明和用法可参考官方文档：[freshness_anomalies](https://docs.elementary-data.com/data-tests/anomaly-detection-tests/freshness-anomalies)【支持中文】。如需进一步了解每个参数的具体作用和配置建议，也可查阅相关文档页面中的链接和说明内容。 [详细配置参考](https://docs.elementary-data.com/data-tests/anomaly-detection-tests/freshness-anomalies)

好的，针对你的四个问题，以下是基于官方文档和社区讨论的详细解答： --- ### 1. anomaly_sensitivity 灵敏度设置的范围是多少？

anomaly_sensitivity

是一个数值型参数，默认值为 3。它表示模型期望范围的标准差倍数。 - **数值越小**，检测范围越窄，更容易被判定为异常（更敏感）。 - **数值越大**，检测范围越宽，只有极端情况才会被判定为异常（更不敏感）。 官方文档没有明确限制最大/最小值，但通常建议在 1~5 之间调整，具体取决于你的业务需求。 配置示例：

yaml anomaly_sensitivity: 2

[详细说明见文档](https://docs.elementary-data.com/data-tests/anomaly-detection-configuration/anomaly-sensitivity) --- ### 2. anomaly_direction 参数怎么配置，什么意思？

anomaly_direction

用于指定只检测“上升异常（spike）”、“下降异常（drop）”还是“两者都检测（both）”。 - **spike**：只检测高于期望范围的异常（如延迟、变慢等）。 - **drop**：只检测低于期望范围的异常。 - **both**：两种异常都检测。 **注意**：对于 `freshness_anomalies`，默认只检测 spike（即只关注延迟），而且该参数通常无需手动配置，配置了也不会生效，因为新鲜度只关心延迟，不关心提前更新。[见社区说明](https://slack.com/archives/C02CTC89LAX/p1685592068134349) 配置示例（一般不需要在 freshness_anomalies 里加）：

yaml anomaly_direction: spike

[参数说明](https://docs.elementary-data.com/data-tests/anomaly-detection-configuration/anomaly-direction) --- ### 3. seasonality 配置什么意思？

seasonality

用于指定模型在检测异常时是否考虑周期性（如一周内不同天的规律）。 - **day_of_week**：模型只会用同一星期几的历史数据来做对比，比如周一只和之前的周一比，适合有明显工作日/周末规律的数据。 配置示例：

yaml seasonality: day_of_week

[参数说明](https://docs.elementary-data.com/data-tests/anomaly-detection-configuration/seasonality) --- ### 4. 重新解释 elementary.freshness_anomalies 的配置作用及影响 #### 主要配置及其作用 - **timestamp_column**：指定用于判断数据更新时间的字段，必须配置。 - **where_expression**：只对满足条件的数据行做新鲜度检测。 - **anomaly_sensitivity**：控制异常检测的灵敏度，数值越小越敏感，越容易报警。 - **detection_period**：指定最近多少个时间段作为异常检测窗口，影响检测的“最近性”。 - **training_period**：指定用于建模的历史时间段数量，影响模型对“正常”行为的理解。 - **time_bucket**：指定分桶粒度，影响新鲜度的统计方式（如按天、小时等）。 - **seasonality**：指定是否考虑周期性规律，适合有明显周期性的数据。 - **anomaly_direction**：理论上可选，但 freshness_anomalies 默认只检测 spike（延迟），一般无需配置。 #### 配置对检测结果的影响 - anomaly_sensitivity 越低，越容易报警，适合对延迟极其敏感的场景。 - seasonality 能避免因周期性波动导致的误报。 - detection_period/training_period 影响模型对“正常”与“异常”的判断窗口，窗口太短可能导致误判，太长则可能对新变化不敏感。 - anomaly_direction 在 freshness_anomalies 里默认只检测 spike（延迟），提前更新不会被判为异常。 #### 配置示例

yaml models:   - name: my_table     tests:       - elementary.freshness_anomalies:           timestamp_column: updated_at           anomaly_sensitivity: 2           detection_period:             period: day             count: 2           training_period:             period: day             count: 14           time_bucket:             period: day             count: 1           seasonality: day_of_week

[官方详细配置说明](https://docs.elementary-data.com/data-tests/anomaly-detection-tests/freshness-anomalies) --- 如需进一步了解每个参数的具体作用和配置建议，建议结合实际业务场景和数据特点进行调整。如有特殊需求，也可以参考官方文档的高级配置说明。

detection_period

的默认值是 **2天**。如果你不进行配置，Elementary 会默认检测最近2天的数据是否存在异常。这意味着只有最近2天内的数据点会被纳入异常检测的窗口中，超出这个范围的数据不会被检测为异常。 相关说明可参考官方文档：“If detection_period are set to 2 days, only data points in the last 2 days will be included in the detection period and could be flagged anomalous.” 并且明确标注了默认值为 2 天（*Default: 2 days*）[detection_period 参数说明](https://docs.elementary-data.com/data-tests/anomaly-detection-configuration/detection-period)。

training_period

和

detection_period

是 Elementary 异常检测中两个核心但不同的参数： --- ### training_period - **含义**：`training_period` 用于指定模型在检测异常时参考的历史数据窗口，也就是“训练集”。Elementary 会用这段时间内的数据来学习和计算“正常”行为的统计特征（如均值、标准差等），据此判断后续数据是否异常。 - **默认值**：14天。 - **作用**：决定了模型对“正常”行为的理解范围。窗口越大，模型越不容易对短期波动敏感；窗口越小，模型对新变化更敏感，但可能更容易误报。 - **举例**：如果

training_period

设置为 14 天，模型会用过去 14 天的数据来计算期望范围。 --- ### detection_period - **含义**：`detection_period` 用于指定“检测集”，即最近多少时间的数据需要被检测是否异常。只有在这个窗口内的数据点会被判定为异常或正常。 - **默认值**：2天。 - **作用**：决定了实际要检测的时间范围。只有在 detection_period 内的数据点会被 Elementary 检查并可能被标记为异常。 - **举例**：如果

detection_period

设置为 2 天，只有最近 2 天的数据会被检测。 --- ### 区别总结 - `training_period`：用来“学习”什么是正常（历史参考窗口）。 - `detection_period`：用来“检测”哪些数据是否异常（实际检测窗口）。 > “The test then compares a certain metric (e.g. row count) of the buckets that are within the detection period to the row count of all the previous time buckets within the training_period period.” [官方说明](https://docs.elementary-data.com/data-tests/how-anomaly-detection-works) --- 简而言之： -

training_period

决定“正常”标准， -

detection_period

决定“要检测哪些数据”。

detection_delay

是 Elementary 异常检测中的一个参数，用于**延后检测窗口**，即在检测异常时跳过最新的一段时间数据。这在数据有延迟加载、调度不准时等场景下非常有用，可以避免因为数据还没到齐而产生误报。 官方定义： > detection_delay：The duration for retracting the detection period. That’s useful in cases which the latest data should be excluded from the test. For example, this can happen because of scheduling issues- if the test is running before the table is populated for some reason. The detection delay is the period of time to ignore, after the detection period. - **默认值**：0（即不延迟，检测窗口就是到“现在”） - **支持的单位**：hour, day, week, month - **配置示例**：

yaml   detection_delay:     period: day     count: 1

这表示检测窗口会往前推一天，最新一天的数据不会被检测。 - **作用**：只影响检测窗口的起止时间，不影响

training_period

或

detection_period

的长度。 - **适用场景**：数据有延迟、调度不准时、数据还没完全落库时，避免误报。 详细说明可参考官方文档：[detection_delay 参数说明](https://docs.elementary-data.com/data-tests/anomaly-detection-configuration/detection-delay)

当然可以，以下是

detection_delay

的实际应用举例： 假设你的数据表每天凌晨 2 点才会完整加载前一天的数据，但你的 dbt 测试任务在每天凌晨 1 点就已经运行了。此时，如果不做特殊处理，Elementary 的异常检测会把“今天”还没加载完的数据也纳入检测，容易导致误报。 这时你可以这样配置 `detection_delay`：

yaml models:   - name: my_table     tests:       - elementary.volume_anomalies:           timestamp_column: created_at           detection_delay:             period: day             count: 1

**含义**： -

detection_delay

设置为 1 天，表示检测时会自动跳过最新一天的数据，只检测之前的数据。 - 这样即使你的测试在数据还没加载完时运行，也不会因为“今天”数据不全而误报异常。 官方文档也明确说明了这个用法：“That’s useful in cases which the latest data should be excluded from the test. For example, this can happen because of scheduling issues- if the test is running before the table is populated for some reason.” [详细说明见官方文档](https://docs.elementary-data.com/data-tests/anomaly-detection-configuration/detection-delay)