Configuring Relative Threshold

A Relative threshold evaluates whether a metric changed in an acceptable way compared to its recent execution history. Rather than comparing a result against a fixed number, a Relative threshold asks: did the value grow, shrink, or change by the right amount since the last run?

This is distinct from an Absolute threshold, which checks whether a metric falls within a static range, and from Anomaly Detection, which uses statistical models to identify unexpected patterns. Use a Relative threshold when your data naturally changes run-over-run and you care about the direction or magnitude of that change.

Use a Relative threshold when...	Use an Absolute threshold when...
The metric is expected to change between runs and you care about the direction or size of that change.	You know the acceptable range upfront and it does not drift over time.
You cannot predict an exact range but can express a minimum or maximum delta.	You have hard contractual or regulatory limits on a value.
The metric naturally trends, such as row counts that grow with each ingestion cycle.	The metric is stable and should remain within a known band.

Applicable Rule Types

The full Relative threshold configuration — including the Operator field and Use Absolute Value toggle — is available for the following aggregate rule types within a Data Quality policy:

Row Check — checks the total number of rows in a dataset.
Metric Check — validates aggregate metrics such as SUM, AVG, MIN, or MAX.
SQL Metric Check — validates a numeric value returned by a custom SQL expression.

*Note For row-based rules such as Null Values, Pattern Match, or Uniqueness Check, the Relative tab uses a simpler form with a direction selector and percentage threshold only. The Operator dropdown and Use Absolute Value toggle are not available for those rule types.*

Threshold Controls

When you select the Relative tab in the rule configuration panel, five controls appear in a single inline row followed by the Look Back Window settings.

1. Direction

The Direction field defines which kind of change the rule evaluates. Three options are available:

Direction	What it measures
Increased By	How much the value grew since the baseline.
Decreased By	How much the value shrank since the baseline.
Changes By	The absolute magnitude of change in either direction, regardless of whether the value went up or down.

Direction determines the verb used in the plain-English description below the form: grows (Increased By), drops (Decreased By), or changes (Changes By).

2. Operator

The Operator field defines how the measured change is compared against the threshold. This is the key enhancement introduced in ADOC v26.6.0. Previously, only the implicit ≤ (at most) operator was available, making all relative thresholds tolerance-boundary checks. Six operators are now available:

Operator	Plain English	Typical Use
`≤ (at most)`	The change is at or below the threshold.	"Do not grow by more than X"
`< (less than)`	The change is strictly below the threshold.	"Must stay below X, not including X"
`≥ (at least)`	The change is at or above the threshold.	"Must grow by at least X"
`> (greater than)`	The change is strictly above the threshold.	"Must grow by more than X"
`= (equals)`	The change is exactly the threshold value.	"Should always change by exactly N"
`≠ (not equals)`	The change is anything except the threshold.	"Should never change by exactly N"

Tip Read the Direction and Operator together as a sentence: "Increased By ≥ 1 row" means the rule passes only when the row count grows by at least 1. The visual band below the form updates in real time to confirm what the rule will evaluate.

3. Use Absolute Value

The Use Absolute Value toggle controls whether the threshold is expressed as a percentage of the baseline or as a fixed numeric value.

Toggle State	Threshold Means	Example
Off (default)	A percentage of the recent baseline value.	Success Threshold = 10 → 10% of the baseline
On	An absolute count or scalar value in the same units as the metric.	Success Threshold = 1 → 1 row (for Row Check)

When the toggle is on, the label on the right side of the toggle updates to Absolute. The unit suffix on the Success Threshold input also updates accordingly.

Important Absolute values are only supported for rule types that produce scalar measurements (Row Check, Metric Check, SQL Metric Check). Selecting Use Absolute Value on a ratio-style rule such as Null Values is not permitted and will produce a validation error at save time. The Success Threshold must be a whole number when the unit is set to Absolute.

4. Success Threshold

The Success Threshold is the numeric value the measured change is compared against using the selected Operator. The unit is determined by the Use Absolute Value toggle: percentage when the toggle is off, absolute count when the toggle is on.

The Success Threshold is required. The policy cannot be saved without it. Decimal values are accepted for percentage thresholds (for example, 0.5 for half a percent). Absolute thresholds require a whole number.

5. Warning Threshold (Optional)

The Warning Threshold adds a graded intermediate band between Pass and Fail. When configured, a rule produces three possible outcomes per execution instead of two.

Outcome	Condition
Pass	The change is on the safe side of the Success Threshold.
Warn	The change falls between the Success Threshold and the Warning Threshold.
Fail	The change is on the unsafe side of the Warning Threshold.

The correct ordering of the Warning Threshold relative to the Success Threshold depends on the Operator selected:

Operator family	Warning must be...	Example
`≤ or < (tolerance)`	Greater than Success Threshold (Warning is the looser bound).	Pass at most 10%, warn between 10–20%, fail above 20%.
`≥ or > (directional minimum)`	Less than Success Threshold (Warning is the softer minimum).	Pass at least 5 rows, warn between 1–5 rows, fail below 1.
`= or ≠`	Not applicable. Warning Threshold is hidden for these operators.	A warning band around an exact-equality or inequality target has no defined meaning.

If you enter a value that violates the required ordering, the form shows an inline validation error before the policy can be saved.

Look Back Window

The Look Back Window defines the historical period used to compute the baseline value the current result is compared against. Two fields control the window:

Look Back Window: A numeric value.
Look Back Window Type: The unit for the window — Hours, Days, or Runs.

The baseline is the average of the metric across the most recent successful executions that fall within the configured window. The default is 24 hours. On the first execution of a policy, no historical baseline exists, so the rule passes by default. From the second execution onward, comparison is live.

Reading the Visual Band

The colored band below the threshold form is the plain-English description of your rule. As you change any of the five controls, the band updates in real time. Treat it as confirmation that the form is configured correctly.

The band has two parts:

A colored bar: Segments are colored green (Pass), yellow (Warn), and red (Fail) to show the result for each range of the measured change.
A bullet list: One bullet per tier, each phrased as “[Tier] when the [subject] [verb] [boundary].”

The subject, verb, and boundary are determined by your control selections:

The subject comes from the rule type: "total number of rows" (Row Check), "value of the selected aggregate metric" (Metric Check), or "value returned by the SQL metric expression" (SQL Metric Check).
The verb comes from Direction: grows, drops, or changes.
The boundary comes from Operator and Threshold: for example, "by at least 1 row" or "by at most 10%".

Tip Read the band bullets aloud before saving. If they describe the rule you intend to create, the form is correct. If they do not, adjust one of the five controls and check the band again.

Common Scenarios

The following examples show how to configure the five controls for the most common relative threshold use cases.

Scenario A — Pass Only If at Least One New Row Arrives

Use this configuration for cumulative ingestion pipelines where each run must add at least one new record.

Control	Value
Direction	Increased By
Operator	≥ (at least)
Use Absolute Value	On
Success Threshold	1
Warning Threshold	Leave blank
Look Back Window	24 Hours

Band reads: Pass when the total number of rows grows by at least 1 row. Fail when the total number of rows grows by less than 1 row.

Scenario B — Do Not Grow by More Than 10% (Classic Tolerance)

Use this configuration to detect unexpected spikes in incoming data volume.

Control	Value
Direction	Increased By
Operator	≤ (at most)
Use Absolute Value	Off
Success Threshold	10
Warning Threshold	Leave blank

Band reads: Pass when the total number of rows grows by at most 10%. Fail when the total number of rows grows by more than 10%.

Scenario C — Three-Tier Tolerance with Warning

Use this configuration when you want a warning before a hard fail threshold is reached.

Control	Value
Direction	Increased By
Operator	≤ (at most)
Use Absolute Value	Off
Success Threshold	10
Warning Threshold	20

Band reads: Pass when row count grows by at most 10%. Warn when row count grows by more than 10% but at most 20%. Fail when row count grows by more than 20%.

Scenario D — Verify a Purge or Cleanup Job Ran

Use this configuration to validate that a daily cleanup or retention job reduced the row count as expected.

Control	Value
Direction	Decreased By
Operator	≥ (at least)
Use Absolute Value	Off
Success Threshold	10
Warning Threshold	Leave blank

Band reads: Pass when the total number of rows drops by at least 10%. Fail when the total number of rows drops by less than 10%.

Scenario E — Stability Check (Changes by at Most X% in Either Direction)

Use this configuration for tables that should remain stable between runs.

Control	Value
Direction	Changes By
Operator	≤ (at most)
Use Absolute Value	Off
Success Threshold	5
Warning Threshold	10

Band reads: Pass when row count changes by at most 5% in either direction. Warn when it changes by more than 5% but at most 10%. Fail when it changes by more than 10%.

Operator Quick Reference

The table below shows the pass condition for every Direction and Operator combination. M is the measured change; S is the Success Threshold; W is the Warning Threshold.

Direction	Operator	Pass when	Band reads
Increased By	> (greater than)	M > S	grows by more than S
Increased By	= (equals)	M = S	grows by exactly S
Increased By	≠ (not equals)	M ≠ S	grows by anything other than S
Decreased By	≤ (at most)	shrinkage ≤ S	drops by at most S
Decreased By	< (less than)	shrinkage < S	drops by less than S
Decreased By	≥ (at least)	shrinkage ≥ S	drops by at least S
Decreased By	> (greater than)	shrinkage > S	drops by more than S
Decreased By	= (equals)	shrinkage = S	drops by exactly S
Decreased By	≠ (not equals)	shrinkage ≠ S	drops by anything other than S
Changes By	≤ (at most)	\|change\| ≤ S	changes by at most S in either direction
Changes By	< (less than)	\|change\| < S	changes by less than S in either direction
Changes By	≥ (at least)	\|change\| ≥ S	changes by at least S in either direction
Changes By	> (greater than)	\|change\| > S	changes by more than S in either direction
Changes By	= (equals)	\|change\| = S	changes by exactly S in either direction
Changes By	≠ (not equals)	\|change\| ≠ S	changes by anything other than S in either direction

Troubleshooting

"Warning threshold must be greater than Success threshold"

You selected a tolerance operator (≤ or <) and entered a Warning Threshold that is smaller than the Success Threshold. For tolerance operators, the Warning Threshold is the looser bound and must be greater. Raise the Warning Threshold or change the Operator to a directional minimum (≥ or >).

"Warning threshold must be less than Success threshold"

You selected a directional minimum operator (≥ or >) and entered a Warning Threshold that is larger than the Success Threshold. For directional minimum operators, the Warning Threshold is the softer floor and must be smaller. Lower the Warning Threshold or change the Operator to a tolerance type (≤ or <).

"Success threshold must be an integer when unit is Absolute"

The Use Absolute Value toggle is on and you entered a fractional value such as 1.5. Absolute thresholds require a whole number. Change the value to a whole number or turn the toggle off to use a percentage instead.

"Directional delta thresholds are only supported for scalar measurements"

You selected a non-tolerance operator on a ratio-style rule item such as Null Values or Uniqueness Check. The Operator field and Use Absolute Value toggle are only available for scalar measurements: Row Check, Metric Check, and SQL Metric Check. Change the rule type or revert the Operator to ≤.

The rule always passes on the first execution

Relative thresholds require at least one previous execution to establish a baseline. On the first run, no historical data exists, so the rule passes by default. From the second execution onward, the comparison is live. This is expected behavior.

Backward Compatibility

This enhancement is fully backward compatible. All Data Quality policies that used a relative threshold before ADOC v26.6.0 continue to function without modification. The previous implicit behavior — where all relative thresholds used ≤ as the operator — is preserved by default. No migration is required, and no feature flag needs to be enabled.

The new Operator field, Use Absolute Value toggle, and directional minimum options are only applied when explicitly configured on new or edited rules. Existing rules are not affected unless you open and modify them.

Last updated on

Was this page helpful?