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.

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.

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 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:

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.

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.

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.

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

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%".

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: Verify arrival of new records

Ensures cumulative ingestion pipelines add at least one new record per run.

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: Volume spike prevention (tolerance check)

Flags unexpected spikes exceeding 10% growth.

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: Tolerance check with warning band

Provides an early warning before triggering a hard failure.

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 cleanup or purge execution

Validates that a daily retention job reduced the table row count by at least 10%.

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: Metric stability check

Ensures metric stability within ±5% run-over-run.

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.

Troubleshooting

Warning threshold must be greater than success threshold

Cause: A tolerance operator (≤ or <) was selected, but the Warning Threshold is set lower than the Success Threshold.

Resolution: Increase the Warning Threshold or switch to a directional minimum operator (≥ or >).

Warning threshold must be less than success threshold

Cause: A directional minimum operator (≥ or >) was selected, but the Warning Threshold is set higher than the Success Threshold.

Resolution: Decrease the Warning Threshold or switch to a tolerance operator (≤ or <).

Success threshold must be an integer when unit is absolute

Cause: Use Absolute Value is enabled and a decimal value (e.g., 1.5) was entered.

Resolution: Enter a whole integer or turn off Use Absolute Value to evaluate by percentage.

Directional delta thresholds are only supported for scalar measurements

Cause: A directional operator was applied to a ratio-style rule (such as Null Values or Uniqueness Check). Resolution: Change the rule type to a scalar check (Row Check, Metric Check, or SQL Metric Check) or reset the operator to ≤.

Rule always passes on the first execution

Cause: Relative thresholds require at least one prior execution to compute a baseline.

Resolution: No action needed. The rule passes by default on run 1 and performs live comparisons from run 2 onward.

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.